Altering the flow of execution

When debugging, you might want to test a code fix by resetting a variable's value and then rerunning one or more statements. Or you might want to alter the flow of control in the program to ensure that hard to reach code is tested, such as error paths. You can accomplish these tasks using the Jump feature.

The Jump feature lets you transfer control to a statement and then execute that statement. The target statement may be earlier or later in the request than the current statement.

You invoke a jump by right clicking a line in the Source Code window or by using commands. The commands offer additional functionality: jumps to a line number, jumps that are a number of lines relative to the current line, and jumps to lines that contain specified strings.

Manually executing a jump

To perform a jump from a Source Code line to a statement you select:  

1. Right click the target line to which you want to transfer program execution.
   If the target is the first line of an executable statement, the context menu will contain a Jump Here option.  
2. Select Jump Here.
   The Debugger validates this target line, using the rules described below in Jump validation rules. If the target is valid:
   1. Control is immediately transferred to the target statement (intervening statements are not executed).
   2. The target statement executes.
   3. The next executable statement after the target is highlighted, and program execution pauses.

If the target is not valid: control is not transferred, and an Invalid Jump message is displayed in the status bar.

Note: Be aware that the execution of a statement you validly jump to may result in an unexpected request error because the jump bypassed the execution of statements that were logically necessary predecessors to the target statement.

Invoking a jump from a macro or mapped command

The jumpToLine and jumpToMatch commands let you add a jump to a macro or Client button or hot key. With these commands, since you cannot manually select the line to which to jump, you select the target lines by number or by matching a string.

Jumping to a target line by

The jumpToLine command transfers control to a specified request statement within the Source Code page, then executes that statement. You identify the target statement by supplying a keyword or a number:

jumpToLine [current | number] 

For further information about specifying the command, see jumpToLine.

Jumping to a target line by matching a string

The jumpToMatch command transfers control to a request statement within the Source Code tab that contains a specified matching string, then it executes that statement. The target statement is the first statement from the top (first) line in the Source Code page that contains a match for the string you provide.

For further information about specifying the command, see jumpToMatch.

Jump validation rules

A jump operation is allowed if it follows these rules:

• You must have executed at least one statement in the request.
• Jumps are confined to the current nesting level. You may jump within but not into or out of nested code, which includes the following SOUL constructs:  
  • Loops (For, Repeat)  
    
  • Subroutines
    
  • Methods
    
  • On units

For example, once the Client's current line indicator moves from the statement that calls a method into the code that defines the method, any attempted jump to a statement outside the method is invalid. Also, any attempted jump into a method body is invalid.

Note: Although you may not jump out of nested code, you can step out of the current level and resume debugging on the statement following the original call of the nested code.

• The jumpToLine and jumpToMatch commands transfer control only to target statements that are executable.
• The jumpToLine command indicates the target statement absolutely by statement line number or relatively by a number of lines forward or backward from the current line. It is an invalid jump if you absolutely specify the statement line number of an empty line, but it is valid to jump relatively to an empty line (in which case, the jump attempts to go to the line following the empty line).