Commands

The following table provides a summary of all the available commands.

Command

Description

breakpoint

Set a breakpoint on a node.

For more information, see Breakpoint.

delete

Remove a breakpoint or a watchpoint.

For more information, see Delete.

end

Terminate the debug session

For more information, see End.

eval

Evaluate an expression.

For more information, see Eval.

execute

Execute commands from a file.

For more information, see Execute.

goto

Transfer control to a specific node.

For more information, see Goto.

help

List commands or give help on specific command.

For more information, see Help.

list

Display flow anatomy.

For more information, see List.

rerun

Rerun the flow with the same parameters as the last run command.

For more information, see Rerun.

resume

Continue execution from the current location.

For more information, see Resume.

run

Run a flow.

For more information, see Run.

save

Save the debugger state or the contents of the current document to a file.

For more information, see Save.

set

Set a register, edge, current document, current source, or the current thread.

For more information, see Set.

shell

Execute an iWay Service Manager console command.

For more information, see Shell.

show

Display a value, such as threads, registers, etc.

For more information, see Show.

step

Execute a single node. With step into, start debugging a subflow.

For more information, see Step.

suspend

When the flow is running, suspend execution at the next node.

For more information, see Suspend.

watchpoint

Set a watchpoint to detect a change in register value, an edge returned or an edge about to be followed.

For more information, see Watchpoint.


Top of page

x
Reference: Breakpoint

Syntax: breakpoint [-source <source>] <node> [-inedge|-outedge] [-count <count>|-if <expr>]

A breakpoint is an instruction to suspend the execution of the flow at a specific node.

The source identifies which flow contains the node. The format is:

channelname:|channelname:flowname | flowname

The default is the current source.

An inedge breakpoint stops before the node is executed. This is the default. An outedge breakpoint stops after the node has been processed but before the returned edges have been dispatched. For a service node, an inedge breakpoint suspends execution before the pre-registers are set and an outedge breakpoint suspends execution after the post-registers are set.

The count option suspends execution only after the breakpoint is reached that many times. When the breakpoint triggers, the count is reset to zero. This is useful for nodes in iterations.The conditional boolean expression suspends execution only if it returns true when evaluated. The expression has access to the current document and special registers.

The count option and the boolean expression cannot be used together. When the count and the expression are absent, the breakpoint suspends execution unconditionally.

With no arguments, the breakpoint command lists all defined breakpoints like show breakpoints.

The debugger assigns a breakpoint id to the new breakpoint. The id has the format bNNNN where NNNN is a unique monotonically increasing number. The id can be used later to refer to the breakpoint, for example to delete it.

Examples:


Top of page

x
Reference: Delete

Syntax:

Removes a breakpoint or a watchpoint. Interactively, deleting with the id is sufficient. In the longer forms, -inedge is the default and the default scope is local. These forms might be more convenient in a script (see the execute command).

Examples:

delete b1
delete breakpoint Node1 -outedge
delete watchpoint reg1
delete watchpoint -source file1:testflow -edge fail_connect

Top of page

x
Reference: End

Syntax: end

The debug session is terminated. Beforehand, the threads launched by the debugger are aborted. In configuration testing mode, breakpoints and watchpoints are removed, and paused threads originally launched by channels are resumed.


Top of page

x
Reference: Eval

Syntax: eval [-thread <thread>] <expr>

The eval command evaluates an iFL expression in the context of a thread. The default is the current thread. The evaluator has access to the current document and the special registers.

If no thread is specified and there is no current thread, then the expression must not require a document.

Examples:

eval _XPATH(/INVOICE/INVOICE-NUMBER)
eval _sreg(reg1)+_sreg(reg2)

Top of page

x
Reference: Execute

Syntax: execute <filename>

The file is used as a source of input commands. The commands are in the same format as commands entered at the command line. Blank lines and lines that start with # are considered comments and are ignored.

Files created by the save state command are compatible with the execute command. In this way the state of the debugger can be restored from an earlier session.

When preparing scripts expected to last across releases, it is wise to avoid using abbreviated syntax as new commands may later make the abbreviation ambiguous. Similarly, avoid use of specific id's (threads, breakpoints…) as these may change from run to run.

Sample script:

# sample script
shell start file1
set source file1:testflow
breakpoint SetReg1 shell start iqueue1
set source iqueue1:qflow watchpoint -edge OnError

Example:

execute c:\script.txt

Top of page

x
Reference: Goto

Syntax: goto <node> [-inedge|-outedge]

Specify the next node to be executed in the current flow. The debugger will jump to the target node and pause, allowing an opportunity to set the document, registers, etc. By default, the debugger jumps to the inedge of the node and sets the input edge to OnSuccess. The -outedge option jumps to the outedge of the node without executing the processing stage. It also sets the returned edges to OnSuccess. The input edge or returned edges can be modified with the set command before execution is resumed.

Example:

goto SetReg1
goto 'Is Default?' -outedge

Top of page

