4.4.6 Debugging

Checking the behavior of a job definition script file is called debugging.

This is equivalent to the adshexec command with the -d option specified. The console is displayed while debugging is being performed. Error messages are displayed in the Error List window.

There are two ways to perform debugging:

Method	Operation	Overview
Execution	From the Debug menu, select Run to Breakpoint.	Starts and restarts execution up to a breakpoint.
Step-by-step execution	From the Debug menu, select Step In.	Executes one line of the job definition script, and then stops execution. If a function is called, the editor also executes one line in the function and stops execution.
	From the Debug menu, select Step Over.	Executes one line of the job definition script and then stops execution. If a function is called, the editor does not stop after executing a single line in the function, but stops only when a breakpoint is reached.
	From the Debug menu, select Step Out.	Stops on the line immediately following a function call or at a breakpoint.

Notes:

If you attempt to debug a job definition script file that does not yet have a name, the Save As dialog box for specifying a name for the file and saving it will be displayed. A file cannot be debugged until it is saved with a new job definition script file name (.ash).
If the contents of the job definition script file have changed, a message asking whether the file is to be updated is displayed. If you update the file, you can then debug it.
If the editor is forcibly terminated during debugging (because, for example, End now is selected in the Exit the Program dialog box), the debugger's adshesub.exe process might keep running and the console might remain displayed. If this happens, terminate the adshesub.exe process with the taskkill command or from the task manager.

Organization of this subsection

(1) Setting and releasing breakpoints during debugging
(2) Performing and canceling debugging
(3) Adding variables to the watch list
(4) Simulating errors
(5) Executing the trap command's action

(1) Setting and releasing breakpoints during debugging

You set breakpoints at locations where you want execution to stop temporarily during debugging. You can also release breakpoints that have been set.

Because JP1/Advanced Shell Editor sets a breakpoint at the line where the cursor is located, breakpoints cannot be set in external scripts. Even if breakpoints have already been set in an external script, execution will not stop at such breakpoints. You can set a maximum of 999 breakpoints.

(a) Setting breakpoints

To set a breakpoint:

Move the cursor to the line where you want to set a breakpoint.
From the Debug menu, select Set Breakpoint.

A breakpoint is set at the line where the cursor is located. The symbol is displayed on the left end of the line to indicate that a breakpoint has been set. The job definition script executes up to, but not including, the line where the breakpoint is set and then stops.

(b) Removing a breakpoint

To remove a breakpoint:

Move the cursor to the line where a breakpoint is to be removed.
From the Debug menu, select Remove Breakpoint.

The breakpoint is removed from the line where the cursor is located.

(c) Removing all breakpoints

To remove all breakpoints:

Display a job definition script in which breakpoints are set.
From the Debug menu, select Remove All Breakpoints.

All breakpoints are removed from the displayed job definition script file.

Notes:

You can set a breakpoint at any line while you are in the edit mode. In the debug mode, a breakpoint can be set only on a line for a command or a statement that is to be executed.
If a breakpoint is set on a non-execution line, the editor searches downwards in the script file for an appropriate location for a breakpoint and sets a breakpoint on that line when the debug mode begins.
You can set a maximum of 999 breakpoints.

To Page Top

(2) Performing and canceling debugging

(a) Debugging up to a breakpoint

To debug up to a breakpoint:

From the Debug menu, select Run to Breakpoint, or on the toolbar, click the Run to Breakpoint button.

JP1/Advanced Shell Editor is placed in the debug mode and begins debugging. A symbol () indicating the next location to be executed is displayed to the left of the corresponding line. Comment lines and lines containing only spaces are ignored.

Execution stops temporarily when the script has executed through the line preceding a line on which a breakpoint () is set.

For details about how to set breakpoints, see (1) Setting and releasing breakpoints during debugging.
To cancel debugging, from the Debug menu, select Quit Debugging, or on the toolbar, click the Quit Debugging button.

The editor stops debugging when this selection is made, displays a message, performs postprocessing, and then terminates debugging. The editor terminates debugging without stopping even if the end of the process has not been reached, and returns to the edit mode.

