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) Referencing and updating variable values while debugging
(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.

When executing the last line of the job definition script, the symbol () indicating completion of debugging process appears.
To stop the job definition script that is being executed, select Debug > Stop Script menu or click the Stop Script button on the tool bar.

Continues the command whose execution is underway when the Stop Script button is clicked and stops the job definition script 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.

(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.

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.
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.

To Page Top

(3) Referencing and updating variable values while debugging

The variable name and value of the variable are updated and displayed in the Variable window when the job definition script stops.

You can change the field value by selecting the variable range. You can return a field value to the value before editing by pressing the Esc key while editing the value.

For a variable of the read only attribute, the variable name and value of the variable are displayed in a light color. In this case, the value of variable cannot be changed.

If you attempt to set a value other than an integer value to a variable that is declared as an integer type, the value will return to the previous value. In addition, 0 is set when you specify null character.

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.21 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.

Fault Injection Mode is enabled with this.

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.

Cautions

If you specify FUNCTION for the CMDRC_CMDGRP_CHECK parameter, the fault injection mode cannot be disabled in the function even by selecting Debug > Fault Injection Mode while the function is stopped.

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:

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