Using the DebuggerTools class methods - Revision history

Ekern at 03:44, 8 November 2022

2022-11-08T03:44:34Z

Ekern at 20:11, 4 November 2022

2022-11-04T20:11:01Z

← Older revision		Revision as of 20:11, 4 November 2022
Line 7:		Line 7:
	* <span class="f_ListBul1">[[Using the DebuggerTools class methods#Break method\|Break]]</span>		* <span class="f_ListBul1">[[Using the DebuggerTools class methods#Break method\|Break]]</span>
	* <span class="f_ListBul1">[[Using the DebuggerTools class methods#ClientCommand method\|ClientCommand]] </span>		* <span class="f_ListBul1">[[Using the DebuggerTools class methods#ClientCommand method\|ClientCommand]] </span>
	* <span class="f_ListBul1">[[Using the DebuggerTools class methods#~~Command~~ method\|Command]] </span>		* <span class="f_ListBul1">[[Using the DebuggerTools class methods#command method\|Command]] </span>
	* <span class="f_ListBul1">[[Using the DebuggerTools class methods#DebugOff method\|DebugOff]] </span>		* <span class="f_ListBul1">[[Using the DebuggerTools class methods#DebugOff method\|DebugOff]] </span>
	* <span class="f_ListBul1">[[Using the DebuggerTools class methods#StatusMessage method\|StatusMessage]] </span>		* <span class="f_ListBul1">[[Using the DebuggerTools class methods#StatusMessage method\|StatusMessage]] </span>
Line 85:		Line 85:
	<span class="f_Para">where:</span>		<span class="f_Para">where:</span>

	<span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span><span class="f_Para"> is a string expression whose value must be of form: </span>		<p class="syntax"><span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span><span class="f_Para"> is a string expression whose value must be of form: </span>

	<span class="f_Syntax"> [command \| macro] </span><span class="f_Syntax" style="font-style: italic;">clientCommand</span>		<span class="f_Syntax"> [command \| macro] </span><span class="f_Syntax" style="font-style: italic;">clientCommand</span>
			<span class="f_Syntax">%returnedStatus</span><span class="f_Para"> is set to a string containing the message in the Client [[Status bar\|status bar]] that results from the execution of </span><span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span></p>

	<span class="f_Syntax">%returnedStatus</span><span class="f_Para"> is set to a string containing the message in the Client [[glance_at_status_area.html\|status bar]] that results from the execution of </span><span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span>		<span class="term" style="font-family: 'Courier New',Courier,monospace; font-weight: bold;">clientCommand</span><span class="f_Para"> is a [[Client Command Reference\|command]] or [[Using Debugger Macros\|macro]] to execute and includes any parameters. If </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="term"> </span><span class="f_Para">is not qualified by the keyword </span><span class="f_Monospace" style="font-weight: bold;">command</span><span class="f_Para"> or </span><span class="f_Monospace" style="font-weight: bold;">macro</span><span class="f_Para">, the Client searches first for a macro, then for a command. You can use the </span><span class="f_Monospace">command</span><span class="f_Para"> or </span><span class="f_Monospace">macro </span><span class="f_Para">keyword to search exclusively for a command or exclusively for a macro. </span>

	<span class="term" style="font-family: 'Courier New',Courier,monospace; font-weight: bold;">clientCommand</span><span class="f_Para"> is a [[~~client_command_ref.html~~\|command]] or [[~~using_debugger_macros.html~~\|macro]] to execute and includes any parameters. If </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="term"> </span><span class="f_Para">is not qualified by the keyword </span><span class="f_Monospace" style="font-weight: bold;">command</span><span class="f_Para"> or </span><span class="f_Monospace" style="font-weight: bold;">macro</span><span class="f_Para">, the Client searches first for a macro, then for a command. You can use the </span><span class="f_Monospace">command</span><span class="f_Para"> or </span><span class="f_Monospace">macro </span><span class="f_Para">keyword to search exclusively for a command or exclusively for a macro. </span>

	<span class="f_Para">For example: </span>		<span class="f_Para">For example: </span>
Line 99:		Line 97:
	<span class="f_Para">After execution of the above statements, </span><span class="term">%statusMsg</span><span class="f_Para"> contains the string "1 watch item added". </span>		<span class="f_Para">After execution of the above statements, </span><span class="term">%statusMsg</span><span class="f_Para"> contains the string "1 watch item added". </span>

	<span class="f_Notes">It does </span>'''not'''<span class="f_Notes"> pause execution before (or after) it executes a Client command. If you want to produce an execution pause before command execution, use the [[~~using_debuggertools_obj.html~~#~~break_method~~\|Break]] command with a command parameter.</span>		<span class="f_Notes">It does </span>'''not'''<span class="f_Notes"> pause execution before (or after) it executes a Client command. If you want to produce an execution pause before command execution, use the [[Using the DebuggerTools class methods#Break method\|Break]] command with a command parameter.</span>

	=== command method ===		=== command method ===
Line 130:		Line 128:
	<span class="f_CodeExList">CLIENTCOMMAND [command \| macro] </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="f_CodeExList"> </span>		<span class="f_CodeExList">CLIENTCOMMAND [command \| macro] </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="f_CodeExList"> </span>

	<span class="term" style="font-family: 'Courier New',Courier,monospace; font-weight: bold;">clientCommand</span><span class="f_Para"> is a [[~~client_command_ref.html~~\|command]] or [[~~using_debugger_macros.html~~\|macro]] to execute and includes any parameters. If </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="term"> </span><span class="f_Para">is not qualified by the keyword </span><span class="f_Monospace" style="font-weight: bold;">command</span><span class="f_Para"> or </span><span class="f_Monospace" style="font-weight: bold;">macro</span><span class="f_Para">, the Client searches first for a macro, then for a command. You can use the </span><span class="f_Monospace">command</span><span class="f_Para"> or </span><span class="f_Monospace">macro </span><span class="f_Para">keyword to search exclusively for a command or exclusively for a macro. </span>		<span class="term" style="font-family: 'Courier New',Courier,monospace; font-weight: bold;">clientCommand</span><span class="f_Para"> is a [[Client Command Reference\|command]] or [[Using Debugger Macros\|macro]] to execute and includes any parameters. If </span><span class="term" style="font-family: 'Courier New',Courier,monospace;">clientCommand</span><span class="term"> </span><span class="f_Para">is not qualified by the keyword </span><span class="f_Monospace" style="font-weight: bold;">command</span><span class="f_Para"> or </span><span class="f_Monospace" style="font-weight: bold;">macro</span><span class="f_Para">, the Client searches first for a macro, then for a command. You can use the </span><span class="f_Monospace">command</span><span class="f_Para"> or </span><span class="f_Monospace">macro </span><span class="f_Para">keyword to search exclusively for a command or exclusively for a macro. </span>

	<span class="f_Para">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: </span>		<span class="f_Para">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: </span>
Line 141:		Line 139:

	=== DebugOff method ===		=== DebugOff method ===
	<span class="f_Para">The DebugOff shared method turns off debugging for a thread for which debugging was turned on with a </span><span class="f_Monospace">[[~~using_sirius_debug_cmd.html~~\|TN3270 DEBUG ON]]</span><span class="f_Para"> command. It is thus a way to issue a </span><span class="f_Monospace">TN3270 DEBUG OFF</span><span class="f_Para"> command via a method call. </span>		<span class="f_Para">The DebugOff shared method turns off debugging for a thread for which debugging was turned on with a </span><span class="f_Monospace">[[TN3270 DEBUG Syntax\|TN3270 DEBUG ON]]</span><span class="f_Para"> command. It is thus a way to issue a </span><span class="f_Monospace">TN3270 DEBUG OFF</span><span class="f_Para"> command via a method call. </span>

	<span class="f_Para">The DebugOff method takes no arguments and returns a numeric result: </span>		<span class="f_Para">The DebugOff method takes no arguments and returns a numeric result: </span>

	<~~span~~ class="~~f_Syntax~~">%num = %(debuggerTools):DebugOff</~~span~~>		<p class="syntax">%num = %(debuggerTools):DebugOff</p>

	<span class="f_Para">where: </span>		<span class="f_Para">where: </span>

Ekern: Created page with "TOC You can use methods from the DebuggerTools system object in your code to aid in the debugging process in either the Janus Debugger 2022-11-04T00:30:11Z Created page with "TOC You can use methods from the DebuggerTools system object in your code to aid in the debugging process in either the <var>Janus Debugger</va..." New page TOC You can use methods from the DebuggerTools system object in your code to aid in the debugging process in either the <var>Janus Debugger</vavr> or the <var>TN3270 Debugger</var>. The following methods are available: * [[Using the DebuggerTools class methods#AmDebugging method|AmDebugging]] * [[Using the DebuggerTools class methods#Break method|Break]] * [[Using the DebuggerTools class methods#ClientCommand method|ClientCommand]] * [[Using the DebuggerTools class methods#Command method|Command]] * [[Using the DebuggerTools class methods#DebugOff method|DebugOff]] * [[Using the DebuggerTools class methods#StatusMessage method|StatusMessage]] === AmDebugging method === The AmDebugging shared method queries whether or not a User Language program is being run under the <var>Janus Debugger</var> or the <var>TN3270 Debugger</var>. 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: <div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 0 0 6px 30px;"> {| | 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 Syntax#TN3270 DEBUG SUSPEND|TN3270 DEBUG SUSPEND]] command. |- | 1 | The program is running under the <var>Janus Debugger</var> or under the <var>TN3270 Debugger</var>. |} </div> 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|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 Reference|Client command]] or [[Creating and running a macro|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 [[Changing the location of Client work files|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_next_over_run.html#step_over|step over]] * If you have issued a [[running_to_specific_procedure.html|Run Until Procedure]], and the Break call is encountered in a procedure that precedes the "Run Until" procedure * If a [[run_only_to_listed_procs.html|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|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.html|Using breakpoints]]. === ClientCommand method === The clientCommand shared method lets you execute a [[Client Command Reference|command]] or [[Creating and running a macro|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 [[glance_at_status_area.html|status bar]] that results from the execution of commandToSendToClient clientCommand is a [[client_command_ref.html|command]] or [[using_debugger_macros.html|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 [[using_debuggertools_obj.html#break_method|Break]] command with a command parameter. === command method === The command shared method lets you execute a [[TN3270 DEBUG Syntax|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: <div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 0 0 6px 30px;"> {| | 0 | command succeeded. |- | <>0 | command failed. |} </div> 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 [[client_command_ref.html|command]] or [[using_debugger_macros.html|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 [[using_sirius_debug_cmd.html|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: <div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 0 0 6px 30px;"> {| | 0 | <var>TN3270 Debugger</var> debugging was not on when the DebugOff method was invoked. |- | 1 | <var>TN3270 Debugger</var> debugging was on and is now turned off. |} </div> 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|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|Status bar]] from the last interaction with the Client. The StatusMessage method returns a string value: %status = %(DebuggerTools):Statusmessage [[Category:Debugger Home]]

← Older revision		Revision as of 03:44, 8 November 2022
Line 58:		Line 58:
	<span class="f_Para">The Break method will </span>'''not'''<span class="f_Para"> break execution in the following cases: </span>		<span class="f_Para">The Break method will </span>'''not'''<span class="f_Para"> break execution in the following cases: </span>

	* <span class="f_ListBul1">If it is invoked in a routine or method that you have elected to [[~~step_next_over_run.html~~#~~step_over~~\|step over]] </span>		* <span class="f_ListBul1">If it is invoked in a routine or method that you have elected to [[Step, Step Over, and Run#Step Over\|step over]] </span>
	* <span class="f_ListBul1">If you have issued a [[~~running_to_specific_procedure.html~~\|Run Until Procedure]], and the Break call is encountered in a procedure that precedes the "Run Until" procedure </span>		* <span class="f_ListBul1">If you have issued a [[Running to a specific procedure\|Run Until Procedure]], and the Break call is encountered in a procedure that precedes the "Run Until" procedure </span>
	* <span class="f_ListBul1">If a [[~~run_only_to_listed_procs.html~~\|white list]] is enabled, and the Break method is contained in a procedure that is not on the white list </span>		* <span class="f_ListBul1">If a [[Running only to listed procedures\|white list]] is enabled, and the Break method is contained in a procedure that is not on the white list </span>

	<span class="f_Para">This code fragment includes a Break method invocation: </span>		<span class="f_Para">This code fragment includes a Break method invocation: </span>
Line 74:		Line 74:
	<span class="f_Para">You can also use the DebuggerTools ClientCommand method to execute a Client command; it does so without an execution break. </span>		<span class="f_Para">You can also use the DebuggerTools ClientCommand method to execute a Client command; it does so without an execution break. </span>

	<span class="f_Para">For more information about breakpoints, see [[~~using_breakpoints.html~~\|Using breakpoints]]. </span>		<span class="f_Para">For more information about breakpoints, see [[Using breakpoints\|Using breakpoints]]. </span>

	=== ClientCommand method ===		=== ClientCommand method ===
Line 81:		Line 81:
	<span class="f_Para">The clientCommand method takes one string argument and returns a string: </span>		<span class="f_Para">The clientCommand method takes one string argument and returns a string: </span>

	<span class="f_Syntax">%returnedStatus = %(DebuggerTools):ClientCommand(</span><span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span><span class="f_Syntax">)</span>		<p class="syntax"><span class="f_Syntax">%returnedStatus = %(DebuggerTools):ClientCommand(</span><span class="f_Syntax" style="font-style: italic;">commandToSendToClient</span><span class="f_Syntax">)</span></p>

	<span class="f_Para">where:</span>		<span class="f_Para">where:</span>
Line 152:		Line 152:

	{\|		{\|
	\| <span class="f_DefListTerm">0</span>		\| <span class="f_DefListTerm">'''0'''</span>
	\| <var>TN3270 Debugger</var><span class="f_DefListDD"> debugging was not on when the </span><span class="f_Para">DebugOff </span><span class="f_DefListDD">method was invoked. </span>		\| <var>TN3270 Debugger</var><span class="f_DefListDD"> debugging was not on when the </span><span class="f_Para">DebugOff </span><span class="f_DefListDD">method was invoked. </span>
	\|-		\|-
	\| <span class="f_DefListTerm">1</span>		\| <span class="f_DefListTerm">'''1'''</span>
	\| <var>TN3270 Debugger</var><span class="f_DefListDD"> debugging was on and is now turned off. </span>		\| <var>TN3270 Debugger</var><span class="f_DefListDD"> debugging was on and is now turned off. </span>
	\|}		\|}