Using the DebuggerTools class methods
You can use methods from the DebuggerTools system object in your code to aid in the debugging process in either the Janus Debugger</vavr> or the TN3270 Debugger.
The following methods are available:
AmDebugging method
The AmDebugging shared method queries whether or not a User Language program is being run under the Janus Debugger or the TN3270 Debugger.
The method takes no arguments, and it returns a numeric result:
%num = %(DebuggerTools):AmDebugging
where:
%num is a numeric variable that can be either of these:
| 0 | The program is not running under either Debugger. This includes the case where the program runs after debugging is suspended by a TN3270 DEBUG SUSPEND command. |
| 1 | The program is running under the Janus Debugger or under the TN3270 Debugger. |
AmDebugging lets you insert code that runs only when debugging, as in the following example:
b if (%(DebuggerTools):AmDebugging) then print 'extra debugging information' end if * normal processing .....
Break method
The Break shared method pauses execution on the statement that follows the Break method specification. If your request is not being run under the Debugger, the Break method does nothing which lets you leave it in code. It essentially has the same effect as using the Debugger Client to put a breakpoint on the statement that would follow the Break method call.
The Break method has one, optional, argument:
%statusMsg = %(DebuggerTools):Break[(command)]
where:
%statusMsg is a string that contains the message in the Client status bar that results from the execution of command. If the request containing the method is not running in the Debugger, %statusMsg contains a "break is ignored" message.
command is a string expression (case not important) that contains the Client command or macro to be executed immediately following the break in execution. The command or macro in the string may be preceded by the keyword Command or Macro.
If command is not qualified by the keyword Command or Macro, the Debugger Client searches first for a macro named command, then for a Client command named command. You can use the Command or Macro keyword to search exclusively for a specified command or exclusively for a specific macro. The macro search is restricted to the Client installation folder or the designated macro folder.
The Break method will not break execution in the following cases:
- If it is invoked in a routine or method that you have elected to step over
- If you have issued a Run Until Procedure, and the Break call is encountered in a procedure that precedes the "Run Until" procedure
- If a white list is enabled, and the Break method is contained in a procedure that is not on the white list
This code fragment includes a Break method invocation:
%status is longstring %status = %(DebuggerTools):break('clearWatch') * Break, execute the clearWatch command, and pause * (awaiting instruction to execute the next statement) %x = 666
When a Break method pauses execution, DebuggerTools:break hit is displayed in the Status bar of the Debugger Client (except, if Break executes a command, the effect of the command is displayed).
You can also use the DebuggerTools ClientCommand method to execute a Client command; it does so without an execution break.
For more information about breakpoints, see Using breakpoints.
ClientCommand method
The clientCommand shared method lets you execute a command or macro from within a SOUL request. If your request is not being run under the Debugger, the clientCommand method harmlessly takes no action.
The clientCommand method takes one string argument and returns a string:
%returnedStatus = %(DebuggerTools):ClientCommand(commandToSendToClient)
where:
commandToSendToClient is a string expression whose value must be of form: [command | macro] clientCommand %returnedStatus is set to a string containing the message in the Client status bar that results from the execution of commandToSendToClient
clientCommand is a command or macro to execute and includes any parameters. If clientCommand is not qualified by the keyword command or macro, the Client searches first for a macro, then for a command. You can use the command or macro keyword to search exclusively for a command or exclusively for a macro.
For example:
%statusMsg is longstring
%statusMsg = %(DebuggerTools):clientCommand('addWatch %x')
After execution of the above statements, %statusMsg contains the string "1 watch item added".
It does not pause execution before (or after) it executes a Client command. If you want to produce an execution pause before command execution, use the Break command with a command parameter.
command method
The command shared method lets you execute a TN3270 DEBUG command within a SOUL request, that is, as a statement. It takes one argument and returns a numeric value:
%rc = %(DebuggerTools):command(string)
where:
%rc is set to indicate success or failure:
| 0 | command succeeded. |
| <>0 | command failed. |
string is a string expression whose value specifies which TN3270 DEBUG subcommand to execute. It may be one of the following:
- The term OFF, SUSPEND, RESUME, or STATUS.
- The term ON, followed by the additional parameters required by the TN3270 DEBUG ON command.
- The term CLIENTCOMMAND, followed by a blank, followed by its argument "clause":
CLIENTCOMMAND [command | macro] clientCommand
clientCommand is a command or macro to execute and includes any parameters. If clientCommand is not qualified by the keyword command or macro, the Client searches first for a macro, then for a command. You can use the command or macro keyword to search exclusively for a command or exclusively for a macro.
In the following example, the method turns debugging on for the next procedure that runs; the Janus client port and Debugger Client workstation are specified:
%rc = %(DebuggerTools):command('ON DEBSOCK 198.242.444.234')
In this example, it a user interface command to the Client:
%rc = %(DebuggerTools):command('CLIENTCOMMAND AddWatch %i')
DebugOff method
The DebugOff shared method turns off debugging for a thread for which debugging was turned on with a TN3270 DEBUG ON command. It is thus a way to issue a TN3270 DEBUG OFF command via a method call.
The DebugOff method takes no arguments and returns a numeric result:
%num = %(debuggerTools):DebugOff
where:
%num is a numeric variable that can be either of these:
| 0 | TN3270 Debugger debugging was not on when the DebugOff method was invoked. |
| 1 | TN3270 Debugger debugging was on and is now turned off. |
When debugging is on and a DebugOff method executes, debugging stops immediately, the Client/Online connection is broken, Online has disconnected is displayed in the Status bar of the Debugger Client, and the request completes at the Online thread.
StatusMessage method
The StatusMessage shared method contains the message in the Client Status bar from the last interaction with the Client. The StatusMessage method returns a string value:
%status = %(DebuggerTools):Statusmessage