x
Reference: Help

Syntax: help [<command>]

Give help on a specific command. List all commands if the command name is absent.

Examples:

help
help breakpoint

Top of page

x
Reference: List

Syntax: list [<depth>] [-source <source>] [-node <node>]

List the nodes and the edges between them. Specify the maximum depth displayed with an integer. This is useful for large process flows. The default is to display all nodes.

The source identifies which process flow is listed. The format is:

channelname:|channelname:flowname | flowname

The default is the current source.

The listing starts at the identified node. If the source is specified, the default node is the start node, otherwise the default node is the current node within the current source.

The output has one line per node. The outgoing edges are listed underneath, indented one level to the right. The format is edgename -> nodename.

The debugger reads the compiled version of the flow. Some small differences in the shape of the flow may be visible compared to iIT. This is due to the flow compilation.

Sample Output:

Node Start in source file1:testflow
  OnCompletion -> SetReg1
    OnSuccess -> 'Is Default?'
      true -> Default
        OnSuccess -> End
      false -> NotDefault
        OnSuccess -> End

The second line says there is an OnCompletion edge from the Start node to the SetReg1 node. Lower down, the 'Is Default?' node has two out edges: true and false. That is because they appear at the same indentation level, which is one level to the right of 'Is Default?'.

Examples:

list
list 1
list -source file1:testflow -node 'Is Default?'

Top of page

x
Reference: Rerun

Syntax: rerun

Runs a flow using the same parameters as the last run command. The flow is rerun from the beginning but side effects of the flow, such as a file having been updated or a message sent to an external source, will not be rolled back. The rerun command uses the original input, even if the input came from a file and the file has been modified since then.


Top of page

x
Reference: Resume

Syntax: resume [<thread>|-all]

Execution continues from the breakpoint on the active or identified thread. The option -all causes all paused threads to be resumed.

Examples:

resume
resume t4
resume -all

Top of page

x
Reference: Run

