SoftSpy commands and macros
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.
- 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.
- 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
- The SoftSpy version number.
- The serial number of your copy of SoftSpy.
- 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
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
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 |
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 |
See Also | OPEN WINDOW |
COLLECT
Function | Initiate collection of statistic_operand and usage_operand data by statement during User Language request evaluation. |
Syntax | COLLECT { statistic_operand | usage_operand } [, { statistic_operand | usage_operand } ]... |
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 |
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 |
DEFAULT PRINTER { TERMINAL | [DATASET | PRINTER | PUNCH] [printer_id] [WITH parm [, parm]...] } |
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 |
See Also | OPEN PRINTER |
DEFINE SoftSpy_variable
Function | Define a SoftSpy_variable. |
Syntax |
DEFINE SoftSpy_variable [ IS ] { STRING LEN n | FIXED } [ LOCAL | SESSION ] |
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 |
See Also |
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 |
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 |
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 |
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:
| ||||||||
Examples | DISPLAY %NEXT | ||||||||
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
| |
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 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
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: These items are displayed but cannot be modified: 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
| ||
Examples | 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 |
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 |
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 |
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:
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 |
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 * |
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 |
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 |
See Also | $ACTIVE_WINDOW, $DEFAULT_WATCH_WINDOW, ACTIVE WINDOW |
JUMP TO
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 |
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 |
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 |
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 |
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 01 SEP 2012 12:00:00 LIST MACRO =================================================================================== UPDATE UPDATE UPDATE NAME LINES USERID DATE TIME > ALL_TYPES 23 STEVE 20 FEB 1992 16:42:59 = ALTPF 12 STEVE 18 JUN 1992 15:54:15 = ALTPF1 12 STEVE 18 JUN 1992 16:12:26 = ANT 5 ANTHONY 09 AUG 1994 12:44:16 = ANTHONY_ON_EVAL 19 ANTHONY 18 APR 1994 13:50:44 = ANTHONY_PROFILE 8 ANTHONY 19 JUL 1994 15:37:20 = A1 2 GEORGEW 03 AUG 1994 11:58:10 = B 1 KAREN 08 FEB 1994 15:16:36 = BKBM 2 ANTHONY 11 NOV 1993 16:59:50 = BN 41 MICHAEL 26 JUN 1994 14:58:59 = BOB_ARRAY 82 BOB 03 SEP 1993 12:38:41 = BOB_ARRAY_D 9 BOB 27 AUG 1993 08:21:18 = BOB_BREAKS 31 BOB 02 SEP 1993 10:41:14 = BOB_WATCH 9 BOB 23 AUG 1993 10:16:06 => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 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 |
See Also | LIST Environment |
LOCATE
Function | Find a character string in the active window. |
Syntax | [ - ] { /string [ / ] | LOCATE pattern } |
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 |
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 |
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 |
NEXT
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 |
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 | ON {BREAK | CANCEL | COMPILE_ERROR | END_EVAL | EVAL | NON_CANCEL | USER_CANCEL} [softspy_command] | ||||||||||||||
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:
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 | ||||||||||||||
See Also | GO, STEP |
OPEN PRINTER
Function | Open a destination for print output. |
Syntax |
OPEN PRINTER [ TERMINAL | [DATASET | PRINTER | PUNCH] [printer_id] [WITH parm [, parm]...]] |
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 |
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 |
See Also | CLOSE WINDOW, DEFINE WINDOW, WATCH |
PF
Function | Assign a command to a program function key. |
Syntax |
{ PF n | PAI } [ ( { BROWSE | COMPILE_ERROR | CONFIG | EDIT | EVAL | HELP | LIST } ) ] [label] = [softspy_command]
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 |
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 |
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' |
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 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 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 |
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
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: 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 |
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 |
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 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 |
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 |
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 |
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 |
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 |
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: |
Examples | SCREEN SOURCE 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 |
SET
Function | Alter the value of an operand. |
Syntax | SET { $CURRENT_LINE('SOURCE') | $DEFAULT_JUMP_LIMIT | $JUMP_LIMIT | $SPY_MESSAGE | field_operand [(subscript)] | global_variable_operand | percent_variable_operand | softspy_variable } = expression |
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_LIMITSET 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_LIMITSET 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_MESSAGEIf $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 FieldsA 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: 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' |
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: |
{ [ HISTOGRAM ] [ PERCENT | AVERAGE ] statistic_operand | [ AVERAGE ] usage_operand | [ BRACKET ] compilation_operand | quality_assurance_operand }
[ LEN n | DP n | NOTITLE | TITLE str [ str ] ]...
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: 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: 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: 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: SHOW Histogram Screen
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
The following characters are used to draw the brackets:
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 | ||||||||||||||
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] 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 |
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 |
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 |
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 |
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 |
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:
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 |
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 |
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: |
Examples | TRACE ON |
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 |
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: 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: 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 |