SDAPI Script Threads 2.0

A script thread is a container for a running script. When a Script Pipelet or Controller Script is called, a script thread is created representing the script file. A script thread is either 'running' or 'halted'. If the script thread is halted, a stack frame is created representing the entry point of the script. For every function that is subsequently called, a new stack frame is created and added to the script's call stack. When function is exited, the stack frame is removed from the call stack.

The script thread's call stack is a zero-based index where element 0 represents the current location of the script execution path.

To interact with script threads, you must first create a breakpoint and then you must call a Controller or a Pipeline that runs the script. When the Script Engine encounters a breakpoint, the script thread is halted. When a script thread is halted, you can use actions to:
  • Fetch variables based on script thread and stack frame index. See Object Members for more information.
  • Evaluate expressions based on script thread and stack frame index. See Object Members for more information.
  • Control the execution of the script by stepping into a function, stepping out of a function, stepping over the current line, resuming scripts, and stopping script threads. See Object Members for more information.
Important: By default, a script thread can be halted for up to 60 seconds without reseting the timeout counter. Each time you reset the timeout counter, you have another 60 seconds to interact with the thread. If you do not reset the timeout counter, the script engine throws a ScriptDebuggerTerminate error in the script that was halted. See Example 3 for the syntax for resetting timeout counters.

In the vast majority of cases, you do not want to interact with a “running” script thread, because there is no guarantee that the thread will be alive when your request is processed.

Examples

Example 1: Get all script threads


REQUEST:
GET /s/-/dw/debugger/v1_0/threads HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
{
  "_v":"2.0",
  "script_threads":[
  {
    "call_stack":[
    {
      "index":0,
      "location":
      {
        "function_name":"first()",
        "line_number":25,
        "script_path":"/app_storefront_controllers/cartridge/scripts/models/CartModel.js"
      }
    },
    {
      "index":1,
      "location":
      {
        "function_name":"execute()",
        "line_number":12,
        "script_path":"/app_storefront_controllers/cartridge/controllers/Cart.js"
      }
    }],
  "id":2,
  "status":"halted"
  }
 ]
}
   

Example 2: Get a specific script thread


REQUEST:
GET /s/-/dw/debugger/v1_0/threads/2 HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
{
  "_v":"2.0",
    "call_stack":[
    {
      "index":0,
      "location":
      {
        "function_name":"first()",
        "line_number":25,
        "script_path":"/app_storefront_controllers/cartridge/scripts/models/CartModel.js"
      }
    },
    {
      "index":1,
      "location":
      {
        "function_name":"execute()",
        "line_number":12,
        "script_path":"/app_storefront_controllers/cartridge/controllers/Cart.js"
      }
    }],    
  "id":2,
  "status":"halted"
}
   

Example 3: Reset script thread timeout counter for all halted threads


REQUEST:
POST /s/-/dw/debugger/v1_0/threads/reset HTTP/1.1
RESPONSE:
HTTP/1.1 204 No Content