SoftSpy commands and macros: Difference between revisions

Revision as of 22:54, 20 March 2014

Introduction

This topic describes all SoftSpy commands and all SoftSpy macros that function as commands. The SoftSpy commands and macros described in this topic are entered on the SoftSpy command line, or are used within SoftSpy macros. The commands entered at Model 204 command level that are used to turn SoftSpy on and off are also described in this topic.

The macro facility within SoftSpy is very powerful. You effectively add new commands to SoftSpy by writing macros to perform new functions. Many of the most powerful facilities within SoftSpy are built using macros. Refer to the Macro Listings topic to see practical examples of how the macro facility was used to provide many capabilities described here.

SoftSpy commands perform a variety of functions including:

Stepping through the evaluation of a User Language request statement by statement.
Setting break points within a request and executing until a break point is encountered.
Examining the source code of a request (with all includes expanded) with a comprehensive set of scrolling commands.
Displaying variable, field, global, and parameter values.
Displaying statistics including server table usage and performance related statistics like page reads, disk reads, disk writes, and cpu time used. These statistics can be shown on a statement by statement basis.
Defining and manipulating windows containing statistics, variables, fields, globals, or parameters in order to monitor them on an ongoing basis.
Assigning frequently used commands to program function keys.
Tailoring SoftSpy by using macros to define new commands which consist of a series of other commands.
Obtaining help using a comprehensive hypertext based on‑line facility.
Administering SoftSpy including defining the privileges of individual users within the SoftSpy environment.
Printing the contents of any SoftSpy screen or window.

Lists of commands by functional area

The tables that follow group SoftSpy commands into major functional areas. A brief description is included with each command.

Basic commands

Command	Function
AUDIT	Establish the interactive audit environment.
DEBUG	Establish the interactive debugging environment.
HELP	Request SoftSpy help information.
QA	Establish the interactive quality assurance testing environment.
QUIT	Quit the current SoftSpy function or cancel the current User Language request.
REPEAT	Repeat the last command entered on the command line.
RETRIEVE	Recall a previously entered command.
SPY AUDIT OFF	Deactivate the SoftSpy audit feature.
SPY AUDIT ON	Activate the SoftSpy audit feature.
SPY OFF	Terminate a SoftSpy session.
SPY ON	Start a SoftSpy session.
SPY ON THREAD	Start a SoftSpy server session to debug another User Language thread.
SPY ON USER	Start a SoftSpy server session to debug another User Language thread.
TUNE	Establish the interactive performance tuning environment.

Interactive execution commands

Command	Function
BREAK	Set a break point.
BREAKS	Set break points following User Language request lines that contain *BREAK.
CLEAR BREAK	Clear break points.
DEFAULT LINE	Indicate whether to focus on the last statement executed or the next statement to execute.
GO	Start or resume evaluation of a User Language request until an interrupt or a user-specified condition occurs.
QUAD	Make the current statement the statement containing the specified quad offset.
STEP	Start or resume evaluation of a User Language request for a specified number of statements or until an interrupt occurs.
TRACER	Start or resume evaluation of a User Language request and print a trace of statements executed.
UL CONTINUE	Advance the execution position to the next iteration of a FOR or REPEAT loop.
UL JUMP TO LABEL	Advance the execution position to a statement label or statement number and execute that statement.
UL JUMP TO LINE	Advance the execution position to a line and execute the first statement on the line.
UL LOOP END	Exit a FOR or REPEAT loop and execute the statement following the end of the loop.
UL RESULT	Alter the behavior of a statement that makes a flow of control decision.
UL RETURN	Return immediately from a subroutine and execute the statement following the CALL to the subroutine.

Operand display and manipulation commands

Command	Function
COLLECT	Initiate the collection of statistic_operand and usage_operand data, statement by statement, during User Language request evaluation.
COVERAGE	Display test coverage information about the current User Language request.
DISPLAY	Display operands.
GLOBALS	Watch all currently defined global variables.
SET	Alter the value of an operand.
SHOW	Add columns to the source window that display statistic, usage, quality assurance, or compilation operands by line.
STATS	Watch all statistic_operands and usage_operands.
UNCOLLECT	Terminate data collection and discard collected data.
UNSHOW	Remove columns from the source window.
UNWATCH	Remove operands from a watch window.
WATCH	Display operands in a watch window.

Scrolling commands

Command	Function
BACKWARD	Scroll backward in the active window.
BOTTOM	Scroll to the bottom of the active window.
FORWARD	Scroll forward in the active window.
LAST	Scroll backward in the execution history of the current User Language request.
LEFT	Scroll to the left in the active window.
LOCATE	Find a character string in the active window.
NEXT	Scroll forward in the execution history of the current User Language request.
RIGHT	Scroll to the right in the active window.
SCROLL	Scroll in the source window based on user-specified criteria.
TOP	Scroll to the top of the active window.

Print commands

Command	Function
CLOSE PRINTER	Close the destination for print output.
DEFAULT PRINTER	Set the default destination and parameters for print output.
NEW PAGE	Begin a new page.
OPEN PRINTER	Open a destination for print output.
PRINT ACL	Print an access control list.
PRINT HELP	Print SoftSpy help information.
PRINT LINE	Print a line.
PRINT LIST	Print a list of access control lists or macros.
PRINT MACRO	Print a macro.
PRINT WINDOW	Print the contents of a window.

Window commands

Command	Function
ACTIVE WINDOW	Set the active window.
CLOSE WINDOW	Close a window and remove it from the screen.
DEFINE WINDOW	Define a window.
DELETE WINDOW	Delete a window definition.
IN WINDOW	Temporarily alter the active window while a command is executed.
OPEN WINDOW	Display a window on the screen.
SCREEN	Change the layout of the SoftSpy screen by ordering the screen elements (such as borders and messages).

Advanced commands and commands used in macros

Command	Function
comment	Document macros.
COMMAND	Dynamically build and execute a command.
DATETIME	Control display of the date and time.
DEFINE softspy_variable	Define a softspy_variable.
DELETE softspy_variable	Delete a softspy_variable.
ERROR	Issue an error message.
IF	Conditionally execute a command.
JUMP TO	Branch to a different location in a macro.
M204	Execute a Model 204 command.
ON	Establish a command to execute whenever processing of User Language request causes a specified condition to occur.
PF	Assign a command to a program function key.
RETURN	Terminate a macro and return to the point of invocation.
SPY softspy_command	Issue SoftSpy commands from the Model 204 command line.
TRANSFER	Transfer control to a command from a macro.

Macro commands

Command	Function
BROWSE MACRO	Browse a macro.
COPY MACRO	Copy a macro.
DELETE MACRO	Delete a macro.
EDIT MACRO	Create or edit a macro.
EXEC	Execute a macro.
LIST MACRO	Display a list of macros.
RENAME MACRO	Rename a macro.
SAVE MACRO	Save a macro and continue editing.
TRACE	Produce a debugging trace when macros are run.

Administrative commands

Command	Function
BROWSE ACL	Browse an access control list.
COPY ACL	Copy an access control list.
DELETE ACL	Delete an access control list.
EDIT ACL	Create or edit an access control list.
EDIT CONFIG	Edit the SoftSpy configuration.
LIST ACL	Display a list of access control lists.
RENAME ACL	Rename an access control list.
SAVE ACL	Save an access control list and continue editing.
SAVE CONFIG	Save the SoftSpy configuration and continue editing.
SPY SERVER	Start a SoftSpy server.

SoftSpy command descriptions

The following sections describe each SoftSpy command in detail.

comment

Function	Document macros.
Syntax	* `comment_text`
Description	The comment command is used in macros to provide documentation. Comment commands are not executed; they merely provide descriptive information. Multi-line comments can be constructed by using several comment statements in a row. The asterisk used to initiate a comment must be the first non-blank character on the line.
Examples	* * `This is a comment.` * ********************************* * * * `Comments can be written` * * `in many styles` * * * *********************************

ACTIVE WINDOW

Function	Set the active window.
Syntax	ACTIVE WINDOW [ `window_identifier` ]
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The ACTIVE WINDOW command sets the window in which subsequent commands are executed. The `window_identifier` specifies which window to make active. It can be the SOURCE window or a window opened with the OPEN WINDOW command. If the `window_identifier` does not specify an open window, an error message is issued and the active window is not changed. The active window changes to another open window if no `window_identifier` is used. ACTIVE WINDOW can thus be used repeatedly to cycle through all open windows. A highlighted equal sign (=) character is used as the border character for the active window. A dim hyphen (-) character is used is the border character for all other windows. The BACKWARD, BOTTOM, FORWARD, LEFT, LOCATE, PRINT WINDOW, RIGHT, and TOP commands all operate in the context of the active window. The UNWATCH and WATCH commands operate in the context of the default watch window. The default watch window is the same as the active window unless the active window is the source window.

Examples	ACTIVE WINDOW ACTIVE WINDOW SOURCE ACTIVE WINDOW MONITOR ACTIVE WINDOW GLOBALS
See Also	$ACTIVE_WINDOW, $DEFAULT_WATCH_WINDOW, IN WINDOW

AUDIT

Function	Establish the interactive audit environment.
Syntax	AUDIT
Restrictions	The context must be EVAL and the audit option is required.
Description	The AUDIT macro is used to switch to the interactive audit environment, or to reinitialize the interactive audit environment. The lines of User Language requests are prefixed with brackets showing the statement nesting level and the cumulative QTBL usage in bytes for each line. A monitor window in which operands can be watched is placed in the upper right corner of the screen. The default line is set to the next executable statement. Any data collection is terminated and any collected data is discarded.

Audit screen

12 of 16 Next 1 SoftSpy for Model 204 20 JUL 2012 11:45:26 IN AEYPROC I TESN.LOGIN SUBSYSTEM DEMO ============================================================================= CMPL NEST QTBL == 20 CALL MAIN MONITOR == 52 %X = $SETG('NEXT','EXIT') == 52 == / 68 MAIN: SUBROUTINE == | 88 CALL DIVIDE.LOOP == \ 96 END SUBROUTINE MAIN == 96 == / 112 DIVIDE.LOOP: SUBROUTINE == |/ 172 FOR %I FROM 10 TO 0 BY 1 => || 220 %J = 10 / %I == |\ 224 END FOR == \ 232 END SUBROUTINE DIVIDE.LOOP == 232 == 276 END => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=QUAD 12=RETRIEVE

The audit environment can be customized on an individual user basis. The AUDIT macro looks for a macro named userid_AUDIT, where userid is your user id. If such a macro is found, it is automatically run by the AUDIT macro in order to customize the audit environment.

See the description of the audit environment for a complete description of the facilities available when using the interactive audit environment.

Examples

AUDIT

See Also

AUDIT environment, DEBUG, QA, TUNE

BACKWARD

Function

Scroll backward in the active window.

Syntax

{ BACKWARD | - } [ FULL | HALF | n | ERROR ]

Description

The BACKWARD command scrolls backward the distance specified in the active window. It allows the display of data preceding the portion visible in the window by moving data downward.

When FULL is used the distance scrolled is the full height of the window. FULL is the default. The line preceding the first line displayed in the active window becomes the last line displayed. The new center line becomes the current line. If there are not enough preceding lines to permit this movement, the first line becomes the current line.

When HALF is used the distance scrolled is half the height of the window. The line preceding the first line displayed in the active window becomes the current line. If no preceding lines exist, the first line becomes the current line.

When an integer is used the current line in the active window moves backward the specified number of lines. If there are not enough preceding lines, the first line becomes the current line.

ERROR scrolls backward to the previous statement that caused a compilation error. Searching begins with the line preceding the current line. The first line of the first executable statement found containing an error becomes the current line. If no errors are found, a warning message is issued and the current line remains unchanged. If ERROR is used and the active window is not the source window, an error message is issued and the current line remains unchanged.

The active window can be temporarily altered for the duration of the BACKWARD command by prefixing it with the IN WINDOW command.

Examples	BACKWARD - BACKWARD 100 -HALF BACKWARD ERROR IN WINDOW SOURCE -ERROR
See Also	FORWARD

BOTTOM

Function	Scroll to the bottom of the active window.
Syntax	BOTTOM
Description	The BOTTOM macro scrolls to the last line of data available in the active window. The last line becomes the current line. The active window may be temporarily altered for the duration of the BOTTOM macro by prefixing it with the IN WINDOW command.
Examples	BOTTOM
See Also	TOP

BREAK

Function	Set a break point.
Syntax	BREAK
Restrictions	The context must be EVAL.
Description	The BREAK command is used to set a break point on the current line in the source window, provided that the current line is executable. The letter "B" is placed in the prefix area of the line to indicate that a break point is set on the line. If the line is not executable, an error message is issued and no break point is set. Lines that are not executable include continuation lines, comment lines, screen definition statements, and other types of declare statements. An error message is also issued if a break point is already set on the line. As an alternative to issuing a BREAK command, a "B" prefix command can be entered directly into the prefix area of a source statement line.
Examples	BREAK
See Also	BREAKS, CLEAR BREAK

BREAKS

Function	Set break points following User Language request lines that contain *BREAK.
Syntax	BREAKS
Restrictions	The context must be EVAL.
Description	The BREAKS macro scans the source program from the line following the current line to the end of the source program for lines containing BREAK. Whenever BREAK is found, a break point is set on the next executable statement. If no line containing BREAK is found, the current line in the source window is left unchanged, and the error message 'NO BREAK POINTS REQUESTED' is displayed. If break points are requested and successfully set, the current line in the source window is set to the last line on which a break point was set. If a break point cannot be set on the next executable statement following BREAK, the current source window line is set to the first such line, and an error message is issued.
Examples	BREAKS
See Also	BREAK, CLEAR BREAK

BROWSE ACL

Function	Browse an access control list.
Syntax	BROWSE ACL `access_control_list_identifier`
Restrictions	The READ ACL privilege is required.
Description	The BROWSE ACL command is used to browse an access control list. The `access_control_list_identifier` parameter specifies the access control list to browse. If the specified access control list does not exist, an error message is issued. Otherwise, the browse environment is entered. See the description of the browse environment for a complete description of the facilities available when browsing an access control list.

BROWSE ACL Screen

1 of 15 SoftSpy for Model 204 01 SEP 2012 12:00:00 BROWSE ACL ADMIN ============================================================================== ALAN DAVID DAPHNE GEORGEC GEORGEW JEN JOEL JOHN KAREN MARCIA MICHAEL STEVE SUE SYLVIA TOM => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Examples	BROWSE ACL ADMIN
See Also	BROWSE environment, EDIT ACL

BROWSE MACRO

Function	Browse a macro.
Syntax	BROWSE MACRO `macro_identifier`
Restrictions	The READ MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
Description	The BROWSE MACRO command is used to browse a macro. The `macro_identifier` parameter specifies the macro to browse. If the specified macro does not exist, an error message is issued. Otherwise, the browse environment is entered. See the description of the browse environment for a complete description of the facilities available when browsing a macro.

BROWSE MACRO Screen