(b) Executing one line at a time (performing step-by-step execution in functions)

To execute one line at time and perform step-by-step execution in functions:

From the Debug menu, select Step In, or on the toolbar, click the Step In button.

The editor is placed in the debug mode and begins debugging. A symbol () indicating the next location to be executed is displayed to the left of the corresponding line. Comment lines and lines containing only spaces are ignored. The editor also executes only one line at a time inside functions. When the job definition script has been executed through the last line, a symbol () indicating the end of the debugger process is displayed.

Unlike CUI, when an external script is executed, execution does not stop within the external script. Execution stops when it reaches the next command in the job definition script being displayed by the editor.
To cancel debugging, from the Debug menu, select Quit Debugging, or on the toolbar, click the Quit Debugging button.

The editor stops debugging when this selection is made, displays a message, performs postprocessing, and then terminates debugging. The editor terminates debugging without stopping even if the end of the process has not been reached, and returns to the edit mode.

(c) Executing one line at a time (not performing step-by-step execution in functions)

To execute one line at a time and not perform step-by-step execution in functions:

From the Debug menu, select Step Over, or on the toolbar, click the Step Over button.

The editor is placed in the debug mode and begins debugging. A symbol () indicating the next location to be executed is displayed to the left of the corresponding line. Comment lines and lines containing only spaces are ignored. When the job definition script has been executed through the last line, a symbol () indicating the end of the debugger process is displayed.

Unlike CUI, when an external script is executed, execution does not stop within the external script. Execution stops when it reaches the next command in the job definition script being displayed by the editor.
To cancel debugging, from the Debug menu, select Quit Debugging, or on the toolbar, click the Quit Debugging button.

The editor stops debugging when this selection is made, displays a message, performs postprocessing, and then terminates debugging. The editor terminates debugging without stopping even if the end of the process has not been reached, and returns to the edit mode.

(d) Executing through the end of a function

To execute through the end of a function:

From the Debug menu, select Step Out, or on the toolbar, click the Step Out button.

The editor is placed in the debug mode and begins debugging. A symbol () indicating the next location to be executed is displayed to the left of the corresponding line. Comment lines and lines containing only spaces are ignored. When the job definition script has been executed through the last line, a symbol () indicating the end of the debugger process is displayed.

Unlike CUI, execution continues through the end of the job definition script even when control is not inside a function. However, if there is a breakpoint before control is returned from the function, execution stops.
To stop executing the job definition script, from the Debug menu, select Stop Script, or on the toolbar, click the Stop Script button.

The command whose execution is underway when the Stop Script button is clicked is completed, and the job definition script stops before the next command is executed.
To cancel debugging, from the Debug menu, select Quit Debugging, or on the toolbar, click the Quit Debugging button.

The editor stops debugging when this selection is made, displays a message, performs postprocessing, and then terminates debugging. The editor terminates debugging without stopping even if the end of the process has not been reached, and returns to the edit mode.

(e) Error List window, Watch List window, and console during debugging

Error List window

Analysis and execution errors detected during debugging are displayed in the Error List window. The values of variables added to the Watch List window are updated and displayed when execution stops.

For details about the Error List window, see 4.7.4 Error List window.
Watch List window

The values of the variables displayed in the Watch List window are updated and displayed when execution of the job definition script stops. To display the Watch List window, while the job definition script is not running, select Show Watch List from the View menu or click the Show Watch List button on the toolbar. You can select this menu item only while the job definition script is not running. Double-clicking a variable name in the Watch List window displays the Edit Value dialog box, where you can update the variable's value.

For details about the Watch List window, see 4.7.6 Watch List window. For details about how to specify settings in the Edit Value dialog box, see 4.7.8 Edit Value dialog box.
Console

During debugging, information equivalent to the standard output, standard error output, and job execution logs is output to the console. The console is displayed while a process executing a job definition script is running and closes when the process terminates. While a job definition script is executing, the console is active; while a job definition script is stopped, the editor is active.

To Page Top

(3) Adding variables to the watch list

To add a variable to the Watch List window:

In the debug mode, from the Debug menu, select Add Variable to Watch List.

The Add to Watch List dialog box is displayed.

For details about how to specify a setting in this dialog box, see 4.7.7 Add to Watch List dialog box.
Enter a name for the variable that you want to add.

You can enter a maximum of 99 bytes. A variable name longer than 99 bytes cannot be entered.
Click the Add button.

The entered variable name is added to the Watch List window.
Click the Cancel button.

The Add to Watch List dialog closes.

In the debug mode, selecting a character string in the client area of the JP1/Advanced Shell Editor window, and then selecting Debug and then Add Variable to Watch List, sets the selected character string in Variable name.
To delete an added variable from the Watch List window, right-click the variable name and select the Delete from List menu item.

To Page Top

(4) Simulating errors

The C1 execution percentage rate might not be 100%, even when all execution paths have executed. This situation occurs when no job step or command that results in an error precedes the job step of the #-adsh_step_start command.

In such a case, if you simulate an error at a location preceding the #-adsh_step_start command, the C1 information indicating errors in the preceding job steps or job definition scripts can be acquired, thus achieving a 100% C1 execution percentage rate. For details about the behavior of a job definition script when the fault injection mode is enabled, see 6.2.20 Enabling and disabling the fault injection mode (joberrmode command).

To simulate an error:

Move the cursor to a row in which you want to simulate an error and set a breakpoint.

For details about how to set breakpoints, see (1) Setting and releasing breakpoints during debugging.
Perform debugging up to the line in which you intend to simulate an error.

Perform debugging up to the breakpoint set in step 1. Debugging stops temporarily at the breakpoint. For details about how to perform debugging up to a breakpoint, see (2) Performing and canceling debugging.
From the Debug menu, select Fault Injection Mode.

The Fault Injection Mode menu item can be selected only when the job definition script is stopped for a reason such as a breakpoint.

The fault injection mode is enabled and a check mark is displayed to the left of the Fault Injection Mode menu item, as shown below.

If you restart debugging in this status, an error is simulated and C1 information is acquired.

To release the fault injection mode, select the Fault Injection Mode item again before you restart debugging.
Restart debugging.

By stepping in, stepping over, stepping out, or executing up to the breakpoint, the editor is placed in the debug mode and debugging resumes.

When debugging is completed through the last line of the job definition script, the fault injection mode is released.

To Page Top

(5) Executing the trap command's action

You use the trap command's action to define an operation that is to be performed when the job controller has received a forced termination request.

To execute the trap command's action during debug execution:

Start debug execution, and then stop the job definition script at any line after the trap action is defined.

For details about how to perform debug execution, see (2) Performing and canceling debugging.
Stop the job definition script at a desired line by using a method such as breakpoints.

For details about how to set breakpoints, see (1) Setting and releasing breakpoints during debugging.
From the Debug menu, select Execute a trap action.

The Execute a trap action menu item can be selected only when the job definition script is stopped by a means such as breakpoints.

Once the menu item is selected, the job definition script is run up to the breakpoint. In this case, the commands are executed in the following order:

1) Current command located on the line where execution is stopped

2) Commands in the action part

3) Commands following the command in step 1

If DISABLE is specified in the TRAP_ACTION_SIGTERM environment setting parameter or no action by the trap command has been defined and this menu is selected, JP1/Advanced Shell runs the job definition script up to the next breakpoint without executing the trap command's action.

Notes

The job definition script cannot be stopped while the trap command's action is executing.
If the job is terminated while the action by this function is underway, the termination code of the last command executed is applied as the job's termination code, unlike when the job is terminated forcibly. For example, if action exit 2 is executed by using this function, the job is terminated with termination code 2. On the other hand, if the job is terminated forcibly and then action exit 2 is executed, the job is terminated with error and termination code 1.
After this menu is selected, if execution of the command that immediately follows is skipped, the action will not be executed.^#1

#1

For example, execution of a command is skipped in the following cases:

The fault injection mode is enabled.
A command inside a job step for which stop was specified for the onError attribute terminates with an error.

To Page Top