Syntax: run [[-source <source>] [-suspend] [-error] [[-bytes|-string|-xml] (-file <filename>|<input>)]

Run a process flow. The source identifies the process flow. The format is:

channelname:|channelname:flowname | flowname

The default is the current source.

The -suspend option causes the debugger to pause the flow before the Start node. By default, the flow executes normally.

The -error option marks the input document as in error. The default is not in error. The -bytes, -string, and -xml options specify the format of the input document. The default is XML format.

The contents of the document can be read from a file or directly on the command line. When not specified, the default document is <default/>. The encoding is UTF-8.

Examples:

run
run -source file1:testflow
run -file doc.xml
run -xml <root/>
run -string sample text

Top of page

x
Reference: Save

Syntax:

Information is saved to a file for later use.

The save document command saves the payload of the identified document to a file. The current document of the specified thread is used. When omitted, the current document of the current thread is used. The output can later be used by the set document or run commands.

The save state command saves the current breakpoint and watchpoint settings into a file. The file can later be executed with the execute command to restore the state of the debugging session.

Examples:

save document doc.xml
save state breakpoints.txt

Top of page

x
Reference: Set
Syntax:

Set changes either a value or a debugger setting.

The set document command sets the current document on the identified thread. The default is the current thread. The -error option marks the input document as in error. The default is not in error. The -bytes, -string and -xml options specify the format of the input document. The default is XML format. The contents of the document can be read from a file or directly on the command line. When not specified, the default contents is <default/>. The encoding is UTF-8.

The set edges command sets the returned edges of the current node on the identified thread. The default is the current thread. The value is a comma-separated list of one of more edges. This command is enabled only when the thread is paused at the outedge of a node. The dispatch stage will match these returned edges against the outedges to determine which edges are followed.

The set inedge command sets the inedge of the current node on the identified thread. The default is the current thread. The value is a single edge name. This command is enabled only when the thread is paused at the inedge of a node. The inedge is usually immaterial to the execution of the node except for iterator nodes. The inedge called $jump means this is an iteration, any other name means it is the initial entry.

The set register command creates or modifies a special register. The register exists in the context of the identified thread. The default is the current thread. The default scope is local. The register type can be user, hdr or doc. The default is user. Header registers are serialized during emit operation to the proper header type for the protocol. Setting the register type applies during register creation only. An existing register will keep its register type. The reg token is the register name and the rest of the input is the iFL expression that will be evaluated before the result is assigned.

The set source command specifies the current source. The format is:

channelname:|channelname:flowname | flowname

The default is the current source.

This becomes the default value for the source in other debugger commands.

The set thread command specifies the current thread. This becomes the default value for the thread in other debugger commands.

Examples:

set document -xml <root/>
set document -file doc.xml
set edges OnSuccess
set edges fail_redirection,303
set inedge $jump
set register reg1 _sreg(reg2)+3
set register -hdr User-Agent iWay Service Manager
set source file1:testflow
set source channel1:inlet.1:File.1:testflow
set source sysflow
set thread t4

Top of page

x
Reference: Shell

Syntax: shell <shellcommand>

Run a server command without leaving the debugger. The remainder of the command line is passed directly to the iSM command executor.

The commands are not interactive - that is, a command that depends on a prior command may not work as expected. Generally, the restrictions on the commands are the same as those that apply to commands executed by the schedule provider. See the console commands guide for further information.

Example:

shell set debug off -m file1
shell start file1
shell info
shell show flows

Top of page

x
Reference: Show

Syntax:

The show command without arguments displays the current location in the current thread.

The show breakpoint command displays the configured breakpoints.

The show document command displays the current document of the identified thread. The default is the current thread. If there are no active threads, the debugger will display the output document generated by the last flow started by the run or rerun command. By default, an XML document is pretty-printed. The -noindent option displays the XML document without extra indentation. The -offset option is an integer for the number of characters or bytes to skip from the beginning. The -maxlen option is an integer for the maximum number of characters or bytes to process starting from the offset. The attachments option displays the attachments associated with a multipart document.

The show edges command displays the inedge or the returned edges of the current node of the identified thread. The default is the current thread. The inedge is shown when paused on the inedge side of the node, or the returned edges when paused on the outedge side of the node.

The show node command displays the type, parameters and outedges of a specific node. The default is the current node of the current source. The format of the source is:

channelname:|channelname:flowname | flowname

The show registers command displays the values of special registers accessible from the identified thread at the specified scope. The default is the current thread at the thread scope. If a register patternis entered, only registers with a name that match are shown. In the pattern, ? matches one character and * matches 0 or more characters. If the type is specified, only registers of that type are displayed. The -inherit option causes registers from higher scopes to be inherited unless they are redefined at a more local scope. This is the default and the usual behavior at runtime. The -noinherit option disables the inheritance and only shows registers defined locally within that scope. The scope can be one of: channel, flow, global, local, manager, master, message, session, server, system, thread, or worker. The -hierarchy option displays all the registers grouped by scope, starting from the specified scope. The default is -noinherit when the -hierarchy option is used.

The show source command displays the current source.

The show threads command displays the active threads. The arrow => indicates the current thread.

Examples:

show
show breakpoints
show document -noindent -offset 2000 -maxlen 500
show edges -thread t5
show node SetReg1
show registers
show registers reg1
show registers ns.*
show registers -scope worker
show registers -hierarchy
show source
show threads

Top of page

x
Reference: Step

Syntax: step [-thread <thread>] [into|nearest]

The step command executes the current node in the identified thread. The default is the current thread. If the thread is paused on the inedge of the node, both the processing and dispatching stages are executed. If the node is paused on the outedge of the node, only the dispatch is executed.

The step into command is identical to the step command except when the thread is paused on the inedge of a call to a subflow, in which case it will step into the subflow and pause on the start node instead. When paused on the outedge of the node (including a call to a subflow), the node is already processed, therefore step into is the same as step.

The step nearest command suspends at the nearest inedge or outedge location. If the thread is paused on the inedge of a node, it will process it and suspend at the outedge of the node. When paused at the outedge of a node, the step nearest command is identical to the step command. This command executes one stage of the node. It takes two step nearest commands to execute the node completely.This is particularly useful to process the node and inspect the returned edges before dispatch.

Examples:

step
step into
step nearest
step -thread t4

Top of page

x
Reference: Suspend

Syntax: suspend [-thread <thread>] [-cancel]

Suspend execution of the identified thread. The default is the current thread. The execution may stop at the outedge of the current node or the inedge of the next node. The thread can be resumed.

With the -cancel option, the debugger does a best effort to cancel the flow as soon as possible. The thread cannot be resumed. If the thread is in the running state, the debugger sends a cancel request to the current node. If the node is a service capable of cancellation, it will abort the processing immediately. If the thread is in the waiting state, the entire flow is cancelled, along with any subflows it might have been waiting for completion.

Examples:

suspend
suspend -cancel
suspend -thread t4

Top of page

x
Reference: Watchpoint

Syntax:

A watchpoint is an instruction to stop the execution of the flow at any location when an event that satisfies some condition is detected.

The first form declares a watchpoint that triggers when the value of a special register changes. The source and scope specifies where that register was created. The scope can be one of: channel, flow, global, local, manager, master, message, session, server, system, thread, or worker. The default is the current source and the local scope. The debugger will break on the outedge of the node that modified the special register. This node does not have to be in the same source, it could be in a subflow for example. In the case of a register at server scope, it could be any thread.

The second form declares a watchpoint that triggers when an edge is detected. By default, the watchpoint will match edges returned by the node, even if not followed. Optionally, it will match only edges that are actually followed.

The conditional boolean expression suspends execution only if it returns true when evaluated. The expression has access to the current document and special registers.

Examples:

watchpoint reg1
watchpoint -scope channel reg1
watchpoint reg1 -if _sreg(reg1)==100
watchpoint -edge OnError 11

iWay Software