25 of 50 SoftSpy for Model 204 01 SEP 2012 12:00:00 BROWSE MACRO DISPLAY_WATCH ============================================================================= SET $I = $CURSOR_LINE('SOURCE') IF $I EQ 0 THEN SET $I = $CURRENT_LINE('SOURCE') DEFINE $TEXT STRING LEN 255 LOCAL SET $TEXT = $SOURCE_LINE_DATA('TEXT',$I) DEFINE $OPERAND STRING LEN 255 LOCAL DEFINE $RIGHT_PAREN STRING LEN 1 LOCAL SET $RIGHT_PAREN = ')' DEFINE $DELIMITERS STRING LEN 25 LOCAL SET $DELIMITERS = ',<>?/''"{}\+=-()*& ' DEFINE $CHAR STRING LEN 1 LOCAL OPERAND_LOOP: SET $I = $INDEX($TEXT,'%') IF $I EQ 0 THEN JUMP TO DISPLAY_WATCH SET $TEXT = $SUBSTR($TEXT,$I) SET $I = $MATCH($TEXT,$DELIMITERS) IF $I THEN JUMP TO OPERAND_DELIMITER => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Examples	BROWSE MACRO PROFILE
See Also	BROWSE environment, EDIT MACRO

CLEAR BREAK

Function	Clear break points.
Syntax	CLEAR BREAK [ ALL ]
Restrictions	The context must be EVAL.
Description	The CLEAR BREAK command is used to clear break points. All break points are cleared if the ALL parameter is specified, otherwise only the break point on the current line in the source window is cleared. If ALL is not specified and a break point is not set on the current line in the source window, an error message is issued. The letter "B" is removed from the prefix area of all source statement lines affected by CLEAR BREAK. A break point may also be cleared by removing the "B" from the prefix area of a source statement line. This can be accomplished by clearing the prefix area or by typing a blank or another prefix character over the "B".
Examples	CLEAR BREAK CLEAR BREAK ALL
See Also	BREAK, BREAKS

CLOSE PRINTER

Function	Close the destination for print output.
Syntax	CLOSE PRINTER
Description	The CLOSE PRINTER command closes the currently open destination for print output. If there is no currently open destination an error message is issued. After the CLOSE PRINTER command is issued subsequent print output is sent to the default print destination.
Examples	CLOSE PRINTER
See Also	OPEN PRINTER

CLOSE WINDOW

Function	Close a window and remove it from the screen.
Syntax	CLOSE WINDOW `window_identifier`
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The CLOSE WINDOW command closes a window and removes it from the screen. The `window_identifier` parameter specifies the name of the window to close. If an open window name is not specified, an error message is issued. Closing a window removes it from the screen. Source statement lines covered by the window become visible. The SOURCE window may not be closed. If the active window is closed, the SOURCE window becomes the new active window.
Examples	CLOSE WINDOW MONITOR CLOSE WINDOW STATS CLOSE WINDOW GLOBALS
See Also	OPEN WINDOW

COLLECT

Function	Initiate collection of `statistic_operand` and `usage_operand` data by statement during User Language request evaluation.
Syntax
Restrictions	Context must be COMPILE_ERROR or EVAL.
Description	The COLLECT command is used to initiate collection of statistic_operand or usage_operand data. Detailed statement by statement information is gathered showing the cumulative evaluation time net change in the requested statistic and usage operands. This statement level data can be accessed with the $SOURCE_LINE_INFO function, or can be displayed in the source window using the SHOW command. Once collection is initiated, it continues until terminated with an UNCOLLECT command. Subsequent COLLECT commands initiate the collection of additional statistic or usage operands. In order to ensure consistency in collected data, a COLLECT command is rejected with an error if data has already been collected within the current request. In this situation you must either wait until the beginning of the next request, or issue an UNCOLLECT command to clear all collected data first. A new request is initiated by the Model 204 BEGIN and MORE commands. If averages or the `quality_assurance_operands` TESTED, UNTESTED, or TEST_STATUS are required, EXECOUNT `statistic_operand` must be collected. There are restrictions on which operands can be collected based on which optional SoftSpy features are available. The description of each operand identifies restrictions on its use. If an operand cannot be collected, an error message is issued, and collection is not initiated. The optional `statistic_operand` qualifiers of LOGIN, SPY, EVAL, or STMT must be omitted or an error message will be issued. They are not meaningful for data collection.
Examples	COLLECT EXECOUNT COLLECT DKRD, CCATEMP COLLECT VTBL COLLECT CPU, CNCT
See Also	SHOW, UNSHOW, UNCOLLECT

COMMAND

Function	Dynamically build and execute a command.
Syntax	COMMAND `expression`
Description	The COMMAND command is used to dynamically build and execute a SoftSpy command. The `expression` is evaluated to produce a command. The command is then dynamically executed. If the result of the `expression` is not KNOWN, an error message is issued. The dynamically built command can be a COMMAND command. However, at most ten levels of recursively built COMMAND commands are allowed. If this limit is exceeded an error message is issued.
Examples	COMMAND 'FORWARD ' WITH $COMMAND COMMAND 'DISPLAY ' WITH $MACRO_ARGS COMMAND 'CLOSE WINDOW ' WITH $DEFAULT_WATCH_WINDOW COMMAND 'DISPLAY F.''' WITH $COMMAND WITH ''''

COPY ACL

Function	Copy an access control list.
Syntax	COPY ACL `access_control_list_identifier` TO [ACL] `access_control_list_identifier`
Restrictions	The UPDATE ACL privilege is required.
Description	The COPY ACL command copies an access control list. The first access_control_list_identifier specifies the name of the access control list to copy. If the specified access control list does not exist, an error message is issued. The second access_control_list_identifier specifies the name of the new access control list to create. If an access control list already exists with this name, an error message is issued. The keyword ACL must proceed the new access control list name if it is ACL.
Examples	COPY ACL ADMIN TO OLD_ADMIN COPY ACL ADMIN TO ACL OLD_ADMIN

COPY MACRO

Function	Copy a macro.
Syntax	COPY MACRO `macro_identifier` TO [ MACRO ] `macro_identifier`
Restrictions	The READ MACRO privilege is required unless the name of the macro to be copied begins with the user's id followed by an underscore. The UPDATE MACRO privilege is required unless the new macro name begins with the user's id followed by an underscore.
Description	The COPY MACRO command copies a macro. The first `macro_identifier` specifies the name of the macro to copy. If the specified macro does not exist, an error message is issued. The second `macro_identifier` specifies the name of the new macro to create. If a macro already exists with this name, an error message is issued. The keyword MACRO must proceed the new macro name if it is MACRO.
Examples	COPY MACRO PROFILE TO OLD_PROFILE COPY MACRO PROFILE TO MACRO OLD_PROFILE

COVERAGE

Function	Display test coverage information about the current User Language request.
Syntax	COVERAGE [ GO ]
Restrictions	The context must be EVAL and the quality assurance testing option is required.
Description	A message is displayed showing the number of statements that have been tested and the total number of statements that are reachable in the current User Language request. The message also identifies the number of unreachable or dead statements in the request. The message is of one of the following forms:
	All `num` reachable statements tested, no unreachable statements All `num1` reachable statements tested, `num2` unreachable statements `num1` of `num2` reachable statements tested, no unreachable statements `num1` of `num2` reachable statements tested, `num3` unreachable statements If the context is not EVAL or the EXECOUNT statistic option is not being collected, then an error message is issued and the message is not displayed. If the GO option is specified, a GO command is issued before the message is displayed unless evaluation of the current User Language request was already completed.
Examples	COVERAGE COVERAGE GO

DATETIME

Function	Control display of the date and time.
Syntax	DATETIME { OFF \| ON }
Description	The DATETIME command controls whether or not the date and time are displayed in the upper right corner on SoftSpy screens. They are initially displayed by default. DATETIME OFF indicates the date and time should not be displayed. DATETIME ON indicates the date and time should be displayed.
Examples	DATETIME OFF DATETIME ON

DEBUG

Function	Establish the interactive debugging environment.
Syntax	DEBUG
Restrictions	The context must be EVAL and the interactive debugging option is required.
Description	The DEBUG macro is used to switch to the interactive debugging environment, or to reinitialize the interactive debugging environment. The lines of User Language requests are prefixed with brackets showing the statement nesting level. A monitor window in which operands can be watched is placed in the upper right corner of the screen. The default line is set to the next executable statement. Any data collection is terminated and any collected data is discarded.

DEBUG Screen

1 of 20 Next 1 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG12 ============================================================================= NEST => BEGIN ----------MONITOR---------- == %TOTALQTY IS FIXED > $UPDATE=0 - == - - == * FIND ALL CURRENT ORDERS - - == FDORD: - - == IN CLIENT1 FDWOL ZIP_CODE IS I - - == FROM '02190' TO '02190' - - == END FIND - - == - - == /------- FOR EACH RECORD IN FDORD - - == |/------ IF DATE_PURCHASED > %DATE THEN - - == || %CURRENT = %CURRENT + 1 --------------------------- == |>------ ELSE == || %HISTORY = %HISTORY + 1 == |\------ END IF => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

	The debugging environment can be customized on an individual user basis. The DEBUG macro looks for a macro named userid_DEBUG, where userid is your user id. If such a macro is found, it is automatically run by the DEBUG macro in order to customize the debugging environment.
	See the description of the debug environment for a complete description of the facilities available when interactively debugging a User Language request.
Examples	DEBUG
See Also	DEBUG Environment, AUDIT, QA, TUNE

DEFAULT LINE

Function	Indicate whether to focus on the last statement executed or the next statement to execute.
Syntax	DEFAULT LINE { LAST \| NEXT }
Restrictions	The context must be EVAL.
Description	The DEFAULT LINE command indicates whether to focus on the LAST statement executed or the NEXT statement to execute. It is usual to focus on the next statement to execute when debugging because you can easily see which statement will be executed next. In the case of performance tuning, it is usual to focus on the last statement executed because statistic values include that statement. The focus specified by DEFAULT LINE takes effect immediately and remains in effect until it is reset. Changing the focus changes the current line, the execution point display at the top of the evaluation screen, and the position in the history of executed statements. The behavior of subsequent STEP and GO commands is similarly affected by the focus. If LAST is specified then the current line is positioned at the first line of the last statement executed. The execution point indicator at the top of the evaluation screen shows the line number of the last statement executed in the current request. If no statements have yet been executed it indicates LAST NONE. The current position in the history of executed statements is set to the last statement executed. If NEXT is specified then the current line is positioned at the first line of the next statement to be executed. The execution point indicator at the top of the evaluation screen shows the line number of the next statement to execute in the current request. If no statements remain to execute it indicates NEXT NONE. The current position in the history of executed statements is set to the next statement to execute.
Examples	DEFAULT LINE LAST DEFAULT LINE NEXT
See Also	GO, LAST, NEXT, STEP

DEFAULT PRINTER

Function	Set the default destination and parameters for print output.
Syntax
Description	The DEFAULT PRINTER command alters the default destination for print output. Various aspects of the format of print output can also be controlled. The initial default print destination is the TERMINAL. The output destination is not actually opened. The OPEN PRINTER command can be used to explicitly open the print destination, or individual PRINT commands may implicitly open and close the default print destination. The print destination may be a DATASET, PRINTER, PUNCH, or the TERMINAL. The TERMINAL option takes no arguments. The other destination options require conformance with the syntax of the Model 204 USE command. In addition, SoftSpy supports two additional parameters for these destinations. A parameter of CCC=`n` can be specified, where `n` is the desired continuation column setting. Similarly, a parameter of LPP=`n` can be specified, where `n` is the desired number of lines per page.
Examples	DEFAULT PRINTER TERMINAL DEFAULT PRINTER OUT1 DEFAULT PRINTER PUNCH PUNCH1 DEFAULT PRINTER DATASET REPORT DEFAULT PRINTER PRINTER WITH ROUTER=VM,ID=GEORGE
See Also	OPEN PRINTER

DEFINE `SoftSpy_variable`

Function	Define a `SoftSpy_variable`.
Syntax
Description	The DEFINE command defines a `SoftSpy_variable` operand. `SoftSpy_variable` operands must be defined before being referenced. The name of the `SoftSpy_variable` may be up to twenty characters long. The first character must be a dollar sign. Subsequent characters may be alphabetic, numeric, or the underscore. The `SoftSpy_variable` must be defined as either type STRING or type FIXED. It should be defined as type STRING if it will contain character string values. In this case a maximum character string length in the range 1 to 255 must be specified. It should be defined as FIXED if it will contain numeric integer values. String variables are initialized to a null string. Fixed variables are initialized to zero. The `SoftSpy_variable` can be defined with a scope of LOCAL or SESSION. LOCAL is the default, and indicates that the `SoftSpy_variable` is only accessible within the macro in which it is defined. SESSION indicates that the `SoftSpy_variable` has no accessibility restrictions. SESSION must be specified if a DEFINE command is issued outside a macro. `SoftSpy_variables` with LOCAL scope are automatically deleted when the macro they were defined within terminates. `SoftSpy_variables` with SESSION scope exist for the duration of the SoftSpy session. Any `SoftSpy_variable` can be explicitly deleted sooner with the DELETE `SoftSpy_variable` command. A `SoftSpy_variable` can be defined with SESSION scope if it is not already defined with SESSION scope, or with LOCAL scope within the currently executing macro. A `SoftSpy_variable` can be defined with LOCAL scope if it is not already defined with LOCAL scope within the currently executing macro.
Examples	DEFINE $TEMPF IS STRING LEN 6 DEFINE $L IS FIXED DEFINE $MACRO_NAME STRING LEN 18 LOCAL DEFINE $TEMP STRING LEN 255 SESSION DEFINE $END_EVAL_SCROLL_TOP FIXED SESSION
See Also	DELETE SoftSpy_variable

DEFINE WINDOW

Function	Define a window.
Syntax
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The DEFINE WINDOW command is used to define a SoftSpy window. The `window_identifier` names the window. It must not specify the name of a window that is already defined, or an error message is issued. Once a window is defined the OPEN WINDOW command may be used to display the window on the terminal. The COLUMN keyword is followed by a `left_column` parameter specifying a window's first column, the word TO, and a `right_column` parameter specifying a window's last column. The `left_column` must be greater than or equal to six. The `right_column` must be less than or equal to 77 and at least two larger than the `left_column`. Columns adjacent to a window are reserved for screen format control. If the COLUMN parameter is omitted then it will be required when the window is opened. The ROW keyword is followed by a `top_line` parameter specifying a window's top line, the word TO, and a `bottom_line` parameter specifying a window's bottom line. The `top_line` must be greater than or equal to one. The `bottom_line` must be less than or equal to 16 minus the number of title lines created by SHOW commands, and at least two larger than the `top_line`. If the ROW parameter is omitted then it will be required when the window is opened. The WATCH parameter identifies operands to watch in the window.
Examples	DEFINE WINDOW MONITOR ROW 1 TO 12 COLUMN 51 TO 77 DEFINE WINDOW GLOBALS DEFINE WINDOW STATS WATCH (CPU, DKPR) DEFINE WINDOW INFO COLUMN 50 TO 77 DEFINE WINDOW WATCH COLUMN 50 TO 77 ROW 1 TO 6
See Also	DELETE WINDOW, OPEN WINDOW

DELETE ACL

Function	Delete an access control list.
Syntax	DELETE ACL `access_control_list_identifier`
Restrictions	The UPDATE ACL privilege is required.
Description	The DELETE ACL command deletes an access control list. The `access_control_list_identifier` specifies the name of the access control list to delete. If the specified access control list does not exist, an error message is issued.
Examples	DELETE ACL ADMIN

DELETE MACRO

Function	Delete a macro.
Syntax	DELETE MACRO `macro_identifier`
Restrictions	The UPDATE MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
Description	The DELETE MACRO command deletes a macro. The `macro_identifier` specifies the name of the macro to delete. If the specified macro does not exist, an error message is issued.
Examples	DELETE MACRO OLDPROFILE

DELETE SoftSpy_variable

Function	Delete a Softspy variable.
Syntax	DELETE `SoftSpy_variable` [ LOCAL \| SESSION ]
Description	The DELETE `SoftSpy_variable` command deletes the designated SoftSpy variable. The variable must have been previously defined with the DEFINE `SoftSpy_variable` command. The scope of LOCAL or SESSION specified on the DELETE command must match the scope specified on the DEFINE command. If it does not match then an error message is issued and the variable is not deleted. A variable with a scope of LOCAL can only be deleted from within the macro in which it was defined. A variable with a scope of SESSION may not be deleted from within a macro that has a LOCAL variable defined with the same name.
Examples	DELETE $L DELETE $TEMPO LOCAL DELETE $TUNE_PF10 SESSION
See Also	DEFINE softspy_variable

DELETE WINDOW

Function	Delete a window definition.
Syntax	DELETE WINDOW `window_identifier`
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The DELETE WINDOW command deletes a window definition. The `window_identifier` specifies the name of the window definition to delete. The window must have been defined with the DEFINE WINDOW command, or an error message is issued. A window definition can be deleted even if the window is open.
Examples	DELETE WINDOW MONITOR DELETE WINDOW STATS DELETE WINDOW GLOBALS
See Also	CLOSE WINDOW, DEFINE WINDOW

DISPLAY

Function

Display operands.

Syntax

DISPLAY operand [ , operand ]...

Description

The DISPLAY command is used to display one or more operands and their values on the message line. The operand parameters specify the operands to display. All SoftSpy operands are supported, including statistics, parameters, globals, variables, and fields.

An operand is displayed in one of three formats. The display formats and their meanings are as follows:

Display Format	Meaning
`operand`=`value`	The operand value is known and the value of the operand does not contain leading or trailing blanks. If the operand is boolean then the value is shown as 1 if it is true and as 0 if it is false.
`operand`='`value`'	The `operand` value is known and the value of the `operand` contains leading or trailing blanks.
`operand` is `result`	The `operand` value is not known. The result is invalid, not available, not present, undefined, or unknown.

Examples

DISPLAY %NEXT
DISPLAY CPU
DISPLAY FREESIZE(METADATA)
DISPLAY UDDLPP
DISPLAY %X, %Y, DIRRCD
DISPLAY G.UDDLPP
DISPLAY $UPDATE

See Also

SHOW, WATCH

EDIT ACL

Function

Create or edit an access control list.

Syntax

EDIT ACL access_control_list_identifier

Restrictions

The UPDATE ACL privilege is required.

Description

The EDIT ACL command creates or edits an access control list. The access_control_list_identifier specifies the name of the access control list to edit. If the specified list does not exist, a new access control list with the name specified is created.

The SAVE ACL command must be used to save any changes. The editing session is terminated with the QUIT command.

EDIT ACL Screen

1 of 14 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT ACL ADMIN ===== ======================================================================= ====> ALAN ===== DAVID ===== DAPHNE ===== GEORGEC ===== GEORGE2 ===== JEN ===== JOEL ===== JOHN ===== KAREN ===== MARCIA ===== MICHAEL ===== STEVE ===== SUE ===== SYLVIA ===== TOM => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Examples

EDIT ACL ADMIN

See Also

DELETE ACL, EDIT Environment, SAVE ACL, QUIT

EDIT CONFIG

Function

Edit the SoftSpy configuration.

Syntax

EDIT CONFIG

Restrictions

You must belong to the ADMIN subsystem class for the SoftSpy subsystem and you must have invoked SoftSpy using the SPY softspy_command command rather than the SPY ON command.

Description

The EDIT CONFIG command is used to edit the SoftSpy configuration. Several aspects of the configuration may be changed from the EDIT CONFIG screens.

The SAVE CONFIG command is used to save any changes. The QUIT command terminates the editing session.

The first screen displayed by EDIT CONFIG lets you tailor the SoftSpy environment to suit the needs of your installation. These characteristics may be modified from this screen:

If square bracket characters are displayed on SoftSpy user terminals. Square brackets are not available on all 3270 terminals. If "N" (no) is selected SoftSpy help uses vertical bar characters in place of square brackets in syntax diagrams. Otherwise square brackets are used.
The names of the access control lists which define who is authorized to take the following actions:
- Issue the M204 command from the SoftSpy command line or from within user macros.
- Issue the M204 command from within system macros.
- Read access control lists.
- Read system macros.
- Issue the SPY SERVER command.
- Issue the SPY ON command.
- Update access control lists.
- Update system macros.

If a specified access control list does not exist, no user is authorized to perform functions that require the corresponding privilege. If an access control list is not specified, every user is authorized to perform functions that require the corresponding privilege.

EDIT CONFIG Definition Screen

1 of 2 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT CONFIG ============================================================================= Square Brackets can be displayed on terminals (Y OR N) Y Privilege Access Control List Name M204 Ad Hoc ADMIN_______________ M204 Macro ____________________ Read ACL ADMIN_______________ Read Macro ____________________ SoftSpy Server ADMIN_______________ Spy On ____________________ Update ACL ADMIN_______________ Update Macro ADMIN_______________ => 1=HELP 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 10=ACLS 11=MACROS 12=RETRIEVE

The second and subsequent screens displayed by EDIT CONFIG let you examine and update authorized SoftSpy environments. Changes to items on these screens require the entry of an authorization key provided by Information Technology Systems for validation. The following items may be modified on these screens:

The authorization key used to validate the specified start date, expiration date, customer name, CPU model number, CPU serial, optional features, user limits, and permitted operating systems.
The start date prior to which the SoftSpy configuration is not authorized. The start date is compared with the system clock, and is not affected by the Model 204 SYSDATE parameter.
The expiration date after which the SoftSpy configuration is not authorized. The expiration date is compared with the system clock, and is not affected by the Model 204 SYSDATE parameter.
The name of the organization authorized to use this copy of SoftSpy.
The four-digit model number of the CPU on which SoftSpy is authorized. An asterisk in any position means that position of the CPU model number is ignored for authorization purposes.
The six-digit serial number of the CPU on which SoftSpy is authorized An asterisk in any position means that position of the CPU serial number is ignored for authorization purposes.
The SoftSpy components which are available and the number of authorized users for each component.
The operating systems for which SoftSpy is authorized

These items are displayed but cannot be modified:

The SoftSpy version number.
The serial number of your copy of SoftSpy.

More than one authorization entry screen can exist. For example, different CPU serial numbers or different sets of optional features could have different expiration dates. You can request the creation or deletion of authorization entry screens using the editing actions section of the screen.

EDIT CONFIG Authorization Entry Screen

2 of 2 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT CONFIG ============================================================================= SoftSpy Version 3.0C SoftSpy Serial Number 970253 Authorization Key EPPQMKFL Start Date __ ___ ____ Expiration Date 01 SEP 1997 Customer Name SoftSpy Trial CPU Model Number **** CPU Serial Number ****** Optional Features User Limit Permitted Operating Systems X Debugging ____ X DOS X Performance Tuning ____ X CMS X QA Testing ____ X MVS X Audit X MVS/ESA X MUSE Configuration Entry Editing Actions (X to request specified action) _ Delete this authorization entry _ Insert new authorization entry => 1=HELP 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 10=ACLS 11=MACROS 12=RETRIEVE

Examples

EDIT CONFIG
SPY EDIT CONFIG

See Also

CONFIG Environment, SAVE CONFIG, QUIT

EDIT MACRO

Function	Create or edit a macro.
Syntax	EDIT MACRO `macro_identifier`
Restrictions	The READ MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
Description	The EDIT MACRO command creates or edits a macro. The `macro_identifier` specifies the name of the macro to edit. If the specified macro does not exist, a new macro with the name specified is created. The SAVE MACRO command must be used to save any changes. The editing session is terminated with the QUIT command.

EDIT MACRO Screen

1 of 50 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT MACRO DISPLAY_WATCH ===== ======================================================================= ====> ********************************************************************** ===== * SOFTSPY DISPLAY_WATCH MACRO: * ===== * * ===== * THIS MACRO TAKES A SINGLE ARGUMENT WHICH SPECIFIES WHETHER THE * ===== * SPECIFIED ARGUMENTS SHOULD BE DISPLAYED OR WATCHED. THE ARGUMENTS * ===== * TO BE DISPLAYED OR WATCHED ARE: * ===== * 1) CONTAINED ON THE COMMAND LINE IF THE COMMAND LINE IS NOT NULL * ===== * 2) CONTAINED ON THE SOURCE LINE WHERE THE CURSOR IS LOCATED IF IT * ===== * IS LOCATED ON A SOURCE LINE * ===== * 3) CONTAINED ON THE CURRENT SOURCE LINE IN ALL OTHER CASES. * ===== ********************************************************************** ===== * ===== DEFINE $OPERANDS STRING LEN 255 LOCAL ===== SET $OPERANDS = $COMMAND ===== IF $OPERANDS NE '' THEN JUMP TO DISPLAY_WATCH ===== DEFINE $I FIXED LOCAL => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Examples	EDIT MACRO PROFILE EDIT MACRO KAREN_PROFILE
See Also	DELETE MACRO, EDIT Environment, QUIT, SAVE MACRO

ERROR

Function	Issue an error message.
Syntax	ERROR `expression`
Description	The ERROR macro issues an error message. The `expression` parameter is evaluated. The resulting string is displayed with a prefix of "ERROR: ". This allows macros to issue error messages. If the result of the expression is not KNOWN, an error message is issued.
Examples	ERROR 'PF2 NOT SUPPORTED IN THIS CONTEXT' ERROR 'INVALID COMMAND LINE VALUE OF ' WITH $COMMAND

EXEC

Function	Execute a macro.
Syntax	[ EXEC ] `macro_identifier` [ `parameter_string` ]
Description	The EXEC command executes a macro. The `macro_identifier` parameter specifies the name of the macro to execute. If the macro specified does not exist, an error message is issued. The EXEC keyword can be omitted if the macro name is not the same as a SoftSpy command name. In effect this lets you use macros to create new SoftSpy commands. Parameters supplied by the `parameter_string` in EXEC commands can be referenced with the $MACRO_ARGS function within the invoked macro. The macro must perform any required parameter parsing. The `parameter string` begins with the first non-blank character following the `macro_identifier`. The macro name is terminated by any character except alphanumeric characters and the underscore, colon, percent sign, dollar sign, single quote, and double quote characters. The maximum number of JUMP TO commands that may be executed in a macro is controlled by the value of $JUMP_LIMIT for the macro. The initial value of $JUMP_LIMIT for a macro is set to the value of $DEFAULT_JUMP_LIMIT. Macros can be nested up to a maximum level of ten. If this limit is exceeded, a message is issued and all macros are terminated.
Examples	EXEC PROFILE PROFILE EXEC SCROLL MAX CPU EXEC TUNE TUNE REPORT DKRD
See Also	$DEFAULT_JUMP_LIMIT, $JUMP_LIMIT, $MACRO_ARGS

FORWARD

Function	Scroll forward in the active window.
Syntax	{ FORWARD \| + } [ FULL \| HALF \| `n` \| ERROR ]
Description	The FORWARD command scrolls forward the distance specified in the active window. It allows the display of data following the portion visible in the window by moving data upward. When FULL is used the distance scrolled is the full height of the window. FULL is the default. The line following the last line displayed in the active window becomes the first line displayed. The new center line becomes the current line. If there are not enough following lines to permit this movement, the last line becomes the current line. When HALF is used the distance scrolled is half the height of the window. The line following the last line displayed in the active window becomes the current line. If no following lines exist, the last line becomes the current line. When an integer is used the current line in the active window moves forward the specified number of lines. If there are not enough following lines, the last line becomes the current line. ERROR scrolls forward to the next statement that caused a compilation error. Searching begins with the line following the current line. The first line of the first executable statement found containing an error becomes the current line. If no errors are found, a warning message is issued and the current line remains unchanged. If ERROR is used and the active window is not the source window, an error message is issued and the current line remains unchanged. The active window may be temporarily altered for the duration of the FORWARD command by prefixing it with the IN WINDOW command.
Examples	FORWARD FORWARD ERROR +HALF FORWARD 100 + 100 IN WINDOW STATS +20
See Also	BACKWARD

GLOBALS

Function	Watch all currently defined global variables.
Syntax	GLOBALS
Restrictions	The context must be COMPILE_ERROR or EVAL and the interactive debugging option is required.
Description	The GLOBALS macro watches all defined global variables in the default watch window. An error message is issued if there is no default watch window or the interactive debugging option is not available.
Examples	GLOBALS
See Also	`global_variable_operand`, WATCH

GO

Function	Start or resume evaluation of a User Language request until an interrupt or user-specified condition occurs.
Syntax	GO [ FOREVER ] [ UNTIL `expression` ]
Restrictions	The context must be EVAL.
Description	The GO command resumes request evaluation for at least one statement. Evaluation is normally suspended again when any of the following conditions occur: Any UNTIL condition is true or the result is not KNOWN A break point is encountered An evaluation-time error occurs (either cancelling or non-cancelling) Evaluation of a User Language request is completed Evaluation of a User Language request is begun A User Language request fails to successfully compile and the interactive debugging option is available Normally evaluation is suspended at break points or at the beginning or end of request evaluation. However, this is not the case if FOREVER is specified. FOREVER causes evaluation to continue across multiple requests until an error occurs or a condition you specify is satisfied. FOREVER is assumed if an UNTIL expression only uses $PROCFILE, $PROCNAME, $SUBSYS, softspy_variables, numeric_constants and string_constants. For example, the command: GO UNTIL $PROCNAME = 'DESIRED.PROCEDURE' specifies that execution continues when evaluation of a new request starts unless the request is contained in the specified procedure. You must be careful when you specify GO FOREVER since execution continues indefinitely when you specify a condition that will never be true. In this situation you should exit your application and issue SPY OFF followed by SPY ON at the Model 204 command line prompt. This will reset your SoftSpy environment. After evaluation is suspended the actions specified by the most recent DEFAULT LINE command are performed. These actions include setting the current line to either the last statement executed or the next statement to be executed. They also include resetting the position in the history of executed statements. If an ON condition occurs while processing the GO command, the actions specified by the most recent DEFAULT LINE command are performed followed by the action specified in the ON command for the condition. This allows specific actions to be taken automatically on start or end of request, when compilation or evaluation-time errors occur, or when break points are encountered. Evaluation is suspended only if a condition that suspends evaluation is in effect after all ON processing is completed. When terminal process-to-process communication is active, control cannot be returned to SoftSpy and UNTIL conditions cannot be evaluated. Return of control due to break points or errors and evaluation of UNTIL conditions is delayed until terminal process-to-process communication is terminated. A GO command with an UNTIL clause may not be used while performing ON processing for a GO command with an UNTIL clause. The STEP statement can also be used to resume request evaluation.
Examples	GO GO FOREVER GO UNTIL %DATA = 'DESIRED VALUE' GO UNTIL $PROCNAME = 'DESIRED.PROCEDURE' GO UNTIL DKPR(STMT) GO FOREVER UNTIL DKPR(STMT) GO UNTIL FINDS(STMT) GO UNTIL DKPR(STMT) OR DKAR(STMT) GO UNTIL $UPDATE GO UNTIL $UPDATE AND SCREENS(STMT)
See Also	DEFAULT LINE, ON, STEP

HELP

Function

Request SoftSpy help information.

Syntax

HELP [ pattern ] [ pattern ]

Description

The HELP command invokes SoftSpy's on-line help facility. Patterns are used to select the desired help topics. Help is available on a variety of subjects including SoftSpy environments, commands, macros, expressions, operands, functions, identifiers, and messages.

Help topic titles can be either one or two words long. They correspond with the name of the subject described. The help topic titles for SoftSpy environments are two words long. The first word is the environment name and the second word is environment. Help topic titles for commands and macros can be either one or two words long. Normally they consist of the one or two word command name or the macro name. If a command or macro name is also the name of a SoftSpy environment the help topic title consists of the command or macro name as the first word with command or macro as the second word.

Expressions, operands, functions, and identifiers all have single word help topic titles that match their name. Messages always have two word help topic titles. The first word is message and the second word is of the form SPY.nnn where nnn is the three digit SoftSpy message number. A variety of summary topics are also available. They all have two word help topic titles consisting of the word summary followed by the name of the subject.

HELP Topic Screen

HELP HELP Command ============================================================================= HELP Command FUNCTION Request SoftSpy help information. SYNTAX HELP [ <pattern> ] [ <pattern> ] DESCRIPTION The HELP command invokes SoftSpy's on-line help facility. Patterns are used to select the desired help topics. Help is available on a variety of ...MORE => Select a topic by placing the cursor on a topic and pressing the HELP PF key 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=QUIT HELP 7=BACKWARD 8=FORWARD 9=REPEAT 10=HELP MENU 11=HELP LIST 12=RETRIEVE

If the pattern you specify is the title of a help topic, then that topic is displayed. If no pattern is specified, then the summary menu topic is displayed.

If you specify a pattern that is not the name of a help topic then pattern matching will be performed to select appropriate topics. If two patterns are specified then the selected topics are those for which the first word of the topic title matches the first pattern and the second word of the topic title matches the second pattern. If a single pattern is specified then the selected topics are those for which the first word of the topic title matches the pattern, if any. Otherwise the selected topics are those for which the second word of the topic title matches the pattern.

If a single help topic is selected then help is displayed on the selected topic. If no help topics are selected an error message is issued. If more than one help topic is selected then a menu is displayed showing the list of selected topics. Specific help topics may then be selected from the menu. Help menus can show just the first word of help topic titles or complete help topic titles. Only the first word is shown if a single pattern was specified and it matched with two or more different words. Otherwise complete help topic titles are shown.

HELP List Screen

1 OF 8 SoftSpy for Model 204 01 SEP 2012 12:00:00 HELP ACL ============================================================================= Select a topic by placing the cursor on a topic and pressing the HELP PF key BROWSE ACL COPY ACL DELETE ACL EDIT ACL LIST ACL PRINT ACL RENAME ACL SAVE ACL => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=QUIT HELP 7=BACKWARD 8=FORWARD 9=REPEAT 10=HELP MENU 11=HELP LIST 12=RETRIEVE

Angle brackets in SoftSpy on-line help identify text shown in italics in the manual. For example, <operand> represents the word operand in italics. This is done because italics cannot be displayed on 3270 terminals. Similarly, square brackets can not be displayed on some 3270 terminals. If necessary, vertical bars are used in syntax diagrams in place of square brackets. The EDIT CONFIG command lets your SoftSpy administrator control whether square brackets are displayed at your site.

Examples	HELP HELP * HELP DISPLAY HELP * * HELP EDIT MACRO HELP B* HELP * S* HELP OPERAND HELP SUMMARY HELP * MACRO HELP MESSAGE SPY.001 HELP SPY.127
See Also	HELP Environment

IF

Function	Conditionally execute a command.
Syntax	IF `expression` THEN `softspy_command`
Description	The IF command conditionally executes a softspy_command. The expression parameter is evaluated. If the result is true the following softspy_command is executed. Otherwise, the command is not executed. This allows conditional execution of SoftSpy commands. Like all SoftSpy commands, the complete IF command, including the THEN clause, must be contained on a single line.
Examples	IF $OPTION('DEBUG') THEN JUMP TO DEBUG IF $TESTED EQ $REACHABLE THEN JUMP TO REACHABLE IF $SKIP_END_EVAL THEN TRANSFER GO IF $SUBSTR($TEXT,1,1) NE '(' THEN JUMP TO OPERAND_WATCH IF $CONTEXT EQ 'EVAL' THEN EXEC EVAL_PROFILE IF $L IS NUM GT $MAX_LINE('SOURCE') THEN JUMP TO MISSING

IN WINDOW

Function	Temporarily alter the active window while a command is executed.
Syntax	IN [ WINDOW ] `window_identifier` `softspy_command`
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The IN WINDOW command temporarily changes the active window for the execution of the specified command. The original active window is restored after the command is executed. The window_identifier specifies the name of the window to make active while the softspy_command specified is executed. It can be the SOURCE window or a window opened with the OPEN WINDOW command. Otherwise an error message is issued and the command is not executed. The BACKWARD, FORWARD, LEFT, LOCATE, PRINT WINDOW, and RIGHT commands all operate in the context of the active window. The UNWATCH and WATCH commands operate in the context of the default watch window. The default watch window is the same as the active window unless the active window is the source window. IN WINDOW is also useful for EXEC commands when the macro executed contains commands sensitive to the active window. For example, the BOTTOM and TOP macros execute in the context of the active window.
Examples	IN WINDOW MONITOR TOP IN MONITOR TOP IN WINDOW MONITOR FORWARD IN MONITOR BACKWARD IN WINDOW STAT BOTTOM IN WINDOW SOURCE LEFT IN WINDOW SOURCE RIGHT IN WINDOW SOURCE LOCATE /ABC/ IN WINDOW STAT UNWATCH G.* IN WINDOW STAT WATCH CPU IN WINDOW SOURCE EXEC FINDEND
See Also	$ACTIVE_WINDOW, $DEFAULT_WATCH_WINDOW, ACTIVE WINDOW

Function	Branch to a different location in a macro.
Syntax	JUMP TO `label_identifier`
Restrictions	JUMP TO must be issued in a macro.
Description	The JUMP TO command performs branching in macros. Control is transferred to the first command in the macro following the specified label_identifier. If the specified label is not present, an error message is issued and the macro is aborted. The value of $JUMP_LIMIT in a macro controls the maximum number of JUMP TO commands that may be executed in that macro. In order to prevent infinite loops, macro execution terminates and an error message is issued if the limit is exceeded. If the value of $JUMP_LIMIT is zero then no limit is enforced. A label consists of a label_identifier followed by a colon. A label can be on a line by itself or can be followed by a command.
Examples	JUMP TO CHECK JUMP TO START_OF_LOOP CHECK: IF $SUBSYS EQ 'SOFTSPY' THEN JUMP TO SKIP
See Also	$JUMP_LIMIT

LAST

Function	Scroll backward in the execution history of the current User Language request.
Syntax	LAST [ `n` ]
Restrictions	The context must be EVAL and the interactive debugging option is required.
Description	The LAST command scrolls backward through the execution history of the current request. The position in the history is moved backward the specified number of statements. If no parameter is used, a default of one statement is assumed. If the history requested is not available a warning message is issued and the position is moved as far backward as possible. The current line is set to the first line of the statement executed at the new position in the execution history. SoftSpy maintains an execution history for 99 previously executed statements, plus the next statement to execute. The execution history is only available for the current User Language request.
Examples	LAST LAST 10
See Also	DEFAULT LINE, NEXT

LEFT

Function	Scroll to the left in the active window.
Syntax	LEFT [ FULL \| HALF \| n \| MAX]
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The LEFT command scrolls to the left in the active window. It allows the display of data to the left of the portion visible in the window. Data moves right, allowing columns to the left to become visible. When FULL is used the distance scrolled is the full width of the window. FULL is the default. The column preceding the first column displayed becomes the last column displayed. If there are not enough columns to allow this movement then the first column displayed becomes column one. When HALF is used the distance scrolled is half the width of the window. If there are not enough columns to allow this movement then the first column displayed becomes column one. When an integer is used the distance scrolled is the number of columns specified. If there are not enough columns to allow this movement then the first column displayed becomes column one. When MAX is specified the first column displayed becomes column one. The active window may be temporarily altered for the duration of the LEFT command by prefixing it with the IN WINDOW command.
Examples	LEFT LEFT MAX LEFT 10 LEFT HALF IN WINDOW STATS LEFT FULL IN MONITOR LEFT
See Also	RIGHT

LIST ACL

Function	Display a list of access control lists
Syntax	LIST ACL [ `pattern` ]
Restrictions	The READ ACL privilege is required.
Description	The LIST ACL command displays a list of access control lists. All access control lists whose names match the pattern specified are included. If no pattern is specified then all access control lists are included. A screen is displayed that shows all access control lists that meet the specified search criteria. The access control list name, number of lines, last update user id, and last update date and time, are shown for each selected access control list. If no access control lists are selected, an error message is issued and the screen is not displayed.

LIST ACL Screen

1 OF 2 SoftSpy for Model 204 01 SEP 2012 12:00:00 LIST ACL ================================================================================== UPDATE UPDATE UPDATE NAME LINES USERID DATE TIME > ADMIN 14 ANTHONY 16 JUN 1994 12:51:00 = EDIT_MACRO 5 ANTHONY 14 JUL 1994 13:09:36 => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

This access control list screen is scrollable. See the LIST environment for a description of facilities provided by the LIST ACL command.

Examples	LIST ACL LIST ACL * LIST ACL A*
See Also	LIST Environment

LIST MACRO

Function	Display a list of macros.
Syntax	LIST MACRO [ `pattern` ]
Description	The LIST MACRO command displays a list of macros. All macros whose names match the pattern specified are included. If no pattern is specified then all macros are included.

LIST MACRO Screen

1 OF 305 SoftSpy for Model 204 LIST MACRO ========================================== NAME > ALL_TYPES = ALTPF = ALTPF1 = ANT = ANTHONY_ON_EVAL = ANTHONY_PROFILE = A1 = B = BKBM = BN = BOB_ARRAY = BOB_ARRAY_D = BOB_BREAKS = BOB_WATCH => 1=HELP 2=PRINT 3=QUIT 7=BACKWARD 8=FORWARD 9=REPEAT 01 SEP 2012 12:00:00 ========================================= UPDATE UPDATE UPDATE LINES USERID DATE TIME 23 STEVE 20 FEB 1992 16:42:59 12 STEVE 18 JUN 1992 15:54:15 12 STEVE 18 JUN 1992 16:12:26 5 ANTHONY 09 AUG 1994 12:44:16 19 ANTHONY 18 APR 1994 13:50:44 8 ANTHONY 19 JUL 1994 15:37:20 2 GEORGEW 03 AUG 1994 11:58:10 1 KAREN 08 FEB 1994 15:16:36 2 ANTHONY 11 NOV 1993 16:59:50 41 MICHAEL 26 JUN 1994 14:58:59 82 BOB 03 SEP 1993 12:38:41 9 BOB 27 AUG 1993 08:21:18 31 BOB 02 SEP 1993 10:41:14 9 BOB 23 AUG 1993 10:16:06 4=TOP 5=BOTTOM 12=RETRIEVE

A screen is displayed that shows all macros that meet the specified search criteria. The macro name, number of lines, last update user id, and last update date and time, are shown for each selected macro. If no macros are selected, an error message is issued and the screen is not displayed.

This macro list screen is scrollable. See the LIST environment for a description of facilities provided by the LIST MACRO command.

Examples	LIST MACRO LIST MACRO * LIST MACRO P*
See Also	LIST Environment

LOCATE

Function	Find a character string in the active window.
Syntax
Restrictions	The context must be BROWSE, COMPILE_ERROR, EDIT or EVAL.
Description	The LOCATE command is used to find a line containing a substring that matches a specified string or a specified pattern in the active window. The search is case insensitive. An exact string match is requested using a string delimited with an initial slash. The slash delimiter must not be contained in the string. Unless the end slash delimiter is used, the string includes all following characters on the line except trailing spaces. A pattern match is requested with the keyword LOCATE. If a minus sign is specified, the search begins with the line preceding the current line and continues backward. Otherwise the search begins with the line after the current line and continues forward. LOCATE only searches in the active window. The current line is set to the first line found that contains the specified string or pattern. Searches include data outside of the visible portion of the window. If no match is found, an error message is issued and the current line remains unchanged. The active window may be changed for the duration of a LOCATE command by prefixing it with the IN WINDOW command.
Examples	/SUBROUTINE -/SUBROUTINE LOCATE SUBROUTINE LOCATE 'SUBROUTINE' LOCATE %SCREEN:LINE#

M204

Function	Execute a Model 204 command.
Syntax	M204 `model_204_command`
Restrictions	The M204 ADHOC privilege is required to use the M204 command from the command line or in a macro whose name begins with the user's id followed by an underscore. The M204 MACRO privilege is required to use the M204 command in macros whose name does not begin with the user's id followed by an underscore.
Description	The M204 command executes a Model 204 command. The Model 204 command is executed in the context of the SoftSpy server, not in the context of the user that issued the SPY ON command. The M204 command lets you edit procedures and run ad-hoc queries. Context information such as open files must be established first, since the Model 204 command is executed in the SoftSpy server environment, not the environment of the SoftSpy user. The specified command is run from within an included procedure. Commands that must be entered directly from a terminal, like invoking subsystems, are not allowed.
Examples	M204 OPEN PROCFILE M204 EDIT (SCREEN TERMINAL) 0 M204 INCLUDE RECORD.DISPLAY.PROC

NEW PAGE

Function	Begin a new page.
Syntax	NEW PAGE
Description	The NEW PAGE command begins a new page on the current print output destination. Page headers are printed on the new page. If the output destination is the terminal then an end of page pause is issued. Once the user has responded to the end of page pause the terminal screen is cleared so that a new page can be displayed. If no print destination is open and the default print destination is the terminal, a new page is begun on the terminal. If no print destination is open and the default print destination is not the terminal, an error message is issued.
Examples	NEW PAGE
See Also	DEFAULT PRINTER, OPEN PRINTER, PRINT LINE

Function	Scroll forward in the execution history of the current User Language request.
Syntax	NEXT [ `n` ]
Restrictions	The context must be EVAL and the interactive debugging option is required.
Description	The NEXT command scrolls forward through the execution history of the current request. The position in the history is moved forward the specified number of statements. If no parameter is used, a default of one statement is assumed. If the requested history is not available a warning message is issued and the current position is moved to the next statement to execute. The current line is set to the first line of the statement executed at the new position in the execution history. SoftSpy maintains an execution history for 99 previously executed statements, plus the next statement to execute. The execution history is only available for the current User Language request.
Examples	NEXT NEXT 10
See Also	DEFAULT LINE, LAST

ON

Function

Establish a command to execute whenever processing of a User Language request causes a specified condition to occur.

Syntax

Restrictions

The context must be COMPILE_ERROR or EVAL.

Description

The ON command specifies a softspy_command to execute whenever a specified condition occurs while processing a User Language request.

The following conditions can be specified:

BREAK	A break point is encountered.
CANCEL	A request is cancelled due to an error.
COMPILE_ERROR	A request contains compilation errors.
END_EVAL	Evaluation of a request is completed.
EVAL	Evaluation of a new request is begun.
NON_CANCEL	An error occurs during the evaluation of a request that does not cause the request to be cancelled (such as division by zero).
USER_CANCEL	A request is cancelled by the user (such as *CANCEL).

An ON command for a specified condition supersedes any prior ON command for the same condition. If no softspy_command is specified, no command is executed when the specified condition occurs.

When an ON condition occurs, processing of the associated softspy_command is nested within processing of the GO or STEP command that caused the condition to occur. Nesting depth increases when a GO or STEP command performed while processing an ON condition causes another ON condition to be processed. The maximum allowed nesting level for ON conditions is ten. If this level is exceeded an error message is issued and the associated softspy_command is not performed.

Examples

ON CANCEL EXEC EVAL_ERROR
ON END_EVAL GO
ON EVAL
ON EVAL EXEC ON_EVAL
ON NON_CANCEL EXEC EVAL_ERROR

See Also

GO, STEP

OPEN PRINTER

Function	Open a destination for print output.
Syntax
Description	The OPEN PRINTER command opens a destination for print output. Various aspects of the format of print output can also be controlled. If a print destination is not specified then the default print destination set by the DEFAULT PRINTER command is opened. If the open is successful then all print output will be sent to the specified destination until a CLOSE PRINTER command is issued. If a print destination is already open an error message is issued and the print destination is not changed. The print destination may be a DATASET, PRINTER, PUNCH, or the TERMINAL. The TERMINAL option takes no arguments. The other destination options require conformance with the syntax of the Model 204 USE command. In addition, SoftSpy supports two additional parameters for these destinations. A parameter of CCC=n may be specified, where n is the desired continuation column setting. Similarly, a parameter of LPP=n may be specified, where n is the desired number of lines per page. When output is directed to the terminal the continuation column is controlled by the Model 204 OUTCCC parameter. The number of lines per page is either 24 or 42 depending on the terminal model number. The initial default printer is TERMINAL.
Examples	OPEN PRINTER OPEN PRINTER TERMINAL OPEN PRINTER OUT1 OPEN PRINTER PUNCH PUNCH1 OPEN PRINTER DATASET REPORT OPEN PRINTER PRINTER WITH ROUTER=VM,ID=GEORGE
See Also	DEFAULT PRINTER, CLOSE PRINTER

OPEN WINDOW

Function	Display a window on the screen.
Syntax	OPEN WINDOW window_identifier [COLUMN left_column TO right_column] [ROW top_line TO bottom_line] [WATCH { operand \| (operand [,operand]...) } ]
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The OPEN WINDOW command displays a window on the screen. The window_identifier specifies the name of the window. This parameter may specify a new name or the name of a window that has been defined, but not opened. If the name of an open window is used an error message is issued. The COLUMN parameter is required unless a previously defined window that included a COLUMN parameter is being opened. The COLUMN keyword is followed by a left_column parameter specifying the window's first column, the word TO, and a right_column parameter specifying the window's last column. The left_column must be greater than or equal to six. The right_column must be less than or equal to 77 and at least two larger than the left_column. Columns adjacent to a window are reserved for screen format control. When the COLUMN parameter is specified in both the DEFINE and OPEN commands the values specified in the OPEN command are used. The ROW parameter is required unless a previously defined window that included a ROW parameter is being opened. The ROW keyword is followed by a top_line parameter specifying the window's top line, the word TO, and a bottom_line parameter specifying the window's bottom line. The top_line must be greater than or equal to one. The bottom_line must be less than or equal to 16 minus the number of title lines created by SHOW commands, and at least two larger than the top_line. The window must not overlap the rows of an open window or an error message is issued. When the ROW parameter is specified in both the DEFINE and OPEN commands the values specified in the OPEN command are used. The WATCH parameter identifies operands to watch in the window. If operands are specified in both the DEFINE WINDOW and OPEN WINDOW commands, both sets of operands are initially watched. OPEN WINDOW does not change the active window. The ACTIVE WINDOW or IN WINDOW commands must be used for this purpose. Opening windows can cause a performance penalty. The penalty is incurred when pre-compiled versions of SoftSpy code cannot be used because custom screen definitions are required. No penalty is incurred if there is a single open window positioned at ROW 1 TO 12 and at COLUMN 51 to 77.
Examples	OPEN WINDOW MONITOR OPEN WINDOW STATS COLUMN 50 TO 77 ROW 1 TO 6 OPEN WINDOW INFO ROW 1 TO 6 OPEN WINDOW WATCH ROW 7 TO 16 OPEN WINDOW GTBL WATCH G.* COLUMN 50 TO 77 ROW 1 TO 16
See Also	CLOSE WINDOW, DEFINE WINDOW, WATCH

PF

Function	Assign a command to a program function key.
Syntax

Description

The PF command assigns a softspy_command to a program function key. The number n specifies the number of the program function key. This number must be from 1 to 12. Physical program function keys 13 to 24 are mapped to program function keys 1 to 12. PA1 is used to assign a command to the attention key.

The context in which the program function key definition applies is specified within parentheses following the function key name. If a context is not specified then the current context is used. If a context is not specified, and there is no current context, an error message is issued. There is no current context until a context setting command is used if SoftSpy is started with the SPY softspy_command command.

The label parameter specifies a label for the program function key. Labels must not be longer than nine characters. If a label is omitted, the first nine characters of the first word of the command name are used as the label. Labels can consist of a single unquoted word containing alphanumeric characters or the underscore character, or they can consist of a string_constant.

The softspy_command parameter specifies the command to assign to the program function key. If this parameter is omitted no command is associated with the program function key, and any previously assigned command is cleared.

Examples

PF3 = QUIT
PF12(EVAL) = RETRIEVE
PF8(LIST) = COMMAND 'FORWARD ' WITH $COMMAND
PF12 STATS = DISPLAY CPU, DKPR, DKRD, DKWR
PA1 = QUIT CONFIRM
PF2 =

PRINT ACL

Function	Print an access control list.
Syntax	PRINT ACL `access_control_list_identifier`
Restrictions	The READ ACL privilege is required.
Description	The PRINT ACL command prints the specified access control list. If the specified access control list does not exist, an error message is issued and no printout is produced. The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.
Examples	PRINT ACL ADMIN

PRINT HELP

Function	Print SoftSpy help information.
Syntax	PRINT HELP [ `pattern` ] [ `pattern` ]
Description	The PRINT HELP command prints SoftSpy help information. It uses the same rules as the HELP command to select a single topic or a set of topics based upon the specified patterns. The single selected topic or a list of selected topics is printed. If no topics are found, an error message is issued and no printout is produced. The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.
Examples	PRINT HELP PRINT HELP ENVIRONMENT PRINT HELP * PRINT HELP LIST MACRO PRINT HELP BREAK PRINT HELP LIST *
See Also	HELP

PRINT LINE

Function	Print a line.
Syntax	PRINT LINE [ `expression` ]
Description	PRINT LINE evaluates the expression specified and prints a line consisting of the resulting value. If the result of the expression is not KNOWN, an error message is issued and no line is printed. If an expression is not specified a blank line is printed. The line is sent to the current open print output destination. If there is not an open print output destination and the default print destination is the terminal, the line is displayed on the terminal. Otherwise, the line is not printed and an error message is issued.
Examples	PRINT LINE 'HELLO' PRINT LINE $PAD('','',70) PRINT LINE '* TERMINATED BY ' WITH $INTERRUPT_TYPE PRINT LINE 'IN ' WITH $PROCFILE WITH ' I ' WITH $PROCNAME
See Also	DEFAULT PRINTER, NEW PAGE, OPEN PRINTER

PRINT LIST

Function	Print a list of access control lists or macros.
Syntax	PRINT LIST {ACL \| MACRO} [`pattern`]
Description	The PRINT LIST command prints a list of access control lists or macros. All access control lists or macros whose names match the pattern specified are included. If no pattern is specified then all access control lists or macros are included. If no access control lists or macros are selected, an error message is issued and no printout is produced. A line is printed for each access control list or macro selected. The line contains the access control list or macro name, number of lines, last update user id, and last update date and time. The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.
Examples	PRINT LIST MACRO PRINT LIST ACL * PRINT LIST MACRO _PROFILE PRINT LIST MACRO MICHAEL_

PRINT MACRO

Function	Print a macro.
Syntax	PRINT MACRO `macro_identifier`
Restrictions	The READ MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
Description	The PRINT MACRO command prints the specified a macro. If the specified macro does not exist, an error message is issued and no printout is produced. The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.
Examples	PRINT MACRO PROFILE PRINT MACRO BOB_PROFILE

PRINT WINDOW

Function	Print the contents of a window.
Syntax	PRINT WINDOW [ `window_identifier` ]
Description	The PRINT WINDOW command prints the specified window. The entire window is printed, including any portion that is not visible in the screen display. If the specified window does not exist, or has not been opened, an error message is issued and no printout is produced. The active window is printed if a window_identifier is not specified. The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.
Examples	PRINT WINDOW PRINT WINDOW MONITOR PRINT WINDOW SOURCE

QA

Function

Establish the interactive quality assurance testing environment.

Syntax

QA

Restrictions

The context must be EVAL and the quality assurance option is required.

Description

The QA macro switches to the interactive quality assurance testing environment, or reinitializes the interactive quality assurance testing environment. This environment helps you determine how thoroughly a User Language request has been tested.

QA Screen

54 of 90 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I QA_UL1 ============================================================================= TIMES LINE R U TESTED == 47 COUNT250.TOTAL: SUBROUTINE == 48 R 1170 %COUNT250 = %COUNT250 + 1 == 49 R 1170 RETURN == 50 U U END SUBROUTINE COUNT250.TOTAL == 51 COUNT500.TOTAL: SUBROUTINE == 52 R 794 %COUNT500 = %COUNT500 + 1 == 53 R 794 RETURN => 54 U U END SUBROUTINE COUNT500.TOTAL == 55 COUNT750.TOTAL: SUBROUTINE == 56 R 100 %COUNT750 = %COUNT750 + 1 == 57 R 100 RETURN == 58 U U END SUBROUTINE COUNT750.TOTAL == 59 == 60 R 1 FOR EACH RECORD ON LIST LIST1 => 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=-UNTESTED 11=+UNTESTED 12=RETRIEVE

The lines of User Language requests are prefixed with four columns. These columns show the line number, whether the statement is reachable or unreachable, whether the statement is untested, and the number of times the statement has been tested if it has been executed. The default line is set to the next executable statement. Any data collection is terminated and any collected data is discarded.

The quality assurance testing environment can be customized on an individual user basis. The QA macro looks for a macro named userid_QA, where userid is your user id. If such a macro is found, it is automatically run to customize the QA environment.

See the description of the QA environment for a complete description of the facilities available when interactively quality assurance testing a User Language request.

Examples

QA

See Also

AUDIT, DEBUG, QA Environment, TUNE

QUAD

Function	Find the line containing the quad_offset specified and make it the current line. If a procedure_name is specified following the quad_offset then evaluation is first resumed until the specified procedure is reached.
Syntax	QUAD `quad_offset` [ `procedure_name` ]
Restrictions	The context must be EVAL and the audit option is required.
Description	The QUAD macro is used to locate the line that caused a run-time error. The quad_offset and procedure_name of any statement causing a run-time error are written to the Model 204 audit trail after the SPY AUDIT ON command is issued. Issuing the QUAD macro with a quad_offset will make the line at the specified quad offset the current line in the current program. If a procedure_name is specified following the quad_offset then evaluation is first resumed until the specified procedure is reached. Evaluation will be suspended prior to reaching the specified procedure if any of the following occurs: An evaluation-time error occurs (either cancelling or non-cancelling) A User Language request fails to successfully compile and the interactive debugging option is available The `quad_offset` must be an integer between 0 and the value of C.QTBL for the target User Language request (inclusive). `Procedure_name` must be a valid Model 204 procedure name.
Examples	QUAD QUAD 108 QUAD 108 DESIRED.PROGRAM
See Also	AUDIT, AUDIT Environment, SPY AUDIT ON, SPY AUDIT OFF

QUIT

Function	Quit the current SoftSpy function or cancel the current User Language request.
Syntax	QUIT [CONFIRM \| NOCONFIRM]
Description	The QUIT command terminates the current SoftSpy function. If CONFIRM is specified the user is prompted for confirmation prior to termination of the function. If NOCONFIRM is specified the function is terminated without obtaining confirmation. CONFIRM is the default in the EVAL and COMPILE_ERROR contexts. NOCONFIRM is the default in the BROWSE, HELP, and LIST contexts. The default is CONFIRM in the CONFIG and EDIT contexts if changes have been made but not saved, and NOCONFIRM otherwise. When prompted to confirm the QUIT you should respond by pressing PF3 or entering QUIT on the command line if you want to terminate the function. You should respond by pressing PF12 or entering RETURN on the command line if you want to abort the QUIT and resume the current function. Invalid responses result in repeating the confirmation request. In the EVAL context QUIT cancels the request being evaluated. Use the SPY OFF command instead if you wish to terminate SoftSpy without cancelling the request.
Examples	QUIT QUIT CONFIRM QUIT NOCONFIRM
See Also	SPY OFF

RENAME ACL

Function	Rename an access control list.
Syntax	RENAME ACL `access_control_list_identifier1` TO [ ACL ] `access_control_list_identifier2`
Restrictions	The UPDATE ACL privilege is required.
Description	The RENAME ACL command renames an access control list. The first `access_control_list_identifier` specifies the name of the access control list to rename. If the specified access control list does not exist, an error message is issued. The second `access_control_list_identifier` specifies the new name to give to the access control list. If an access control list already exists with the specified name then an error message is issued.
Examples	RENAME ACL ADMIN TO OLD_ADMIN RENAME ACL ADMIN TO ACL SAVED_ADMIN

RENAME MACRO

Function	Rename a macro.
Syntax	RENAME MACRO `macro_identifier1` TO [ MACRO ] `macro_identifier2`
Restrictions	The UPDATE MACRO privilege is required unless both the name of the macro to be renamed and the new macro name both begin with the user's id followed by an underscore.
Description	The RENAME MACRO command renames a macro. The first `macro_identifier` specifies the name of the macro to rename. If the specified macro does not exist, an error message is issued. The second `macro_identifier` specifies the new name to give to the macro. If a macro already exists with the specified name then an error message is issued.
Examples	RENAME MACRO PROFILE TO OLDPROFILE RENAME MACRO PROFILE TO MACRO OLD_PROFILE

REPEAT

Function	Repeat the last command entered on the command line.
Syntax	{ REPEAT \| = }
Description	The REPEAT command repeats the last command entered on the command line. If no command was previously entered on the command line, an error message is issued. REPEAT ignores previous REPEAT and RETRIEVE commands.
Examples	REPEAT =

RETRIEVE

Function	Recall a previously entered command.
Syntax	RETRIEVE
Description	The RETRIEVE command recalls the previous command line entered. This value is placed on the command line so it may be modified or used again. If no value has been previously entered on the command line, an error message is issued. RETRIEVE ignores previously issued REPEAT and RETRIEVE commands. Each time RETRIEVE is used in succession it recalls the command line entered prior to the last retrieved line. Duplicate command lines are eliminated so that the same command is never retrieved twice by repeated execution of RETRIEVE. A maximum of ten previous command lines are available.
Examples	RETRIEVE

RETURN

Function	Terminate a macro and return to the point of invocation.
Syntax	RETURN
Restrictions	RETURN must be issued in a macro.
Description	RETURN is used in macros to provide a subroutine style return to the point of invocation. This takes the place of jumping to an end label in order to exit and return. When RETURN is executed, the macro stops and returns control to the parent process. RETURN can only be used in macros, otherwise and error message is issued and the command is rejected.
Examples	RETURN
See Also	EXEC, TRANSFER

RIGHT

Function	Scroll to the right in the active window.
Syntax	RIGHT [FULL \| HALF \| `n` \| MAX]
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The RIGHT command scrolls to the right in the active window. RIGHT allows the display of data to the right of the portion visible in the window. Data moves left, allowing columns to the right to become visible. When FULL is used the distance scrolled is the full width of the window. FULL is the default. The column following the last column displayed becomes the first column displayed. If there are not enough columns to allow this movement then the last column displayed becomes the last column. When HALF is used the distance scrolled is half the width of the window. If there are not enough columns to allow this movement then the last column displayed becomes the last column. When an integer is used the distance scrolled is the number of columns specified. If there are not enough columns to allow this movement then the last column displayed becomes the last column. When MAX is specified the last column displayed becomes the last column. The active window can be temporarily altered for the duration of the RIGHT command by prefixing it with an IN WINDOW command.
Examples	RIGHT RIGHT MAX RIGHT 10 RIGHT HALF IN WINDOW STATS RIGHT FULL IN MONITOR RIGHT
See Also	LEFT

SAVE ACL

Function	Save an access control list and continue editing.
Syntax	SAVE [ [ ACL ] `access_control_list_identifier` ]
Restrictions	The context must be EDIT.
Description	The SAVE ACL command saves the access control list being edited. The `access_control_list_identifier` specifies the name of the access control list to save. This can be the name of the access control list being edited or the name of a new access control list that is to be created. The keyword ACL must be used if the `access_control_list_identifier` is ACL, CONFIG, or MACRO. If the access control list name used does not match the edited access control list, and an access control list by that name already exists, an error message is issued and the save is not performed. If an `access_control_list_identifier` is not used, or the name of the edited access control list is used, the edited access control list is saved to reflect pending changes. If you try to save an access control list which contains an invalid user identifier, the access control list is not saved and an error message is issued. User identifiers must not exceed ten characters or contain a semicolon, comma, equal sign, or blank.
Examples	SAVE SAVE ADMIN SAVE ACL ADMIN SAVE ACL EDIT SAVE ACL ACL
See Also	EDIT ACL, QUIT

SAVE CONFIG

Function	Save the SoftSpy configuration and continue editing.
Syntax	SAVE [CONFIG]
Restrictions	The context must be CONFIG.
Description	The SAVE CONFIG command saves the SoftSpy configuration. If any edited configuration parameters are not valid an error message is issued, and the configuration is not saved. The new configuration takes immediate effect. Inactive IODEV=55 SoftSpy server threads are activated if they are authorized by the new configuration.
Examples	SAVE SAVE CONFIG
See Also	EDIT CONFIG, QUIT

SAVE MACRO

Function	Save a macro and continue editing.
Syntax	SAVE [ [MACRO] `macro_identifier`]
Restrictions	The context must be EDIT and the UPDATE MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
Description	The SAVE MACRO command saves the macro being edited. The macro_identifier specifies the name of the macro to save. This can be the name of the macro being edited or the name of a new macro that is to be created. The keyword MACRO must be used if the macro_identifier is ACL, CONFIG, or MACRO. If the macro name used does not match the edited macro, and a macro by that name already exists, an error message is issued and the save is not performed. If a macro_identifier is not used, or the name of the edited macro is used, the edited macro is saved to reflect pending changes. If you try to save a macro that contains invalid or duplicate label_identifiers, the macro is not saved and an error message is issued.
Examples	SAVE SAVE PROFILE SAVE MACRO PROFILE SAVE MACRO CONFIG
See Also	EDIT MACRO, QUIT

SCREEN

Function	Change the layout of the SoftSpy screen.
Syntax	SCREEN [BORDER] SOURCE [BORDER] COMMAND MESSAGE [PFKEYS]
Description	The SCREEN command lets you identify the order in which screen elements will appear. The following syntax rules apply: SOURCE, COMMAND, and MESSAGE must each be specified exactly once. BORDER is optional and can be specified up to two times. If specified it must be adjacent to SOURCE: before, after, or before and after. PFKEYS is optional and can be specified up to one time.
Examples	SCREEN SOURCE COMMAND MESSAGE SCREEN BORDER SOURCE BORDER COMMAND MESSAGE SCREEN MESSAGE SOURCE COMMAND PFKEYS SCREEN BORDER SOURCE PFKEYS COMMAND MESSAGE
See Also	DEFINE WINDOW

SCROLL

Function	Scroll in the source window based on user-specified criteria.
Syntax

SCROLL { [+] | - | TOP | BOTTOM | operand [ {EQ|NE} constant] | {MIN|MAX} operand | PFKEYS | NOPFKEYS}

Restrictions

The context must be COMPILE_ERROR or EVAL.

Description

The SCROLL macro is used to define a subset of lines within User Language requests, and an ordering of the lines in the selected set. It supports scrolling within the ordered selection of lines, and the creation of program function keys for scrolling.

When an operand is specified, the SCROLL macro selects a new subset of User Language request lines. The operand must be a compilation_operand, a quality_assurance_operand, a statistic_operand without a qualifier, or a usage_operand. If the requested operand is not available, or is not being collected, an error message is issued and a new scrolling set is not selected.

If a numeric operand is specified by itself then lines where it is not zero are selected. If a character operand is specified by itself then lines where it is not blank are selected. If the EQ operator is specified then lines where the operand is equal to the constant are selected. If the NE operator is specified then lines where the operand is not equal to the constant are selected. If MIN is specified all lines where the operand is present are selected, and they are ordered from the first line with the smallest value to the last line with the largest value. If MAX is specified all lines where the operand is present are selected, and they are ordered from the first line with the largest value to the last line with the smallest value.

The +, -, TOP, and BOTTOM keywords are used to scroll within the selected set of lines. If a set of lines is not selected an error message is issued and no scrolling is performed. When + or - are used the current line in the source window is moved to the next or the previous line within the ordered set of selected lines. When TOP or BOTTOM are used the current line in the source window is set to either the first or the last line in the ordered set of selected lines.

The PFKEYS and NOPFKEYS keywords determine whether program function keys for scrolling are automatically created for the EVAL context when subsequent scrolling sets are defined. The initial default is that program function keys are automatically defined. Program function key PF10 is used to scroll backward in the selected set. Program function key PF11 is used to scroll forward in the selected set. The program function key labels consist of the first eight characters of the specified operand prefixed with a minus sign and a plus sign.

Examples

SCROLL
SCROLL +
SCROLL -
SCROLL TOP
SCROLL BOTTOM
SCROLL UNTESTED
SCROLL TESTED
SCROLL UNREACHABLE
SCROLL DKPR
SCROLL VTBL
SCROLL TYPE EQ ‘X’
SCROLL MAX DKPR
SCROLL MAX CPU
SCROLL MAX EXECOUNT
SCROLL MAX CCATEMP
SCROLL PFKEYS
SCROLL NOPFKEYS

SET

Function	Alter the value of an operand.
Syntax
Description	The SET command alters the value of SoftSpy operands. The first parameter specifies the operand whose value is to be altered. The `expression` is evaluated and the resulting value is assigned to the target operand. If the result of the `expression` is not KNOWN an error message is issued and the operand is not altered unless the operand is a `softspy variable`. Setting $CURRENT_LINE $CURRENT_LINE is used with the SET command to set the current line for the source window. The literal value 'SOURCE' is required as an argument to indicate the source window. It may only be set in the COMPILE_ERROR and EVAL contexts. An error message is issued, and the current line is not altered, if the value assigned is not an integer between one and the number of lines in the source window. Setting $DEFAULT_JUMP_LIMIT SET can be used with $DEFAULT_JUMP_LIMIT to set the default value of $JUMP_LIMIT for subsequently invoked macros. It may only be set to a non- negative integer value. Setting $JUMP_LIMIT SET can be used with $JUMP_LIMIT to change the maximum number of JUMP TO statements that may be executed within the current macro. It may only be set within a macro. It may only be set to a non-negative integer value. If it is set to zero then no limitation on the number of JUMP TO statements is enforced within the current macro. Setting $SPY_MESSAGE If $SPY_MESSAGE is specified as the operand any SoftSpy message that has been issued but not yet displayed is purged. If the value assigned is a null string, then no pending message will remain. If the value assigned is not a null string, then setting $SPY_MESSAGE causes the specified value to be issued as a message. Setting Fields A `field_operand` can only be set in the EVAL context, and the SoftSpy interactive debugging option is required. They may be set at any point in execution where there is a current record (inside FOR EACH RECORD or FOR RECORD NUMBER loops). The only record loop context where fields may not be set is a record loop against a sorted set (a FOR loop against a set created with the SORT statement). If the SET command is used on a `field_operand` in an invalid context, then it is rejected with an error message. The field specified must exist in the file that contains the current record, or the command is rejected with an error message. If a field occurrence subscript is not specified, then a default of one is used. Setting a `field operand` is similar to the User Language CHANGE statement. If the requested occurrence number is present in the current record, then its value is changed to the value specified. If there are no occurrences of the field in the current record, then an occurrence is added with the value specified. If the occurrence number specified exceeds the number of occurrences in the record, then a new occurrence is added with the value specified. Finally, if the new value specified is a zero length string, the occurrence is deleted from the record. *Security* The user must have update access to the file in question. In addition, if field level security is in place, they must have the same security level as needed to update the field with a User Language CHANGE statement. In either case, the command is rejected with an error message if the user's access to the file is not sufficient. *Record locking* An exclusive record lock is obtained for the current record (if one is not already held). If this lock cannot be obtained, the command is rejected with an error message. The locking behavior is identical to that of an update statement within a record loop except no ON unit is invoked if the lock cannot be obtained. *Items that cannot be set* Neither invisible fields nor the sort key of a sorted file may be set. Remote files may not be updated. In these cases, the command is rejected with an error message. *Constraints* Finally, if the SET command would cause an update to the file that would violate any file or field constraint defined for the file, then the command is rejected with an error message. The user can only perform updates that would be legal in a User Language program. SoftSpy strictly enforces all file and field constraints. Constraint violations include: The value is too long for a pre-allocated field. The occurrence number exceeds the OCCURS specification of a pre-allocated field. The value causes a uniqueness violation (note that any ON FCC unit is not raised). The value cannot be converted to a number on a numeric (FLOAT or BINARY) field in a numeric validation file (FILEMODL=1). The value fails KANJI conversion for either a mixed or pure DBCS field. The occurrence number would cause an attempt to add another occurrence of an AT MOST ONE field. *Sir2000 Field Migration Facility* If you are using the Sirius Software Sir2000 Field Migration Facility, use caution when using the SET command to update date fields. The SET command will not automatically update a Sir2000 RELATEd date field. Setting Global Variables If a new `global_variable_operand` is specified, the G. `global_variable_operand` prefix is required. If room is not available in the global table, an error message is issued and the `global_variable_operand` is not altered. A `global_variable_operand` can only be set in the COMPILE_ERROR and EVAL contexts, and the SoftSpy interactive debugging option is required. Setting Percent Variables If a `percent_variable_operand` is specified, a conversion is performed from the `expression` to the target `percent_variable_operand` type using Model 204 conversion rules. If the correct number of subscripts are not specified, a subscript is out of range, or the `percent_variable_operand` is a complex subroutine input parameter, an error message is issued and the `percent_variable_operand` is not altered. If the `percent_variable_operand` is defined as a string and the value exceeds its defined length, a warning message is issued and the value is truncated. A `percent_variable_operand` can only be set in the EVAL context, and the SoftSpy interactive debugging option is required. One use of setting a percent variable is terminating a loop early, without ending the request. For example, a loop initiated by the statement FOR %I FROM 1 TO 10 can be terminated early by setting %I to 11 while inside the loop. Setting SoftSpy Variables The value assigned to a `softspy_variable` of numeric type must be numeric. If it is not then an error message is issued and the variable is set to UNKNOWN. A value assigned to a `softspy_variable` of string type is truncated if it is longer than the declared length.
Examples	SET %WORD = 'HELLO' SET %ARRAY(2,3) = 'THERE' SET %AGE = 35 SET %NAMELIST(%CURVAL) = 'SALLY' SET %LAST_NAME = G.LAST_NAME SET %NAME = %FIRST_NAME WITH ' ' WITH %LAST_NAME SET G.NAME = 'MICHAEL' SET NAME = OLDNAME SET LINE = %X WITH %SCREEN.LINE1 SET G.'M.I.' = 'A' SET $SPY_MESSAGE = 'MACRO EXECUTION SUCCESSFUL' SET $SPY_MESSAGE = SET $DEFAULT_JUMP_LIMIT = 333 SET $JUMP_LIMIT = 1616 SET $CURRENT_LINE('SOURCE') = $CURRENT_LINE('SOURCE') + 1 SET $SAVED_WINDOW = $ACTIVE_WINDOW SET $I = $I + 1 SET F.FIRSTNAME = 'MOE' SET F.PETS(1) = 'SPOT' SET F.AGE = F.AGE + 1 SET F.'LAST NAME' = 'HOWARD'

SHOW

Function	Add columns to the source window that display statistic, usage, quality assurance, or compilation operands by line.
Syntax	SHOW `column_definition` [ , `column_definition` ] . . . Where each column_definition is of the following form:

Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The SHOW command modifies the source window display by adding columns to the left of the request lines. The columns display values of compilation_operands, statistic_operands without qualifiers, usage_operands, or quality_assurance_operands. The columns persist across requests until cleared with the UNSHOW command.

SHOW Screen

6 of 6 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG30 =================================================================================== NEST DKPR == B ----------MONITOR---------- == 91 FD1: FD - - == /------- 1 FR1: FR FD1 - - == | 372 PAI - - == \------- 190 END FOR - - => END - - - - - - - - - - - - --------------------------- => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

Each SHOW command specifies one or more columns to add to the display, separated by commas. Each column_definition specifies an operand to be displayed in the column. Various qualifiers can also be specified that control how the column is formatted and how the data is displayed. The PERCENT qualifier specifies that values be displayed as a percent of the total. The AVERAGE qualifier specifies that the average use per execution of the statement be displayed (total use divided by S.EXECOUNT).

Columns are added from left to right in the order in which they were specified. Subsequent SHOW commands add columns to the right of any existing SHOW columns. Each column is followed by one blank for separation. The RIGHT and LEFT commands shift columns and their titles, as well as the source lines.

The type of operand shown in a column determines which lines in the column have values to display:

Statistic_operands and usage_operands only have values for the first line on an executable statement.
Compilation_operands and quality_assurance_operands have values for all request lines.

Column Titles

A column can be untitled or can have a one-line or a two-line title. A column is untitled if the NOTITLE parameter is specified. A one-line title is specified if TITLE is specified followed by a single string_constant. A two-line title is specified if TITLE is followed by two string_constants. Only one TITLE or NOTITLE keyword can be specified. The string_constants cannot be longer than the column width. If neither TITLE nor NOTITLE is specified for a column, a default title of the operand name is used unless one of the following situations applies:

If a column is qualified with PERCENT, it has a two-line default title with PCT for the top line and the operand name as the bottom line.
If a column is qualified with AVERAGE, it has a two-line default title with AVG for the top line and the operand name as the bottom line.
Compilation_operands that reference a server table have a default two-line title with CMPL as the top line and the operand name as the bottom line. This distinguishes them from the usage_operand for the same server table.

Default title lines are truncated to the column width if necessary.

Column Width

The LEN parameter specifies the width of a column in display positions. The LEN keyword is followed by a numeric_constant in the range from one to fifteen. If LEN is not specified, a default column width of four is used unless one of the following exceptions applies:

Any operand that is qualified with HISTOGRAM or BRACKET has a default width of ten.
The compilation_operands INC and TYPE and all quality_assurance_operands have a default width of one.

Decimal Places

The DP parameter specifies the number of decimal places. The DP keyword is followed by a numeric_constant in the range from zero to the smaller of three or one less than the column width. It can be specified with any operand that has a numeric value (and is not qualified with HISTOGRAM or BRACKET) to allow decimal places to be displayed in the column. DP always defaults to zero.

Data Collection

When statistic_operands, usage_operands, or the TESTED, UNTESTED or TEST_STATUS quality_assurance_operands are used on a SHOW command, they automatically initiate collection of the required evaluation time data. In addition, any column that mentions AVERAGE will initiate collection of EXECOUNT, which is needed to compute averages. For this reason, a SHOW command can fail for the same reasons that the COLLECT command does if a column mentions evaluation time data.

Numeric Data

If a column contains numeric data, for example a statistic_operand, the values are right-justified within the column width and zero values are displayed as blanks. On a negative value the minus sign is placed immediately to the left of the value.

If a value contains more digits (including any minus sign or decimal point) than the column width, the column is filled with asterisks for the corresponding line. However, if a column contains decimal places (DP specified) and a value is too wide, but the integer portion of the number fits, then only the integer portion of the number is displayed.

Character Data

If a column contains character data, for example a quality_assurance_operand, the values are centered within the column and truncated on the right if their length exceeds the column width.

Histograms

If the HISTOGRAM parameter is specified for a statistic_operand, the column displays a histogram of the data instead of the actual values. The histogram is drawn with asterisks, using the following rules:

If the value is zero, the column is blank.
Each display position in the column represents (maximum operand value/column width) units. The maximum value is defined as the highest value of the operand for any statement in the request at the current execution point.
If a statement has a non-zero value, asterisks are displayed in the column from left to right. The number of asterisks drawn is equal to the value of the operand divided by the units per display position, rounded up.

SHOW Histogram Screen

6 of 6 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG30 ======================================================================================= DKPR HISTO DKPR == B ----------MONITOR---------- == 1 * FD1: FD - - == 1 * FR1: FR FD1 - - == 17 ********** PAI - - == 6 **** END FOR - - => END - - - - - - - - - - - - --------------------------- => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

HISTOGRAM may be used in conjunction with the PERCENT or AVERAGE parameters. If HISTOGRAM is specified for anything other than a statistic_operand, an error message is issued.

Brackets

The parameter BRACKET can be specified with the compilation_operands NEST and INC to draw bracket representation of the nesting or include level, respectively.

SHOW Bracket Screen

1 of 10 Next 1 SoftSpy for Model 204 01 SEP 2012 12:00:00
IN QCPROC I MAN.FIG32 ======================================================================================= NEST => B ----------MONITOR---------- == /------- FOR EACH RECORD - - == |/------ IF AGE > 60 THEN - - == || %GE60 = %GE60 + 1 - - == |>------ ELSE - - == || %LT60 = %LT60 + 1 - - == |\------ END IF - - == | %TOTREC = %TOTREC + 1 - - == \------- END FOR - - == END - - - - --------------------------- => SPY.005: A new request has been compiled. 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

The following characters are used to draw the brackets:

Character	Meaning
/	Start of a new block.
\	End of a block.
>	End of a block and start of a new block.
\|	Continuation of a block.
-	Horizontal connector on start and end of blocks.

The bracket for the outermost nesting level is left-justified within the column and hyphens are drawn to the right to fill the column width. If the maximum nesting level of the request exceeds the width of the column, the brackets are truncated on the right (the innermost nesting levels are not shown).

An error is issued if BRACKET is specified with an operand other than NEST or INC.

Missing Data

If a column is based on evaluation time data (statistic_operands, usage_operands, and the quality_assurance_operands TESTED, UNTESTED, and TEST STATUS) and an UNCOLLECT command has terminated collection of the data, then the column is filled with hyphens ("-") to signify missing data.

Examples

SHOW C.VTBL, NEST
SHOW AVERAGE CCATEMP, EXECOUNT
SHOW DKWR LEN 6 TITLE 'DISK' 'WRITES'
SHOW PERCENT DKRD LEN 8 DP 2 TITLE 'DISK' 'READS'
SHOW BRACKET NEST
SHOW HISTOGRAM DKRR

See Also

COLLECT, DISPLAY, UNCOLLECT, UNSHOW, WATCH

SPY AUDIT OFF

Function	Deactivate the SoftSpy Audit feature.
Syntax	SPY AUDIT OFF
Restrictions	The audit option is required. SPY AUDIT OFF must be issued from the Model 204 command line by user zero or a System Manager.
Description	The SPY AUDIT OFF command deactivates the SoftSpy Audit feature.
Examples	SPY AUDIT OFF
See Also	AUDIT, AUDIT Environment, SPY AUDIT ON

SPY AUDIT ON

Function	Activate the SoftSpy Audit feature.
Syntax	SPY AUDIT ON
Restrictions	The audit option is required. SPY AUDIT ON must be issued from the Model 204 command line by user zero or a System Manager.
Description	The SPY AUDIT ON command activates the SoftSpy Audit feature. With this feature active whenever a run-time error occurs during evaluation of a User Language request the following information is written to the audit trail: SPY >>> Runtime Procedure Error in Subsystem: [NONE \| subsystem_name] Procfile: [NONE \| procfile_name] SPY >>> Procedure: procedure_name SPY >>> QTBL quad offset: quad_offset SPY >>> Call issued from QTBL quad offset: quad_offset . . . This information is written to the audit trail immediately before the error to which it refers. If the error did not occur in a subroutine no “Call issued from” lines will be present. Once SPY AUDIT ON has been issued, it remains on for the entire online run unless SPY AUDIT OFF is issued.
Examples	SPY AUDIT ON
See Also	AUDIT, AUDIT Environment, SPY AUDIT OFF

SPY OFF

Function	Terminate a SoftSpy session.
Syntax	SPY OFF
Restrictions	The context must be COMPILE_ERROR or EVAL unless SPY OFF is used from the Model 204 command line.
Description	The SPY OFF command turns SoftSpy off. This command can be used from the Model 204 command line or from the SoftSpy command line. If SPY OFF is issued in SoftSpy, execution of the User Language request is resumed. Use the QUIT command instead if you wish to cancel the request. You can then issue a SPY OFF command at the next Model 204 prompt to turn SoftSpy off. An informational message is issued if you issue the SPY OFF command when SoftSpy is not turned on.
Examples	SPY OFF
See Also	QUIT, SPY ON, SPY ON THREAD, SPY ON USER

SPY ON

Function	Start a SoftSpy session.
Syntax	SPY [ ON [ CLASS=class_name ] ]
Restrictions	The SPY ON privilege is required. SPY ON must be issued from the Model 204 command line.
Description	The SPY ON command turns SoftSpy on for your use, if possible. It requires that a SoftSpy server be available for use. An error message is issued if a server is not available, or if sufficient storage is not available to establish the SoftSpy environment. An informational message is issued if you have already turned SoftSpy on. The optional CLASS parameter is used to specify a class_name for the server. If CLASS is specified then only a server started with the same CLASS parameter will be used. If CLASS is omitted, then only servers started with CLASS omitted will be used. The class name may be up to eight characters long. The first character must be alphabetic, and any additional characters must be alphanumeric or the underscore. The PROFILE macro is run to initialize SoftSpy. SoftSpy can be customized on an individual user basis. The PROFILE macro looks for a macro named userid_PROFILE, where userid is your user id. If such a macro is found, it is automatically run by the PROFILE macro in order to customize SoftSpy.
Examples	SPY SPY ON SPY ON CLASS=ADMIN
See Also	SPY OFF, SPY ON THREAD, SPY ON USER, SPY SERVER

SPY ON THREAD

Function	Start a SoftSpy server session to debug another User Language thread.
Syntax	SPY ON THREAD threadnum
Restrictions	The SPY SERVER privilege is required. SPY ON THREAD must be issued from the Model 204 command line.
Description	The thread specified by threadnum is validated to see if it is within the range from 1 to NUSERS, and that it is not the thread from which SPY ON THREAD was issued. In addition, the thread number may not specify a thread that is currently using SoftSpy or is a SoftSpy server. The IODEV type of the selected thread is then examined for validity. All thread types from which User Language requests can be run are legal except for Horizon and Janus threads. If any of these rules is violated, an error message is issued and the command is rejected. Once a thread has been selected, the thread that issued the command is turned into a SoftSpy server, and the terminal will lock up until the selected thread runs a User Language request. When the selected thread runs a request, the SoftSpy screen appears on the SoftSpy server terminal session. SoftSpy can then be used in the normal manner. From the SoftSpy screen, issuing SPY OFF will convert the thread from a SoftSpy server back into a normal thread, and disconnect it from the selected thread. This feature can be used for two purposes. First, it can be used to interactively execute non-terminal threads such as BATCH2, and IODEV=3 threads. Second, it can be used if you have an environment (such as Microsoft Windows) where you can have multiple terminal sessions, and you do not want the output of the SoftSpy screen and the application sharing the same terminal session.
Examples	SPY ON THREAD 4 SPY ON THREAD 666
See Also	SPY ON, SPY OFF, SPY SERVER

SPY ON USER

Function	Start a SoftSpy server session to debug another User Language thread.
Syntax	SPY ON USER userid
Restrictions	The SPY SERVER privilege is required. SPY ON USER must be issued from the Model 204 command line.
Description	All logged in threads that run User Language with the exception of Horizon, Janus, and the thread issuing SPY ON USER are matched against userid. If no such threads are found, or more than one are found, then the command is rejected and an error message is issued. If one such thread is found, it is validated to ensure that it is not user 0, a SoftSpy server, or a SoftSpy user. If any of these rules is violated, the command is rejected with an error message. Once a thread has been selected, the thread that issued the command is turned into a SoftSpy server, and the terminal will lock up until the selected thread runs a User Language request. When the selected thread runs a request, the SoftSpy screen appears on the SoftSpy server terminal session. SoftSpy can then be used in the normal manner. From the SoftSpy screen, issuing SPY OFF will convert the thread from a SoftSpy server back into a normal thread, and disconnect it from the selected thread. This feature can be used for two purposes. First, it can be used to interactively execute non-terminal threads, such as BATCH, and IODEV=3 threads. Second, it can be used if you have an environment (such as Windows) where you can have multiple terminal sessions and do not want the output of the SoftSpy screen and the application sharing the same terminal session.
Examples	SPY ON USER MOE SPY ON USER SHEMP
See Also	SPY ON, SPY OFF, SPY SERVER

SPY SERVER

Function	Start a SoftSpy server.
Syntax	SPY SERVER [ CLASS=class_name ]
Restrictions	The SPY SERVER privilege is required to use SPY SERVER unless it is issued by user zero or an IODEV=3 thread. SPY SERVER must be issued from the Model 204 command line.
Description	The SPY SERVER command starts a SoftSpy server. SPY SERVER can be used to dynamically create a SoftSpy server if all IODEV=55 SoftSpy server threads are in use. The optional CLASS parameter is used to specify a class_name for the server. Use of the server is restricted to users that specify the same CLASS in the SPY ON command. If CLASS is omitted then use of the server will be restricted to users that omit CLASS in the SPY ON command. The class name can be up to eight characters long. The first character must be alphabetic, and any additional characters must be alphanumeric or the underscore. A SoftSpy server is created based on the authorized configuration specified with the EDIT CONFIG command. If a valid configuration is defined and enough storage is available the user becomes a SoftSpy server. Control is not normally returned after this command is issued. The value of OUTPB must be the same for both the SPY ON thread and the SPY SERVER thread. If system initialization is not complete when the SPY SERVER command is issued, then processing of the command is delayed until it is complete.
Examples	SPY SERVER SPY SERVER CLASS=ADMIN
See Also	SPY ON, EDIT CONFIG

SPY softspy_command

Function	Issue SoftSpy commands from the Model 204 command line.
Syntax	SPY softspy_command
Restrictions	SPY must be issued from the Model 204 command line.
Description	SPY executes the SoftSpy command specified. Any command can be specified except those requiring the COMPILE_ERROR or EVAL context. If system initialization is not complete when the SPY command is issued, then processing of the command is delayed until it is complete. The PROFILE macro is run to initialize SoftSpy. SoftSpy can be customized on an individual user basis. The PROFILE macro looks for a macro named userid_PROFILE, where userid is your user id. If such a macro is found, it is automatically run by the PROFILE macro in order to customize SoftSpy.
Examples	SPY LIST MACRO SPY COPY MACRO PROFILE TO MACRO OLD_PROFILE SPY EDIT CONFIG

STATS

Function	Watch all statistic_operands and usage_operands.
Syntax	STATS
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The STATS macro requests that all available statistic and usage operands be watched in the default watch window. The actual statistics and usage operands that are watched depends upon which optional SoftSpy features are available. Restrictions are described under statistic and usage operands. An error message is issued if there is no default watch window.
Examples	STATS

STEP

Function	Start or resume evaluation of a User Language request for a specified number of statements or until an interrupt occurs.
Syntax	STEP [ n ]
Restrictions	The context must be EVAL.
Description	The STEP command resumes request evaluation. Evaluation is normally suspended again when any of the following conditions occur: The number of statements specified with STEP have been executed, or a single statement has been executed if a number of statements was not specified A break point is encountered An evaluation-time error occurs (either cancelling or non-cancelling) Evaluation of a User Language request is completed Evaluation of a User Language request is begun. A User Language request fails to successfully compile and the interactive debugging option is available After evaluation is suspended, the actions specified by the most recent DEFAULT LINE command are performed. These actions include setting the current line to either the last statement executed or the next statement to be executed. They also include resetting the position in the history of executed statements. If evaluation is suspended for any reason other than execution of the specified number of statements, the action specified by the most recent ON statement for the specified condition is performed. This allows specific actions to be taken automatically on start or end of request, when compilation or evaluation-time errors occur, or when break points are encountered. When terminal process-to-process communication is active, control cannot be returned to SoftSpy. Return of control is delayed until terminal process-to-process communication is terminated. The GO statement can also be used to resume request evaluation.
Examples	STEP STEP 10
See Also	DEFAULT LINE, GO, ON

TOP

Function	Scroll to the top of the active window.
Syntax	TOP
Description	The TOP macro scrolls to the first line of data available in the active window. The first line becomes the current line. The active window can be temporarily altered for the duration of the TOP macro by prefixing it with the IN WINDOW command.
Examples	TOP IN MONITOR TOP IN WINDOW SOURCE TOP
See Also	BOTTOM

TRACE

Function	Produce a debugging trace when macros are run.
Syntax	TRACE {ON \| OFF}
Description	The TRACE command controls whether or not a SoftSpy macro debugging trace is produced when macros are run. If tracing is enabled when a macro is run, debugging output is written to the open printer. The default printer is used if no printer is open. If no TRACE command has been issued then a debugging trace is not produced. TRACE ON enables a debugging trace. TRACE OFF terminates a debugging trace. Macro debugging output consists of three types of lines: When a macro is entered (or returned to), a line containing MACRO: followed by the *macro_identifier* is printed. For example, the line MACRO: REPORT would be printed when the REPORT macro is run. As each line of a macro is executed, a line containing the macro *line number* followed by the *macro_line_text* is printed. For example, 20 COLLECT VTBL would be printed when the 20th line of a macro containing the text COLLECT VTBL is run. If a message is issued from within a macro, the debugging trace will include the text of the message following the line that caused it to be issued.
Examples	TRACE ON TRACE OFF

TRACER

Function	Start or resume evaluation of a User Language request and print a trace of the statements executed.
Syntax	TRACER
Restrictions	The context must be EVAL.
Description	The TRACER macro creates a trace of statements executed by the evaluation of a request. The request is evaluated until completion unless a break point or an error is encountered first. A trace of the statements executed is sent to the current open printer. This trace includes line numbers and the text of the first line of every statement executed. The reason the trace was terminated is also printed.
Examples	TRACER

TRANSFER

Function	Transfer control to a command from a macro.
Syntax	TRANSFER SoftSpy_command
Restrictions	Must be issued in a macro.
Description	TRANSFER provides a one-way transfer of control to a different macro or command from a macro. The macro containing the TRANSFER command is terminated and the specified SoftSpy command is run. When the new command is done, control is returned: not to the original macro, but to wherever that macro was invoked. TRANSFER can only be used in macros, otherwise an error message is issued and the transfer is not performed.
Examples	TRANSFER GO TRANSFER ERROR 'CONTEXT MUST BE EVAL' TRANSFER COMMAND 'HELP ' WITH $CURSOR_HYPERTEXT
See Also	EXEC, RETURN

TUNE

Function	Establish the interactive performance tuning environment.
Syntax	TUNE
Restrictions	The context must be EVAL and the interactive performance tuning option is required.
Description	The TUNE macro switches to the interactive performance tuning environment, or reinitializes the interactive performance tuning environment. This environment is designed to help you tune the performance of your User Language requests. The lines of User Language requests are prefixed with three columns. These columns show the CPU time used in milliseconds, the number of logical page reads, and the average change in CCATEMP scratch file usage. The default line is set to the last statement executed. Any prior data collection is terminated and any collected data is discarded.

TUNE screen

30 of 81 Last 55 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG1 ============================================================================= PAGE CCA CPU REQ TEMP == * PROCESS THE ORDER FILE == * COMPUTE THE TOTAL VALUE == * AND COUNT THE ORDERS. == * == 8 138 1 FDORD: IN SSPYQA FD RECTYPE = ORDER == END FIND == * => %OCOUNT = 0 == 1 FOR EACH RECORD IN FDORD == 1 %OCOUNT = %OCOUNT + 1 == 1 CALL GET_PRICE( ITEM, %PRICE ) == %TOTALPRICE = %TOTALPRICE+%PRICE*QTY == ************************ == ** CALCULATE DISCOUNT ** => 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=PAGE REQ 11=FIND STMT 12=RETRIEVE

The interactive performance tuning environment can be customized on an individual user basis. The TUNE macro looks for a macro named userid_TUNE, where userid is your user id. If such a macro is found, it is run to customize the tuning environment.

See the description of the TUNE environment for a complete description of the facilities available when interactively performance tuning a User Language request.

Examples	TUNE
See Also	AUDIT, DEBUG, QA, TUNE Environment

UL CONTINUE

Function	Advance the execution position to the next iteration of a FOR or REPEAT loop.
Syntax	UL CONTINUE
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	If the current execution position is not inside a FOR or REPEAT loop, an error message is issued and the command is rejected. In addition, this command is only valid if the execution position is in a loop within the current routine: it is not valid from a subroutine that is called in a loop. If the current execution position is inside a loop, the loop is immediately advanced to its next iteration. If the execution position is in a loop that is nested inside of one or more outer loops, the inner most loop that contains the execution position is the loop that UL CONTINUE operates on. The alteration of the flow of control is identical to the behavior that would be seen if there was a label on the END FOR or END REPEAT that was jumped to. If there are more iterations remaining, then the execution position is placed on the first statement in the loop body. If there are no more iterations remaining, the execution position is placed on the first statement after the END of the loop. On record, value, or occurrence loops (FOR EACH RECORD, FOR EACH VALUE, FOR EACH OCCURRENCE), the next record, value, or occurrence is made current. On index loops (FOR %I FROM x TO y, REPEAT n TIMES), the index is incremented. Note that on a FOR RECORD NUMBER loop, UL CONTINUE simply causes an exit from the loop since this type of loop only has one iteration. Note that if the loop is exited, all the normal processing that occurs at the end of a loop still occurs, such as releasing of resources and locks.
Examples	UL CONTINUE
See Also	QA, QA Environment, UL JUMP TO LABEL, UL JUMP TO LINE, UL LOOP END, UL RESULT, UL RETURN

UL JUMP TO LABEL

Function	Advance the execution position to a statement label or statement number and execute that statement.
Syntax	UL JUMP TO [LABEL] `label`
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	`label` specifies a statement label or number within the request. If no such statement label or number is found, then an error message is issued and the command is rejected. The execution position is transferred to the statement with the matching label and that statement is executed. Not all jumps are valid. If any of the following rules are violated, an error message is issued and the command is rejected: Jumping into or out of subroutines is not permitted. Jumping into or out of ON UNITS is not permitted. Jumping into the body of a FOR or REPEAT loop is not permitted. As an alternative to UL JUMP TO LABEL, the “J” prefix command may be entered directly into the prefix area of a line to jump to. Using this prefix command on a line is identical to determining the line’s number and issuing a UL JUMP TO LINE for that line number.
Examples	UL JUMP TO LABEL X UL JUMP TO EXITLOGIC UL JUMP TO 1 UL JUMP TO LABEL LINE
See Also	QA, QA Environment, UL CONTINUE, UL JUMP TO LINE, UL LOOP END, UL RESULT, UL RETURN

UL JUMP TO LINE

Function	Advance the execution position to a line and execute the first statement on the line.
Syntax	UL JUMP TO LINE linenumber
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	linenumber must be an integer in the range from 1 to the number of source lines, and must specify a line that is the first line of an executable statement. (It corresponds to the LINENO compilation_operand.) If linenumber is not valid, then an error message is issued, and the command is rejected. The execution position is transferred to the statement on the selected line, and that statement is executed. If more than one statement is on the line, then the first statement is transferred to and executed. Not all jumps are valid. If any of the following rules are violated, an error message is issued and the command is rejected: Jumping into or out of subroutines is not permitted. Jumping into or out of ON UNITS is not permitted. Jumping into the body of a FOR or REPEAT loop is not permitted. As an alternative to UL JUMP TO LINE, the “J” prefix command may be entered directly into the prefix area of a line to jump to. Using this prefix command on a line is identical to determining the line’s number and issuing a UL JUMP TO LINE for that line number.
Examples	UL JUMP TO LINE 5 UL JUMP TO LINE 20
See Also	compilation_operand, QA, QA Environment, UL CONTINUE, UL JUMP TO LABEL, UL LOOP END, UL RESULT, UL RETURN

UL LOOP END

Function	Exit a FOR or REPEAT loop and execute the statement following the end of the loop.
Syntax	UL LOOP END
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	If the current execution position is not inside a FOR or REPEAT loop, an error message is issued and the command is rejected.. In addition, this command is only valid if the execution position is in a loop within the current routine: it is not valid from a subroutine that is called in a loop. If the execution position is inside of a loop, then the loop is immediately exited and the statement following the end of the loop is executed. If the execution position is in a loop that is nested inside of one or more outer loops, the inner most loop that contains the execution position is the loop that is exited. Note that when the loop is exited, all the normal processing that occurs at the end of a loop still occurs, such as releasing of resources and locks.
Examples	UL LOOP END
See Also	QA, QA Environment, UL CONTINUE, UL JUMP TO LABEL, UL JUMP TO LINE, UL RESULT, UL RETURN

UL RESULT

Function	Alter the behavior of a statement that makes a flow of control decision.
Syntax	UL RESULT resultvalue
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	If the execution position is not immediately before an IF, ELSEIF, REPEAT WHILE, or computed JUMP TO, then an error message is issued and the command is rejected. In addition, resultvalue must be an integer value that is greater than or equal to zero. The statement about to be executed is made to behave as it would have if the expression evaluated to resultvalue. How behavior is influenced depends on the User Language statement. The IF, ELSEIF, and REPEAT WHILE statements make a flow of control decision based on whether the expression is Boolean true (non‑zero) or false (zero). A non-zero result value always causes the code block associated with the statement in question to execute, and a zero result causes the code block to be bypassed. For example, UL RESULT 1 before an IF would cause it to evaluate to true, and execute the block of code associated with the THEN clause of the IF. The computed JUMP TO statement uses the value of the expression to index into a list of statement labels. If the value is in the range from 1 to the number of labels inclusive, then the corresponding label is branched to, otherwise the flow of control falls through. For example, UL RESULT 3 before a computed JUMP TO would cause a branch to the 3rd label if there was one, otherwise it would cause a fall through.
Examples	UL RESULT 1 UL RESULT 0 UL RESULT 7
See Also	QA, QA Environment, UL CONTINUE, UL JUMP TO LABEL, UL JUMP TO LINE, UL LOOP END, UL RETURN

UL RETURN

Function	Return immediately from a subroutine and execute the statement following the CALL to the subroutine.
Syntax	UL RETURN
Restrictions	The context must be EVAL and the quality assurance option is required.
Description	This command will cause an immediate return from within a subroutine to the CALL statement. The statement following the CALL to the subroutine will be executed. If the execution position is not in a subroutine, then an error message is issued and the command is rejected. In addition, within a subroutine, the execution position may not be within an ON UNIT or the command is rejected.
Examples	UL RETURN
See Also	QA, QA Environment, UL CONTINUE, UL JUMP TO LABEL, UL JUMP TO LINE, UL LOOP END, UL RESULT

UNCOLLECT

Function	Terminate data collection and discard collected data.
Syntax	UNCOLLECT *
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The UNCOLLECT command terminates all data collection, and discards all collected data. UNCOLLECT may only be specified with an asterisk. If the source window contains columns created with the SHOW command that are based on collected data, then those values are replaced with hyphens to indicate missing data. Such columns can be removed with the UNSHOW command.
Examples	UNCOLLECT *
See Also	COLLECT, SHOW, UNSHOW

UNSHOW

Function	Remove columns from the source window.
Syntax	UNSHOW *
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The UNSHOW * command restores the source window to its default state by removing all data columns created with SHOW and their titles. UNSHOW may only be specified with an asterisk. It does not alter what data is being collected. The UNCOLLECT command must be used for this purpose.
Examples	UNSHOW *
See Also	SHOW, UNCOLLECT

UNWATCH

Function	Remove operands from a watch window.
Syntax	UNWATCH { operand \| pattern } [, { operand \| pattern } ]...
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The UNWATCH command removes operands from the default watch window. UNWATCH first seeks a specific operand to remove from the watch window. Only if no match is made is the specified item evaluated as a pattern. The default watch window is the same as the active window, provided that the active window is not the source window. If the active window is the source window and there is only one other open window, then that window is the default watch window. Otherwise there is no default watch window, so an error message is issued and no operands are unwatched. To temporarily change the default window while running the UNWATCH command, prefix UNWATCH with the IN WINDOW command (see Examples). The current line is adjusted so that the operand that was on the current line before execution of the UNWATCH command is on the new current line. If the operand on the current line is deleted, the current line is set to the line containing the first subsequent operand. If no lines remain following the deleted operand, the current line is set to the line containing the last operand.
Examples	UNWATCH * UNWATCH %NEXT UNWATCH %* UNWATCH CPU UNWATCH FREESIZE(METADATA) UNWATCH %X#, %Y*, DIRRCD IN WINDOW GLOBAL UNWATCH G.UDDLPP
See Also	WATCH

WATCH

Function	Display operands in a watch window.
Syntax	WATCH operand [ , operand ] ...
Restrictions	The context must be COMPILE_ERROR or EVAL.
Description	The WATCH command displays one or more operands and their values in the default watch window. The operand parameters specify the operands to watch. Watched operands remain displayed until they are removed with the UNWATCH command or the window is closed. The current line in the watch window is adjusted to be the line containing the last item watched.

Any SoftSpy operand may be specified. The special syntax G.* is used to watch all currently defined global values. If any requested operands are already being watched in the default watch window a warning message is issued. They are not added to the window again.

If there is a single watch window it is the default watch window. If there is more than one watch window the active window is the default watch window unless it is the source window. Otherwise there is no default watch window, so no operands are watched and an error message is issued.

Watch windows are created using the DEFINE WINDOW and OPEN WINDOW commands. They are called watch windows because they allow you to watch operand values as they change.

The default watch window may be temporarily altered for the duration of the WATCH command by prefixing it with the IN WINDOW command.

An operand is displayed in one of three formats. The display formats and their meanings are described below:

Display Format	Meaning
operand=value	The operand value is known and the value of the operand does not contain leading or trailing blanks. If the operand is boolean then the value is shown as 1 if it is true and as 0 if it is false.
operand='value'	The operand value is known and the value of the operand contains leading or trailing blanks.
operand is result	The operand value is not known. The result is invalid, not available, not present, undefined, or unknown.

Examples	WATCH %NEXT WATCH CPU WATCH FREESIZE(METADATA), UDDLPP WATCH %X, %Y, DIRRCD WATCH G.* IN WINDOW GLOBAL WATCH G.UDDLPP
See Also	DISPLAY, OPEN WINDOW, SHOW, UNWATCH

@@ Line 2,989: / Line 2,989: @@
 <tr><td><b>Function</b></td> <td>Alter the value of an operand.</td></tr>
-<tr><td><b>Syntax</b></td> <td>SET { $CURRENT_LINE('SOURCE') | $DEFAULT_JUMP_LIMIT | $JUMP_LIMIT | $SPY_MESSAGE | <var class="term">field_operand</var> [(<var class="term">subscript</var>)] | <var class="term">global_variable_operand</var> | <var class="term">percent_variable_operand</var> | <var class="term">softspy_variable</var> } = <var class="term">expression</var></td></tr>
+<tr><td><b>Syntax</b></td> <td>[[File: SoftSpy_SET_command.jpg| 350px]]</td></tr>
 <tr><td><b>Description</b></td> <td>The SET command alters the value of SoftSpy operands. The first parameter specifies the operand whose value is to be altered. The <var class="term">expression</var> is evaluated and the resulting value is assigned to the target operand. If the result of the <var class="term">expression</var> is not KNOWN an error message is issued and the operand is not altered unless the operand is a <var class="term">softspy variable</var>.

SoftSpy commands and macros: Difference between revisions

Revision as of 22:54, 20 March 2014

Introduction

Lists of commands by functional area

Basic commands

Interactive execution commands

Operand display and manipulation commands

Scrolling commands

Print commands

Window commands

Advanced commands and commands used in macros

Macro commands

Administrative commands

SoftSpy command descriptions

comment

ACTIVE WINDOW

AUDIT

BACKWARD

BOTTOM

BREAK

BREAKS

BROWSE ACL

BROWSE MACRO

CLEAR BREAK

CLOSE PRINTER

CLOSE WINDOW

COLLECT

COMMAND

COPY ACL

COPY MACRO

COVERAGE

DATETIME

DEBUG

DEFAULT LINE

DEFAULT PRINTER

DEFINE SoftSpy_variable

DEFINE WINDOW

DELETE ACL

DELETE MACRO

DELETE SoftSpy_variable

DELETE WINDOW

DISPLAY

EDIT ACL

EDIT CONFIG

EDIT MACRO

ERROR

EXEC

FORWARD

GLOBALS

GO

HELP

IF

IN WINDOW

JUMP TO

LAST

LEFT

LIST ACL

LIST MACRO

LOCATE

M204

NEW PAGE

NEXT

ON

OPEN PRINTER

OPEN WINDOW

PF

PRINT ACL

PRINT HELP

PRINT LINE

PRINT LIST

PRINT MACRO

PRINT WINDOW

QA

QUAD

QUIT

RENAME ACL

RENAME MACRO

REPEAT

RETRIEVE

RETURN

DEFINE `SoftSpy_variable`