SoftSpy commands and macros: Difference between revisions

From m204wiki
Jump to navigation Jump to search
Line 2,989: Line 2,989:
<tr><td><b>Function</b></td> <td>Alter the value of an operand.</td></tr>
<tr><td><b>Function</b></td> <td>Alter the value of an operand.</td></tr>


<tr><td><b>Syntax</b></td> <td>SET { $CURRENT_LINE('SOURCE') | $DEFAULT_JUMP_LIMIT | $JUMP_LIMIT | $SPY_MESSAGE | <var class="term">field_operand</var> [(<var class="term">subscript</var>)] | <var class="term">global_variable_operand</var> | <var class="term">percent_variable_operand</var> | <var class="term">softspy_variable</var> } = <var class="term">expression</var></td></tr>
<tr><td><b>Syntax</b></td> <td>[[File: SoftSpy_SET_command.jpg| 350px]]</td></tr>


<tr><td><b>Description</b></td> <td>The SET command alters the value of SoftSpy operands. The first parameter specifies the operand whose value is to be altered. The <var class="term">expression</var> is evaluated and the resulting value is assigned to the target operand. If the result of the <var class="term">expression</var> is not KNOWN an error message is issued and the operand is not altered unless the operand is a <var class="term">softspy variable</var>.
<tr><td><b>Description</b></td> <td>The SET command alters the value of SoftSpy operands. The first parameter specifies the operand whose value is to be altered. The <var class="term">expression</var> is evaluated and the resulting value is assigned to the target operand. If the result of the <var class="term">expression</var> is not KNOWN an error message is issued and the operand is not altered unless the operand is a <var class="term">softspy variable</var>.

Revision as of 22:54, 20 March 2014

Introduction

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

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

SoftSpy commands perform a variety of functions including:

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

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

    Basic commands

    Command Function

    AUDIT

    Establish the interactive audit environment.

    DEBUG

    Establish the interactive debugging environment.

    HELP

    Request SoftSpy help information.

    QA

    Establish the interactive quality assurance testing environment.

    QUIT

    Quit the current SoftSpy function or cancel the current User Language request.

    REPEAT

    Repeat the last command entered on the command line.

    RETRIEVE

    Recall a previously entered command.

    SPY AUDIT OFF

    Deactivate the SoftSpy audit feature.

    SPY AUDIT ON

    Activate the SoftSpy audit feature.

    SPY OFF

    Terminate a SoftSpy session.

    SPY ON

    Start a SoftSpy session.

    SPY ON THREAD

    Start a SoftSpy server session to debug another User Language thread.

    SPY ON USER

    Start a SoftSpy server session to debug another User Language thread.

    TUNE

    Establish the interactive performance tuning environment.

    Interactive execution commands

    Command Function

    BREAK

    Set a break point.

    BREAKS

    Set break points following User Language request lines that contain *BREAK.

    CLEAR BREAK

    Clear break points.

    DEFAULT LINE

    Indicate whether to focus on the last statement executed or the next statement to execute.

    GO

    Start or resume evaluation of a User Language request until an interrupt or a user-specified condition occurs.

    QUAD

    Make the current statement the statement containing the specified quad offset.

    STEP

    Start or resume evaluation of a User Language request for a specified number of statements or until an interrupt occurs.

    TRACER

    Start or resume evaluation of a User Language request and print a trace of statements executed.

    UL CONTINUE

    Advance the execution position to the next iteration of a FOR or REPEAT loop.

    UL JUMP TO LABEL

    Advance the execution position to a statement label or statement number and execute that statement.

    UL JUMP TO LINE

    Advance the execution position to a line and execute the first statement on the line.

    UL LOOP END

    Exit a FOR or REPEAT loop and execute the statement following the end of the loop.

    UL RESULT

    Alter the behavior of a statement that makes a flow of control decision.

    UL RETURN

    Return immediately from a subroutine and execute the statement following the CALL to the subroutine.

    Operand display and manipulation commands

    Command Function

    COLLECT

    Initiate the collection of statistic_operand and usage_operand data, statement by statement, during User Language request evaluation.

    COVERAGE

    Display test coverage information about the current User Language request.

    DISPLAY

    Display operands.

    GLOBALS

    Watch all currently defined global variables.

    SET

    Alter the value of an operand.

    SHOW

    Add columns to the source window that display statistic, usage, quality assurance, or compilation operands by line.

    STATS

    Watch all statistic_operands and usage_operands.

    UNCOLLECT

    Terminate data collection and discard collected data.

    UNSHOW

    Remove columns from the source window.

    UNWATCH

    Remove operands from a watch window.

    WATCH

    Display operands in a watch window.

    Scrolling commands

    Command Function

    BACKWARD

    Scroll backward in the active window.

    BOTTOM

    Scroll to the bottom of the active window.

    FORWARD

    Scroll forward in the active window.

    LAST

    Scroll backward in the execution history of the current User Language request.

    LEFT

    Scroll to the left in the active window.

    LOCATE

    Find a character string in the active window.

    NEXT

    Scroll forward in the execution history of the current User Language request.

    RIGHT

    Scroll to the right in the active window.

    SCROLL

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

    TOP

    Scroll to the top of the active window.

    Print commands

    Command Function

    CLOSE PRINTER

    Close the destination for print output.

    DEFAULT PRINTER

    Set the default destination and parameters for print output.

    NEW PAGE

    Begin a new page.

    OPEN PRINTER

    Open a destination for print output.

    PRINT ACL

    Print an access control list.

    PRINT HELP

    Print SoftSpy help information.

    PRINT LINE

    Print a line.

    PRINT LIST

    Print a list of access control lists or macros.

    PRINT MACRO

    Print a macro.

    PRINT WINDOW

    Print the contents of a window.

    Window commands

    Command Function

    ACTIVE WINDOW

    Set the active window.

    CLOSE WINDOW

    Close a window and remove it from the screen.

    DEFINE WINDOW

    Define a window.

    DELETE WINDOW

    Delete a window definition.

    IN WINDOW

    Temporarily alter the active window while a command is executed.

    OPEN WINDOW

    Display a window on the screen.

    SCREEN

    Change the layout of the SoftSpy screen by ordering the screen elements (such as borders and messages).

    Advanced commands and commands used in macros

    Command Function

    comment

    Document macros.

    COMMAND

    Dynamically build and execute a command.

    DATETIME

    Control display of the date and time.

    DEFINE softspy_variable

    Define a softspy_variable.

    DELETE softspy_variable

    Delete a softspy_variable.

    ERROR

    Issue an error message.

    IF

    Conditionally execute a command.

    JUMP TO

    Branch to a different location in a macro.

    M204

    Execute a Model 204 command.

    ON

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

    PF

    Assign a command to a program function key.

    RETURN

    Terminate a macro and return to the point of invocation.

    SPY softspy_command

    Issue SoftSpy commands from the Model 204 command line.

    TRANSFER

    Transfer control to a command from a macro.

    Macro commands

    Command Function

    BROWSE MACRO

    Browse a macro.

    COPY MACRO

    Copy a macro.

    DELETE MACRO

    Delete a macro.

    EDIT MACRO

    Create or edit a macro.

    EXEC

    Execute a macro.

    LIST MACRO

    Display a list of macros.

    RENAME MACRO

    Rename a macro.

    SAVE MACRO

    Save a macro and continue editing.

    TRACE

    Produce a debugging trace when macros are run.

    Administrative commands

    Command Function

    BROWSE ACL

    Browse an access control list.

    COPY ACL

    Copy an access control list.

    DELETE ACL

    Delete an access control list.

    EDIT ACL

    Create or edit an access control list.

    EDIT CONFIG

    Edit the SoftSpy configuration.

    LIST ACL

    Display a list of access control lists.

    RENAME ACL

    Rename an access control list.

    SAVE ACL

    Save an access control list and continue editing.

    SAVE CONFIG

    Save the SoftSpy configuration and continue editing.

    SPY SERVER

    Start a SoftSpy server.

    SoftSpy command descriptions

    The following sections describe each SoftSpy command in detail.


    comment

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

    * * This is a comment. * ********************************* * * * Comments can be written * * in many styles * * * *********************************


    ACTIVE WINDOW

    Function Set the active window.
    Syntax ACTIVE WINDOW [ window_identifier ]
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The ACTIVE WINDOW command sets the window in which subsequent commands are executed. The window_identifier specifies

    which window to make active. It can be the SOURCE window or a window opened with the OPEN WINDOW command. If the window_identifier does not specify an open window, an error message is issued and the active

    window is not changed.

    The active window changes to another open window if no window_identifier is used. ACTIVE WINDOW can thus be used repeatedly to cycle through all open windows.

    A highlighted equal sign (=) character is used as the border character for the active window. A dim hyphen (-) character is used is the border character for all other windows.

    The BACKWARD, BOTTOM, FORWARD, LEFT, LOCATE, PRINT WINDOW, RIGHT, and TOP commands all operate in the context of the active window. The UNWATCH and WATCH commands operate in the context of the default watch window. The default watch window is the same as the active window unless the active window is the source window.

    Examples

    ACTIVE WINDOW
    ACTIVE WINDOW SOURCE
    ACTIVE WINDOW MONITOR
    ACTIVE WINDOW GLOBALS

    See Also $ACTIVE_WINDOW, $DEFAULT_WATCH_WINDOW, IN WINDOW

    AUDIT

    Function Establish the interactive audit environment.
    Syntax AUDIT
    Restrictions The context must be EVAL and the audit option is required.
    Description The AUDIT macro is used to switch to the interactive audit environment, or to reinitialize the interactive audit environment.

    The lines of User Language requests are prefixed with brackets showing the statement nesting level and the cumulative QTBL usage in bytes for each line. A monitor window in which operands can be watched is placed in the upper right corner of the screen. The default line is set to the next executable statement.

    Any data collection is terminated and any collected data is discarded.

    Audit screen

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

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

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

    Examples

    AUDIT

    See Also AUDIT environment, DEBUG, QA, TUNE

    BACKWARD

    Function Scroll backward in the active window.
    Syntax

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

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

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

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

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

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

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

    Examples

    BACKWARD - BACKWARD 100 -HALF BACKWARD ERROR IN WINDOW SOURCE -ERROR

    See Also FORWARD

    BOTTOM

    Function Scroll to the bottom of the active window.
    Syntax BOTTOM
    Description The BOTTOM macro scrolls to the last line of data available in the active window. The last line becomes the current line.

    The active window may be temporarily altered for the duration of the BOTTOM macro by prefixing it with the IN WINDOW command.

    Examples BOTTOM
    See Also TOP

    BREAK

    Function Set a break point.
    Syntax BREAK
    Restrictions The context must be EVAL.
    Description The BREAK command is used to set a break point on the current line in the source window, provided that the current line is executable. The letter "B" is placed in the prefix area of the line to indicate that a break point is set on the line.

    If the line is not executable, an error message is issued and no break point is set. Lines that are not executable include continuation lines, comment lines, screen definition statements, and other types of declare statements. An error message is also issued if a break point is already set on the line.

    As an alternative to issuing a BREAK command, a "B" prefix command can be entered directly into the prefix area of a source statement line.

    Examples

    BREAK

    See Also BREAKS, CLEAR BREAK

    BREAKS

    Function Set break points following User Language request lines that contain *BREAK.
    Syntax BREAKS
    Restrictions The context must be EVAL.
    Description The BREAKS macro scans the source program from the line following the current line to the end of the source program for lines containing *BREAK. Whenever *BREAK is found, a break point is set on the next executable statement.

    If no line containing *BREAK is found, the current line in the source window is left unchanged, and the error message 'NO BREAK POINTS REQUESTED' is displayed.

    If break points are requested and successfully set, the current line in the source window is set to the last line on which a break point was set.

    If a break point cannot be set on the next executable statement following *BREAK, the current source window line is set to the first such line, and an error message is issued.

    Examples

    BREAKS

    See Also BREAK, CLEAR BREAK

    BROWSE ACL

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

    BROWSE ACL Screen

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

    Examples

    BROWSE ACL ADMIN

    See Also BROWSE environment, EDIT ACL

    BROWSE MACRO

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

    BROWSE MACRO Screen

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

    Examples

    BROWSE MACRO PROFILE

    See Also BROWSE environment, EDIT MACRO

    CLEAR BREAK

    Function Clear break points.
    Syntax CLEAR BREAK [ ALL ]
    Restrictions The context must be EVAL.
    Description The CLEAR BREAK command is used to clear break points. All break points are cleared if the ALL parameter is specified, otherwise only the break point on the current line in the source window is cleared. If ALL is not specified and a break point is not set on the current line in the source window, an error message is issued.

    The letter "B" is removed from the prefix area of all source statement lines affected by CLEAR BREAK.

    A break point may also be cleared by removing the "B" from the prefix area of a source statement line. This can be accomplished by clearing the prefix area or by typing a blank or another prefix character over the "B".

    Examples

    CLEAR BREAK CLEAR BREAK ALL

    See Also BREAK, BREAKS

    CLOSE PRINTER

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

    CLOSE PRINTER

    See Also OPEN PRINTER

    CLOSE WINDOW

    Function Close a window and remove it from the screen.
    Syntax CLOSE WINDOW window_identifier
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The CLOSE WINDOW command closes a window and removes it from the screen. The window_identifier parameter specifies the name of the window to close. If an open window name is not specified, an error message is issued.

    Closing a window removes it from the screen. Source statement lines covered by the window become visible. The SOURCE window may not be closed. If the active window is closed, the SOURCE window becomes the new active window.

    Examples

    CLOSE WINDOW MONITOR
    CLOSE WINDOW STATS
    CLOSE WINDOW GLOBALS

    See Also OPEN WINDOW

    COLLECT

    Function Initiate collection of statistic_operand and usage_operand data by statement during User Language request evaluation.
    Syntax
    Restrictions Context must be COMPILE_ERROR or EVAL.
    Description The COLLECT command is used to initiate collection of statistic_operand or usage_operand data. Detailed statement by statement information is gathered showing the cumulative evaluation time net change in the requested statistic and usage operands. This statement level data can be accessed with the $SOURCE_LINE_INFO function, or can be displayed in the source window using the SHOW command.

    Once collection is initiated, it continues until terminated with an UNCOLLECT command. Subsequent COLLECT commands initiate the collection of additional statistic or usage operands. In order to ensure consistency in collected data, a COLLECT command is rejected with an error if data has already been collected within the current request. In this situation you must either wait until the beginning of the next request, or issue an UNCOLLECT command to clear all collected data first. A new request is initiated by the Model 204 BEGIN and MORE commands.

    If averages or the quality_assurance_operands TESTED, UNTESTED, or TEST_STATUS are required, EXECOUNT statistic_operand must be collected.

    There are restrictions on which operands can be collected based on which optional SoftSpy features are available. The description of each operand identifies restrictions on its use. If an operand cannot be collected, an error message is issued, and collection is not initiated.

    The optional statistic_operand qualifiers of LOGIN, SPY, EVAL, or STMT must be omitted or an error message will be issued. They are not meaningful for data collection.

    Examples

    COLLECT EXECOUNT
    COLLECT DKRD, CCATEMP
    COLLECT VTBL
    COLLECT CPU, CNCT

    See Also SHOW, UNSHOW, UNCOLLECT

    COMMAND

    Function Dynamically build and execute a command.
    Syntax COMMAND expression
    Description The COMMAND command is used to dynamically build and execute a SoftSpy command.

    The expression is evaluated to produce a command. The command is then dynamically executed. If the result of the expression is not KNOWN, an error message is issued.

    The dynamically built command can be a COMMAND command. However, at most ten levels of recursively built COMMAND commands are allowed. If this limit is exceeded an error message is issued.

    Examples

    COMMAND 'FORWARD ' WITH $COMMAND COMMAND 'DISPLAY ' WITH $MACRO_ARGS COMMAND 'CLOSE WINDOW ' WITH $DEFAULT_WATCH_WINDOW COMMAND 'DISPLAY F.''' WITH $COMMAND WITH ''''


    COPY ACL

    Function Copy an access control list.
    Syntax COPY ACL access_control_list_identifier TO [ACL] access_control_list_identifier
    Restrictions The UPDATE ACL privilege is required.
    Description The COPY ACL command copies an access control list. The first access_control_list_identifier specifies the name of the access control list to copy. If the specified access control list does not exist, an error message is issued.

    The second access_control_list_identifier specifies the name of the new access control list to create. If an access control list already exists with this name, an error message is issued. The keyword ACL must proceed the new access control list name if it is ACL.

    Examples

    COPY ACL ADMIN TO OLD_ADMIN COPY ACL ADMIN TO ACL OLD_ADMIN


    COPY MACRO

    Function Copy a macro.
    Syntax COPY MACRO macro_identifier TO [ MACRO ] macro_identifier
    Restrictions The READ MACRO privilege is required unless the name of the macro to be copied begins with the user's id followed by an underscore. The UPDATE MACRO privilege is required unless the new macro name begins with the user's id followed by an underscore.
    Description The COPY MACRO command copies a macro. The first macro_identifier specifies the name of the macro to copy. If the specified macro does not exist, an error message is issued.

    The second macro_identifier specifies the name of the new macro to create. If a macro already exists with this name, an error message is issued. The keyword MACRO must proceed the new macro name if it is MACRO.

    Examples

    COPY MACRO PROFILE TO OLD_PROFILE COPY MACRO PROFILE TO MACRO OLD_PROFILE


    COVERAGE

    Function Display test coverage information about the current User Language request.
    Syntax COVERAGE [ GO ]
    Restrictions The context must be EVAL and the quality assurance testing option is required.
    Description A message is displayed showing the number of statements that have been tested and the total number of statements that are reachable in the current User Language request. The message also identifies the number of unreachable or dead statements in the request. The message is of one of the following forms:

    All num reachable statements tested, no unreachable statements All num1 reachable statements tested, num2 unreachable statements num1 of num2 reachable statements tested, no unreachable statements num1 of num2 reachable statements tested, num3 unreachable statements

    If the context is not EVAL or the EXECOUNT statistic option is not being collected, then an error message is issued and the message is not displayed.

    If the GO option is specified, a GO command is issued before the message is displayed unless evaluation of the current User Language request was already completed.

    Examples

    COVERAGE COVERAGE GO


    DATETIME

    Function Control display of the date and time.
    Syntax

    DATETIME { OFF | ON }

    Description The DATETIME command controls whether or not the date and time are displayed in the upper right corner on SoftSpy screens. They are initially displayed by default. DATETIME OFF indicates the date and time should not be displayed. DATETIME ON indicates the date and time should be displayed.
    Examples

    DATETIME OFF DATETIME ON


    DEBUG

    Function Establish the interactive debugging environment.
    Syntax DEBUG
    Restrictions The context must be EVAL and the interactive debugging option is required.
    Description The DEBUG macro is used to switch to the interactive debugging environment, or to reinitialize the interactive debugging environment.

    The lines of User Language requests are prefixed with brackets showing the statement nesting level. A monitor window in which operands can be watched is placed in the upper right corner of the screen. The default line is set to the next executable statement. Any data collection is terminated and any collected data is discarded.

    DEBUG Screen

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

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

    DEBUG

    See Also DEBUG Environment, AUDIT, QA, TUNE

    DEFAULT LINE

    Function Indicate whether to focus on the last statement executed or the next statement to execute.
    Syntax DEFAULT LINE { LAST | NEXT }
    Restrictions The context must be EVAL.
    Description The DEFAULT LINE command indicates whether to focus on the LAST statement executed

    or the NEXT statement to execute. It is usual to focus on the next statement to execute when debugging because you can easily see which statement will be executed next. In the case of performance tuning, it is usual to focus on the last statement executed because statistic values include that statement.

    The focus specified by DEFAULT LINE takes effect immediately and remains in effect until it is reset. Changing the focus changes the current line, the execution point display at the top of the evaluation screen, and the position in the history of executed statements. The behavior of subsequent STEP and GO commands is similarly affected by the focus.

    If LAST is specified then the current line is positioned at the first line of the last statement executed. The execution point indicator at the top of the evaluation screen shows the line number of the last statement executed in the current request. If no statements have yet been executed it indicates LAST NONE. The current position in the history of executed statements is set to the last statement executed.

    If NEXT is specified then the current line is positioned at the first line of the next statement to be executed. The execution point indicator at the top of the evaluation screen shows the line number of the next statement to execute in the current request. If no statements remain to execute it indicates NEXT NONE. The current position in the history of executed statements is set to the next statement to execute.

    Examples

    DEFAULT LINE LAST DEFAULT LINE NEXT

    See Also GO, LAST, NEXT, STEP

    DEFAULT PRINTER

    Function Set the default destination and parameters for print output.
    Syntax

    Description The DEFAULT PRINTER command alters the default destination for print output. Various aspects of the format of print output can also be controlled. The initial default print destination is the TERMINAL.

    The output destination is not actually opened. The OPEN PRINTER command can be used to explicitly open the print destination, or individual PRINT commands may implicitly open and close the default print destination.

    The print destination may be a DATASET, PRINTER, PUNCH, or the TERMINAL. The TERMINAL option takes no arguments. The other destination options require conformance with the syntax of the Model 204 USE command. In addition, SoftSpy supports two additional parameters for these destinations. A parameter of CCC=n can be specified, where n is the desired continuation column setting. Similarly, a parameter of LPP=n can be specified, where n is the desired number of lines per page.

    Examples

    DEFAULT PRINTER TERMINAL
    DEFAULT PRINTER OUT1
    DEFAULT PRINTER PUNCH PUNCH1
    DEFAULT PRINTER DATASET REPORT
    DEFAULT PRINTER PRINTER WITH
    ROUTER=VM,ID=GEORGE

    See Also OPEN PRINTER

    DEFINE SoftSpy_variable

    Function Define a SoftSpy_variable.
    Syntax

    Description The DEFINE command defines a SoftSpy_variable operand. SoftSpy_variable operands must be defined before being referenced.

    The name of the SoftSpy_variable may be up to twenty characters long. The first character must be a dollar sign. Subsequent characters may be alphabetic, numeric, or the underscore.

    The SoftSpy_variable must be defined as either type STRING or type FIXED. It should be defined as type STRING if it will contain character string values. In this case a maximum character string length in the range 1 to 255 must be specified. It should be defined as FIXED if it will contain numeric integer values. String variables are initialized to a null string. Fixed variables are initialized to zero.

    The SoftSpy_variable can be defined with a scope of LOCAL or SESSION. LOCAL is the default, and indicates that the SoftSpy_variable is only accessible within the macro in which it is defined. SESSION indicates that the SoftSpy_variable has no accessibility restrictions. SESSION must be specified if a DEFINE command is issued outside a macro.

    SoftSpy_variables with LOCAL scope are automatically deleted when the macro they were defined within terminates. SoftSpy_variables with SESSION scope exist for the duration of the SoftSpy session. Any SoftSpy_variable can be explicitly deleted sooner with the DELETE SoftSpy_variable command.

    A SoftSpy_variable can be defined with SESSION scope if it is not already defined with SESSION scope, or with LOCAL scope within the currently executing macro. A SoftSpy_variable can be defined with LOCAL scope if it is not already defined with LOCAL scope within the currently executing macro.

    Examples

    DEFINE $TEMPF IS STRING LEN 6
    DEFINE $L IS FIXED
    DEFINE $MACRO_NAME STRING LEN 18 LOCAL
    DEFINE $TEMP STRING LEN 255 SESSION
    DEFINE $END_EVAL_SCROLL_TOP FIXED SESSION

    See Also

    DELETE SoftSpy_variable


    DEFINE WINDOW

    Function Define a window.
    Syntax

    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The DEFINE WINDOW command is used to define a SoftSpy window. The window_identifier names the window. It must not specify the name of a window that is already defined, or an error message is issued. Once a window is defined the OPEN WINDOW command may be used to display the window on the terminal.

    The COLUMN keyword is followed by a left_column parameter specifying a window's first column, the word TO, and a right_column parameter specifying a window's last column. The left_column must be greater than or equal to six. The right_column must be less than or equal to 77 and at least two larger than the left_column. Columns adjacent to a window are reserved for screen format control. If the COLUMN parameter is omitted then it will be required when the window is opened.

    The ROW keyword is followed by a top_line parameter specifying a window's top line, the word TO, and a bottom_line parameter specifying a window's bottom line. The top_line must be greater than or equal to one. The bottom_line must be less than or equal to 16 minus the number of title lines created by SHOW commands, and at least two larger than the top_line. If the ROW parameter is omitted then it will be required when the window is opened.

    The WATCH parameter identifies operands to watch in the window.

    Examples

    DEFINE WINDOW MONITOR ROW 1 TO 12 COLUMN 51 TO 77
    DEFINE WINDOW GLOBALS
    DEFINE WINDOW STATS WATCH (CPU, DKPR)
    DEFINE WINDOW INFO COLUMN 50 TO 77
    DEFINE WINDOW WATCH COLUMN 50 TO 77 ROW 1 TO 6

    See Also DELETE WINDOW, OPEN WINDOW

    DELETE ACL

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

    DELETE ACL ADMIN


    DELETE MACRO

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

    DELETE MACRO OLDPROFILE


    DELETE SoftSpy_variable

    Function Delete a Softspy variable.
    Syntax DELETE SoftSpy_variable [ LOCAL | SESSION ]
    Description The DELETE SoftSpy_variable command deletes the designated SoftSpy variable. The variable must have been previously defined with the DEFINE SoftSpy_variable command.

    The scope of LOCAL or SESSION specified on the DELETE command must match the scope specified on the DEFINE command. If it does not match then an error message is issued and the variable is not deleted.

    A variable with a scope of LOCAL can only be deleted from within the macro in which it was defined. A variable with a scope of SESSION may not be deleted from within a macro that has a LOCAL variable defined with the same name.

    Examples

    DELETE $L
    DELETE $TEMPO LOCAL
    DELETE $TUNE_PF10 SESSION

    See Also DEFINE softspy_variable

    DELETE WINDOW

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

    DELETE WINDOW MONITOR
    DELETE WINDOW STATS
    DELETE WINDOW GLOBALS

    See Also CLOSE WINDOW, DEFINE WINDOW

    DISPLAY

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

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

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

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

    See Also SHOW, WATCH

    EDIT ACL

    Function Create or edit an access control list.
    Syntax EDIT ACL access_control_list_identifier
    Restrictions The UPDATE ACL privilege is required.
    Description The EDIT ACL command creates or edits an access control list. The access_control_list_identifier specifies the name of the access control list to edit. If the specified list does not exist, a new access control list with the name specified is created.

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

    EDIT ACL Screen

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

    Examples EDIT ACL ADMIN
    See Also DELETE ACL, EDIT Environment, SAVE ACL, QUIT

    EDIT CONFIG

    Function Edit the SoftSpy configuration.
    Syntax EDIT CONFIG
    Restrictions You must belong to the ADMIN subsystem class for the SoftSpy subsystem and you must have invoked SoftSpy using the SPY softspy_command command rather than the SPY ON command.
    Description The EDIT CONFIG command is used to edit the SoftSpy configuration. Several aspects of the configuration may be changed from the EDIT CONFIG screens.

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

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

    • If square bracket characters are displayed on SoftSpy user terminals. Square brackets are not available on all 3270 terminals. If "N" (no) is selected SoftSpy help uses vertical bar characters in place of square brackets in syntax diagrams. Otherwise square brackets are used.
    • The names of the access control lists which define who is authorized to take the following actions:

      • Issue the M204 command from the SoftSpy command line or from within user macros.
      • Issue the M204 command from within system macros.
      • Read access control lists.
      • Read system macros.
      • Issue the SPY SERVER command.
      • Issue the SPY ON command.
      • Update access control lists.
      • Update system macros.

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

    EDIT CONFIG Definition Screen

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

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

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

    These items are displayed but cannot be modified:

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

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

    EDIT CONFIG Authorization Entry Screen

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

    Examples

    EDIT CONFIG
    SPY EDIT CONFIG

    See Also CONFIG Environment, SAVE CONFIG, QUIT

    EDIT MACRO

    Function Create or edit a macro.
    Syntax EDIT MACRO macro_identifier
    Restrictions The READ MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
    Description The EDIT MACRO command creates or edits a macro. The macro_identifier specifies the name of the macro to edit. If the specified macro does not exist, a new macro with the name specified is created.

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

    EDIT MACRO Screen

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

    Examples

    EDIT MACRO PROFILE
    EDIT MACRO KAREN_PROFILE

    See Also DELETE MACRO, EDIT Environment, QUIT, SAVE MACRO

    ERROR

    Function Issue an error message.
    Syntax ERROR expression
    Description The ERROR macro issues an error message. The expression parameter is evaluated. The resulting string is displayed with a prefix of "ERROR: ". This allows macros to issue error messages. If the result of the expression is not KNOWN, an error message is issued.
    Examples

    ERROR 'PF2 NOT SUPPORTED IN THIS CONTEXT' ERROR 'INVALID COMMAND LINE VALUE OF ' WITH $COMMAND


    EXEC

    Function Execute a macro.
    Syntax [ EXEC ] macro_identifier [ parameter_string ]
    Description The EXEC command executes a macro. The macro_identifier parameter specifies the name of the macro to execute. If the macro specified does not exist, an error message is issued. The EXEC keyword can be omitted if the macro name is not the same as a SoftSpy command name. In effect this lets you use macros to create new SoftSpy commands.

    Parameters supplied by the parameter_string in EXEC commands can be referenced with the $MACRO_ARGS function within the invoked macro. The macro must perform any required parameter parsing. The parameter string begins with the first non-blank character following the macro_identifier. The macro name is terminated by any character except alphanumeric characters and the underscore, colon, percent sign, dollar sign, single quote, and double quote characters.

    The maximum number of JUMP TO commands that may be executed in a macro is controlled by the value of $JUMP_LIMIT for the macro. The initial value of $JUMP_LIMIT for a macro is set to the value of $DEFAULT_JUMP_LIMIT.

    Macros can be nested up to a maximum level of ten. If this limit is exceeded, a message is issued and all macros are terminated.

    Examples

    EXEC PROFILE
    PROFILE
    EXEC SCROLL MAX CPU
    EXEC TUNE
    TUNE
    REPORT DKRD

    See Also $DEFAULT_JUMP_LIMIT, $JUMP_LIMIT, $MACRO_ARGS

    FORWARD

    Function Scroll forward in the active window.
    Syntax { FORWARD | + } [ FULL | HALF | n | ERROR ]
    Description The FORWARD command scrolls forward the distance specified in the active window. It allows the display of data following the portion visible in the window by moving data upward.

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

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

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

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

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

    Examples

    FORWARD
    FORWARD ERROR
    +HALF
    FORWARD 100
    + 100
    IN WINDOW STATS +20

    See Also BACKWARD

    GLOBALS

    Function Watch all currently defined global variables.
    Syntax GLOBALS
    Restrictions The context must be COMPILE_ERROR or EVAL and the interactive debugging option is required.
    Description The GLOBALS macro watches all defined global variables in the default watch window.

    An error message is issued if there is no default watch window or the interactive debugging option is not available.

    Examples GLOBALS
    See Also global_variable_operand, WATCH

    GO

    Function Start or resume evaluation of a User Language request until an interrupt or user-specified condition occurs.
    Syntax GO [ FOREVER ] [ UNTIL expression ]
    Restrictions The context must be EVAL.
    Description The GO command resumes request evaluation for at least one statement. Evaluation is normally suspended again when any of the following conditions occur:
    • Any UNTIL condition is true or the result is not KNOWN
    • A break point is encountered
    • An evaluation-time error occurs (either cancelling or non-cancelling)
    • Evaluation of a User Language request is completed
    • Evaluation of a User Language request is begun
    • A User Language request fails to successfully compile and the interactive debugging option is available

    Normally evaluation is suspended at break points or at the beginning or end of request evaluation. However, this is not the case if FOREVER is specified. FOREVER causes evaluation to continue across multiple requests until an error occurs or a condition you specify is satisfied. FOREVER is assumed if an UNTIL expression only uses $PROCFILE, $PROCNAME, $SUBSYS, softspy_variables, numeric_constants and string_constants.

    For example, the command:

    GO UNTIL $PROCNAME = 'DESIRED.PROCEDURE'

    specifies that execution continues when evaluation of a new request starts unless the request is contained in the specified procedure. You must be careful when you specify GO FOREVER since execution continues indefinitely when you specify a condition that will never be true. In this situation you should exit your application and issue SPY OFF followed by SPY ON at the Model 204 command line prompt. This will reset your SoftSpy environment.

    After evaluation is suspended the actions specified by the most recent DEFAULT LINE command are performed. These actions include setting the current line to either the last statement executed or the next statement to be executed. They also include resetting the position in the history of executed statements.

    If an ON condition occurs while processing the GO command, the actions specified by the most recent DEFAULT LINE command are performed followed by the action specified in the ON command for the condition. This allows specific actions to be taken automatically on start or end of request, when compilation or evaluation-time errors occur, or when break points are encountered. Evaluation is suspended only if a condition that suspends evaluation is in effect after all ON processing is completed.

    When terminal process-to-process communication is active, control cannot be returned to SoftSpy and UNTIL conditions cannot be evaluated. Return of control due to break points or errors and evaluation of UNTIL conditions is delayed until terminal process-to-process communication is terminated.

    A GO command with an UNTIL clause may not be used while performing ON processing for a GO command with an UNTIL clause.

    The STEP statement can also be used to resume request evaluation.

    Examples

    GO
    GO FOREVER
    GO UNTIL %DATA = 'DESIRED VALUE'
    GO UNTIL $PROCNAME = 'DESIRED.PROCEDURE'
    GO UNTIL DKPR(STMT)
    GO FOREVER UNTIL DKPR(STMT)
    GO UNTIL FINDS(STMT)
    GO UNTIL DKPR(STMT) OR DKAR(STMT)
    GO UNTIL $UPDATE
    GO UNTIL $UPDATE AND SCREENS(STMT)

    See Also DEFAULT LINE, ON, STEP

    HELP

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

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

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

    HELP Topic Screen

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

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

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

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

    HELP List Screen

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

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

    Examples

    HELP HELP *
    HELP DISPLAY
    HELP * *
    HELP EDIT MACRO
    HELP B*
    HELP * S*
    HELP *OPERAND
    HELP SUMMARY *
    HELP * MACRO
    HELP MESSAGE SPY.001
    HELP SPY.127

    See Also HELP Environment

    IF

    Function Conditionally execute a command.
    Syntax IF expression THEN softspy_command
    Description The IF command conditionally executes a softspy_command. The expression parameter is evaluated. If the result is true the following softspy_command is executed. Otherwise, the command is not executed. This allows conditional execution of SoftSpy commands. Like all SoftSpy commands, the complete IF command, including the THEN clause, must be contained on a single line.
    Examples

    IF $OPTION('DEBUG') THEN JUMP TO DEBUG
    IF $TESTED EQ $REACHABLE THEN JUMP TO REACHABLE
    IF $SKIP_END_EVAL THEN TRANSFER GO
    IF $SUBSTR($TEXT,1,1) NE '(' THEN JUMP TO OPERAND_WATCH
    IF $CONTEXT EQ 'EVAL' THEN EXEC EVAL_PROFILE
    IF $L IS NUM GT $MAX_LINE('SOURCE') THEN JUMP TO MISSING


    IN WINDOW

    Function Temporarily alter the active window while a command is executed.
    Syntax IN [ WINDOW ] window_identifier softspy_command
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The IN WINDOW command temporarily changes the active window for the execution of the specified command. The original active window is restored after the command is executed. The window_identifier specifies the name of the window to make active while the softspy_command specified is executed. It can be the SOURCE window or a window opened with the OPEN WINDOW command. Otherwise an error message is issued and the command is not executed.

    The BACKWARD, FORWARD, LEFT, LOCATE, PRINT WINDOW, and RIGHT commands all operate in the context of the active window. The UNWATCH and WATCH commands operate in the context of the default watch window. The default watch window is the same as the active window unless the active window is the source window.

    IN WINDOW is also useful for EXEC commands when the macro executed contains commands sensitive to the active window. For example, the BOTTOM and TOP macros execute in the context of the active window.

    Examples

    IN WINDOW MONITOR TOP
    IN MONITOR TOP
    IN WINDOW MONITOR FORWARD IN MONITOR BACKWARD
    IN WINDOW STAT BOTTOM
    IN WINDOW SOURCE LEFT IN WINDOW SOURCE RIGHT
    IN WINDOW SOURCE LOCATE /ABC/ IN WINDOW STAT UNWATCH G.*
    IN WINDOW STAT WATCH CPU
    IN WINDOW SOURCE EXEC FINDEND

    See Also $ACTIVE_WINDOW, $DEFAULT_WATCH_WINDOW, ACTIVE WINDOW

    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
    JUMP TO START_OF_LOOP
    CHECK: IF $SUBSYS EQ 'SOFTSPY' THEN JUMP TO SKIP

    See Also $JUMP_LIMIT

    LAST

    Function Scroll backward in the execution history of the current User Language request.
    Syntax LAST [ n ]
    Restrictions The context must be EVAL and the interactive debugging option is required.
    Description The LAST command scrolls backward through the execution history of the current request. The position in the history is moved backward the specified number of statements. If no parameter is used, a default of one statement is assumed. If the history requested is not available a warning message is issued and the position is moved as far backward as possible.

    The current line is set to the first line of the statement executed at the new position in the execution history.

    SoftSpy maintains an execution history for 99 previously executed statements, plus the next statement to execute. The execution history is only available for the current User Language request.
    Examples

    LAST
    LAST 10

    See Also DEFAULT LINE, NEXT

    LEFT

    Function Scroll to the left in the active window.
    Syntax LEFT [ FULL | HALF | n | MAX]
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The LEFT command scrolls to the left in the active window. It allows the display of data to the left of the portion visible in the window. Data moves right, allowing columns to the left to become visible.

    When FULL is used the distance scrolled is the full width of the window. FULL is the default. The column preceding the first column displayed becomes the last column displayed. If there are not enough columns to allow this movement then the first column displayed becomes column one.

    When HALF is used the distance scrolled is half the width of the window. If there are not enough columns to allow this movement then the first column displayed becomes column one.

    When an integer is used the distance scrolled is the number of columns specified. If there are not enough columns to allow this movement then the first column displayed becomes column one.

    When MAX is specified the first column displayed becomes column one. The active window may be temporarily altered for the duration of the LEFT command by prefixing it with the IN WINDOW command.
    Examples

    LEFT
    LEFT MAX
    LEFT 10
    LEFT HALF
    IN WINDOW STATS LEFT FULL
    IN MONITOR LEFT

    See Also RIGHT

    LIST ACL

    Function Display a list of access control lists
    Syntax LIST ACL [ pattern ]
    Restrictions The READ ACL privilege is required.
    Description The LIST ACL command displays a list of access control lists. All access control lists whose names match the pattern specified are included. If no pattern is specified then all access control lists are included.

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

    LIST ACL Screen

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

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

    Examples

    LIST ACL
    LIST ACL *
    LIST ACL A*

    See Also LIST Environment

    LIST MACRO

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

    LIST MACRO Screen

    1 OF 305 SoftSpy for Model 204 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
    LIST MACRO *
    LIST MACRO P*

    See Also LIST Environment

    LOCATE

    Function Find a character string in the active window.
    Syntax
    Restrictions The context must be BROWSE, COMPILE_ERROR, EDIT or EVAL.
    Description The LOCATE command is used to find a line containing a substring that matches a specified string or a specified pattern in the active window. The search is case insensitive.

    An exact string match is requested using a string delimited with an initial slash. The slash delimiter must not be contained in the string. Unless the end slash delimiter is used, the string includes all following characters on the line except trailing spaces. A pattern match is requested with the keyword LOCATE.

    If a minus sign is specified, the search begins with the line preceding the current line and continues backward. Otherwise the search begins with the line after the current line and continues forward. LOCATE only searches in the active window.

    The current line is set to the first line found that contains the specified string or pattern. Searches include data outside of the visible portion of the window. If no match is found, an error message is issued and the current line remains unchanged.

    The active window may be changed for the duration of a LOCATE command by prefixing it with the IN WINDOW command.

    Examples

    /SUBROUTINE
    -/SUBROUTINE
    LOCATE SUBROUTINE
    LOCATE 'SUBROUTINE'
    LOCATE %SCREEN:LINE#


    M204

    Function Execute a Model 204 command.
    Syntax M204 model_204_command
    Restrictions The M204 ADHOC privilege is required to use the M204 command from the command line or in a macro whose name begins with the user's id followed by an underscore. The M204 MACRO privilege is required to use the M204 command in macros whose name does not begin with the user's id followed by an underscore.
    Description The M204 command executes a Model 204 command. The Model 204 command is executed in the context of the SoftSpy server, not in the context of the user that issued the SPY ON command.

    The M204 command lets you edit procedures and run ad-hoc queries. Context information such as open files must be established first, since the Model 204 command is executed in the SoftSpy server environment, not the environment of the SoftSpy user. The specified command is run from within an included procedure. Commands that must be entered directly from a terminal, like invoking subsystems, are not allowed.

    Examples

    M204 OPEN PROCFILE
    M204 EDIT (SCREEN TERMINAL) 0
    M204 INCLUDE RECORD.DISPLAY.PROC


    NEW PAGE

    Function Begin a new page.
    Syntax NEW PAGE
    Description The NEW PAGE command begins a new page on the current print output destination. Page headers are printed on the new page. If the output destination is the terminal then an end of page pause is issued. Once the user has responded to the end of page pause the terminal screen is cleared so that a new page can be displayed.

    If no print destination is open and the default print destination is the terminal, a new page is begun on the terminal. If no print destination is open and the default print destination is not the terminal, an error message is issued.

    Examples

    NEW PAGE

    See Also DEFAULT PRINTER, OPEN PRINTER, PRINT LINE

    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
    NEXT 10

    See Also DEFAULT LINE, LAST

    ON

    Function Establish a command to execute whenever processing of a User Language request causes a specified condition to occur.
    Syntax
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The ON command specifies a softspy_command to execute whenever a specified condition occurs while processing a User Language request.

    The following conditions can be specified:

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

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

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

    Examples

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

    See Also GO, STEP

    OPEN PRINTER

    Function Open a destination for print output.
    Syntax

    Description The OPEN PRINTER command opens a destination for print output.

    Various aspects of the format of print output can also be controlled. If a print destination is not specified then the default print destination set by the DEFAULT PRINTER command is opened. If the open is successful then all print output will be sent to the specified destination until a CLOSE PRINTER command is issued. If a print destination is already open an error message is issued and the print destination is not changed.

    The print destination may be a DATASET, PRINTER, PUNCH, or the TERMINAL. The TERMINAL option takes no arguments. The other destination options require conformance with the syntax of the Model 204 USE command. In addition, SoftSpy supports two additional parameters for these destinations. A parameter of CCC=n may be specified, where n is the desired continuation column setting. Similarly, a parameter of LPP=n may be specified, where n is the desired number of lines per page.

    When output is directed to the terminal the continuation column is controlled by the Model 204 OUTCCC parameter. The number of lines per page is either 24 or 42 depending on the terminal model number.

    The initial default printer is TERMINAL.

    Examples

    OPEN PRINTER
    OPEN PRINTER TERMINAL
    OPEN PRINTER OUT1
    OPEN PRINTER PUNCH PUNCH1
    OPEN PRINTER DATASET REPORT
    OPEN PRINTER PRINTER WITH ROUTER=VM,ID=GEORGE

    See Also DEFAULT PRINTER, CLOSE PRINTER

    OPEN WINDOW

    Function Display a window on the screen.
    Syntax

    OPEN WINDOW window_identifier [COLUMN left_column TO right_column] [ROW top_line TO bottom_line] [WATCH { operand | (operand [,operand]...) } ]

    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The OPEN WINDOW command displays a window on the screen. The window_identifier specifies the name of the window. This parameter may specify a new name or the name of a window that has been defined, but not opened. If the name of an open window is used an error message is issued.

    The COLUMN parameter is required unless a previously defined window that included a COLUMN parameter is being opened. The COLUMN keyword is followed by a left_column parameter specifying the window's first column, the word TO, and a right_column parameter specifying the window's last column. The left_column must be greater than or equal to six. The right_column must be less than or equal to 77 and at least two larger than the left_column. Columns adjacent to a window are reserved for screen format control. When the COLUMN parameter is specified in both the DEFINE and OPEN commands the values specified in the OPEN command are used.

    The ROW parameter is required unless a previously defined window that included a ROW parameter is being opened. The ROW keyword is followed by a top_line parameter specifying the window's top line, the word TO, and a bottom_line parameter specifying the window's bottom line. The top_line must be greater than or equal to one. The bottom_line must be less than or equal to 16 minus the number of title lines created by SHOW commands, and at least two larger than the top_line. The window must not overlap the rows of an open window or an error message is issued. When the ROW parameter is specified in both the DEFINE and OPEN commands the values specified in the OPEN command are used.

    The WATCH parameter identifies operands to watch in the window. If operands are specified in both the DEFINE WINDOW and OPEN WINDOW commands, both sets of operands are initially watched.

    OPEN WINDOW does not change the active window. The ACTIVE WINDOW or IN WINDOW commands must be used for this purpose.

    Opening windows can cause a performance penalty. The penalty is incurred when pre-compiled versions of SoftSpy code cannot be used because custom screen definitions are required. No penalty is incurred if there is a single open window positioned at ROW 1 TO 12 and at COLUMN 51 to 77.

    Examples

    OPEN WINDOW MONITOR
    OPEN WINDOW STATS COLUMN 50 TO 77 ROW 1 TO 6
    OPEN WINDOW INFO ROW 1 TO 6
    OPEN WINDOW WATCH ROW 7 TO 16
    OPEN WINDOW GTBL WATCH G.* COLUMN 50 TO 77 ROW 1 TO 16

    See Also CLOSE WINDOW, DEFINE WINDOW, WATCH

    PF

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

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

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

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

    Examples

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


    PRINT ACL

    Function Print an access control list.
    Syntax PRINT ACL access_control_list_identifier
    Restrictions The READ ACL privilege is required.
    Description The PRINT ACL command prints the specified access control list. If the specified access control list does not exist, an error message is issued and no printout is produced.

    The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.

    Examples

    PRINT ACL ADMIN


    PRINT HELP

    Function Print SoftSpy help information.
    Syntax PRINT HELP [ pattern ] [ pattern ]
    Description The PRINT HELP command prints SoftSpy help information. It uses the same rules as the HELP command to select a single topic or a set of topics based upon the specified patterns. The single selected topic or a list of selected topics is printed. If no topics are found, an error message is issued and no printout is produced.

    The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.

    Examples

    PRINT HELP PRINT HELP ENVIRONMENT
    PRINT HELP *
    PRINT HELP LIST MACRO
    PRINT HELP BREAK
    PRINT HELP LIST *

    See Also HELP

    PRINT LINE

    Function Print a line.
    Syntax PRINT LINE [ expression ]
    Description PRINT LINE evaluates the expression specified and prints a line consisting of the resulting value. If the result of the expression is not KNOWN, an error message is issued and no line is printed. If an expression is not specified a blank line is printed.

    The line is sent to the current open print output destination. If there is not an open print output destination and the default print destination is the terminal, the line is displayed on the terminal. Otherwise, the line is not printed and an error message is issued.

    Examples

    PRINT LINE 'HELLO'
    PRINT LINE $PAD('*','*',70)
    PRINT LINE '* TERMINATED BY ' WITH $INTERRUPT_TYPE
    PRINT LINE 'IN ' WITH $PROCFILE WITH ' I ' WITH $PROCNAME

    See Also DEFAULT PRINTER, NEW PAGE, OPEN PRINTER

    PRINT LIST

    Function Print a list of access control lists or macros.
    Syntax PRINT LIST {ACL | MACRO} [pattern]
    Description The PRINT LIST command prints a list of access control lists or macros. All access control lists or macros whose names match the pattern specified are included. If no pattern is specified then all access control lists or macros are included. If no access control lists or macros are selected, an error message is issued and no printout is produced.

    A line is printed for each access control list or macro selected. The line contains the access control list or macro name, number of lines, last update user id, and last update date and time.

    The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.

    Examples

    PRINT LIST MACRO
    PRINT LIST ACL *
    PRINT LIST MACRO *_PROFILE
    PRINT LIST MACRO MICHAEL_*


    PRINT MACRO

    Function Print a macro.
    Syntax PRINT MACRO macro_identifier
    Restrictions The READ MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
    Description The PRINT MACRO command prints the specified a macro. If the specified macro does not exist, an error message is issued and no printout is produced.

    The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.

    Examples

    PRINT MACRO PROFILE
    PRINT MACRO BOB_PROFILE


    PRINT WINDOW

    Function Print the contents of a window.
    Syntax PRINT WINDOW [ window_identifier ]
    Description The PRINT WINDOW command prints the specified window. The entire window is printed, including any portion that is not visible in the screen display. If the specified window does not exist, or has not been opened, an error message is issued and no printout is produced. The active window is printed if a window_identifier is not specified.

    The printout is sent to the current open print output destination, if any. Otherwise, the default print destination is opened, the printout is produced, and the default print destination is closed.

    Examples

    PRINT WINDOW
    PRINT WINDOW MONITOR
    PRINT WINDOW SOURCE


    QA

    Function Establish the interactive quality assurance testing environment.
    Syntax QA
    Restrictions The context must be EVAL and the quality assurance option is required.
    Description The QA macro switches to the interactive quality assurance testing environment, or reinitializes the interactive quality assurance testing environment. This environment helps you determine how thoroughly a User Language request has been tested.

    QA Screen

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

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

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

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

    Examples

    QA

    See Also AUDIT, DEBUG, QA Environment, TUNE

    QUAD

    Function Find the line containing the quad_offset specified and make it the current line. If a procedure_name is specified following the quad_offset then evaluation is first resumed until the specified procedure is reached.
    Syntax QUAD quad_offset [ procedure_name ]
    Restrictions The context must be EVAL and the audit option is required.
    Description The QUAD macro is used to locate the line that caused a run-time error. The quad_offset and procedure_name of any statement causing a run-time error are written to the Model 204 audit trail after the SPY AUDIT ON command is issued. Issuing the QUAD macro with a quad_offset will make the line at the specified quad offset the current line in the current program.

    If a procedure_name is specified following the quad_offset then evaluation is first resumed until the specified procedure is reached. Evaluation will be suspended prior to reaching the specified procedure if any of the following occurs:

    • An evaluation-time error occurs (either cancelling or non-cancelling)
    • A User Language request fails to successfully compile and the interactive debugging option is available

    The quad_offset must be an integer between 0 and the value of C.QTBL for the target User Language request (inclusive). Procedure_name must be a valid Model 204 procedure name.

    Examples

    QUAD
    QUAD 108
    QUAD 108 DESIRED.PROGRAM

    See Also AUDIT, AUDIT Environment, SPY AUDIT ON, SPY AUDIT OFF

    QUIT

    Function Quit the current SoftSpy function or cancel the current User Language request.
    Syntax QUIT [CONFIRM | NOCONFIRM]
    Description The QUIT command terminates the current SoftSpy function. If CONFIRM is specified the user is prompted for confirmation prior to termination of the function. If NOCONFIRM is specified the function is terminated without obtaining confirmation.

    CONFIRM is the default in the EVAL and COMPILE_ERROR contexts.

    NOCONFIRM is the default in the BROWSE, HELP, and LIST contexts. The default is CONFIRM in the CONFIG and EDIT contexts if changes have been made but not saved, and NOCONFIRM otherwise.

    When prompted to confirm the QUIT you should respond by pressing PF3 or entering QUIT on the command line if you want to terminate the function. You should respond by pressing PF12 or entering RETURN on the command line if you want to abort the QUIT and resume the current function. Invalid responses result in repeating the confirmation request.

    In the EVAL context QUIT cancels the request being evaluated. Use the SPY OFF command instead if you wish to terminate SoftSpy without cancelling the request.
    Examples

    QUIT
    QUIT CONFIRM
    QUIT NOCONFIRM

    See Also SPY OFF

    RENAME ACL

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

    RENAME ACL ADMIN TO OLD_ADMIN
    RENAME ACL ADMIN TO ACL SAVED_ADMIN


    RENAME MACRO

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

    RENAME MACRO PROFILE TO OLDPROFILE
    RENAME MACRO PROFILE TO MACRO OLD_PROFILE


    REPEAT

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

    REPEAT
    =


    RETRIEVE

    Function Recall a previously entered command.
    Syntax RETRIEVE
    Description The RETRIEVE command recalls the previous command line entered.

    This value is placed on the command line so it may be modified or used again. If no value has been previously entered on the command line, an error message is issued. RETRIEVE ignores previously issued REPEAT and RETRIEVE commands.

    Each time RETRIEVE is used in succession it recalls the command line entered prior to the last retrieved line. Duplicate command lines are eliminated so that the same command is never retrieved twice by repeated execution of RETRIEVE. A maximum of ten previous command lines are available.
    Examples

    RETRIEVE


    RETURN

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

    RETURN

    See Also EXEC, TRANSFER

    RIGHT

    Function Scroll to the right in the active window.
    Syntax RIGHT [FULL | HALF | n | MAX]
    Restrictions The context must be COMPILE_ERROR or EVAL.
    Description The RIGHT command scrolls to the right in the active window. RIGHT allows the display of data to the right of the portion visible in the window. Data moves left, allowing columns to the right to become visible.

    When FULL is used the distance scrolled is the full width of the window. FULL is the default. The column following the last column displayed becomes the first column displayed. If there are not enough columns to allow this movement then the last column displayed becomes the last column.

    When HALF is used the distance scrolled is half the width of the window. If there are not enough columns to allow this movement then the last column displayed becomes the last column.

    When an integer is used the distance scrolled is the number of columns specified. If there are not enough columns to allow this movement then the last column displayed becomes the last column.

    When MAX is specified the last column displayed becomes the last column.

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

    Examples

    RIGHT
    RIGHT MAX
    RIGHT 10
    RIGHT HALF
    IN WINDOW STATS RIGHT FULL
    IN MONITOR RIGHT

    See Also LEFT

    SAVE ACL

    Function Save an access control list and continue editing.
    Syntax SAVE [ [ ACL ] access_control_list_identifier ]
    Restrictions The context must be EDIT.
    Description The SAVE ACL command saves the access control list being edited.

    The access_control_list_identifier specifies the name of the access control list to save. This can be the name of the access control list being edited or the name of a new access control list that is to be created.

    The keyword ACL must be used if the access_control_list_identifier is ACL, CONFIG, or MACRO. If the access control list name used does not match the edited access control list, and an access control list by that name already exists, an error message is issued and the save is not performed. If an access_control_list_identifier is not used, or the name of the edited access control list is used, the edited access control list is saved to reflect pending changes.

    If you try to save an access control list which contains an invalid user identifier, the access control list is not saved and an error message is issued. User identifiers must not exceed ten characters or contain a semicolon, comma, equal sign, or blank.
    Examples

    SAVE
    SAVE ADMIN
    SAVE ACL ADMIN
    SAVE ACL EDIT
    SAVE ACL ACL

    See Also EDIT ACL, QUIT

    SAVE CONFIG

    Function Save the SoftSpy configuration and continue editing.
    Syntax SAVE [CONFIG]
    Restrictions The context must be CONFIG.
    Description The SAVE CONFIG command saves the SoftSpy configuration. If any edited configuration parameters are not valid an error message is issued, and the configuration is not saved.

    The new configuration takes immediate effect. Inactive IODEV=55 SoftSpy server threads are activated if they are authorized by the new configuration.

    Examples

    SAVE
    SAVE CONFIG

    See Also EDIT CONFIG, QUIT

    SAVE MACRO

    Function Save a macro and continue editing.
    Syntax SAVE [ [MACRO] macro_identifier]
    Restrictions The context must be EDIT and the UPDATE MACRO privilege is required unless the macro name begins with the user's id followed by an underscore.
    Description The SAVE MACRO command saves the macro being edited. The macro_identifier specifies the name of the macro to save. This can be the name of the macro being edited or the name of a new macro that is to be created.

    The keyword MACRO must be used if the macro_identifier is ACL, CONFIG, or MACRO. If the macro name used does not match the edited macro, and a macro by that name already exists, an error message is issued and the save is not performed. If a macro_identifier is not used, or the name of the edited macro is used, the edited macro is saved to reflect pending changes.

    If you try to save a macro that contains invalid or duplicate label_identifiers, the macro is not saved and an error message is issued.

    Examples

    SAVE
    SAVE PROFILE
    SAVE MACRO PROFILE
    SAVE MACRO CONFIG

    See Also EDIT MACRO, QUIT

    SCREEN

    Function Change the layout of the SoftSpy screen.
    Syntax SCREEN [BORDER] SOURCE [BORDER] COMMAND MESSAGE [PFKEYS]
    Description The SCREEN command lets you identify the order in which screen elements will appear.

    The following syntax rules apply:

    • SOURCE, COMMAND, and MESSAGE must each be specified exactly once.
    • BORDER is optional and can be specified up to two times. If specified it must be adjacent to SOURCE: before, after, or before and after.
    • PFKEYS is optional and can be specified up to one time.
    Examples

    SCREEN SOURCE COMMAND MESSAGE
    SCREEN BORDER SOURCE BORDER COMMAND MESSAGE
    SCREEN MESSAGE SOURCE COMMAND PFKEYS
    SCREEN BORDER SOURCE PFKEYS COMMAND MESSAGE

    See Also DEFINE WINDOW

    SCROLL

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

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

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

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

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

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

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

    Examples

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


    SET

    Function Alter the value of an operand.
    Syntax
    Description The SET command alters the value of SoftSpy operands. The first parameter specifies the operand whose value is to be altered. The expression is evaluated and the resulting value is assigned to the target operand. If the result of the expression is not KNOWN an error message is issued and the operand is not altered unless the operand is a softspy variable.

    Setting $CURRENT_LINE

    $CURRENT_LINE is used with the SET command to set the current line for the source window. The literal value 'SOURCE' is required as an argument to indicate the source window. It may only be set in the COMPILE_ERROR and EVAL contexts. An error message is issued, and the current line is not altered, if the value assigned is not an integer between one and the number of lines in the source window.

    Setting $DEFAULT_JUMP_LIMIT

    SET can be used with $DEFAULT_JUMP_LIMIT to set the default value of $JUMP_LIMIT for subsequently invoked macros. It may only be set to a non- negative integer value.

    Setting $JUMP_LIMIT

    SET can be used with $JUMP_LIMIT to change the maximum number of JUMP TO statements that may be executed within the current macro. It may only be set within a macro. It may only be set to a non-negative integer value. If it is set to zero then no limitation on the number of JUMP TO statements is enforced within the current macro.

    Setting $SPY_MESSAGE

    If $SPY_MESSAGE is specified as the operand any SoftSpy message that has been issued but not yet displayed is purged. If the value assigned is a null string, then no pending message will remain. If the value assigned is not a null string, then setting $SPY_MESSAGE causes the specified value to be issued as a message.

    Setting Fields

    A field_operand can only be set in the EVAL context, and the SoftSpy interactive debugging option is required. They may be set at any point in execution where there is a current record (inside FOR EACH RECORD or FOR RECORD NUMBER loops). The only record loop context where fields may not be set is a record loop against a sorted set (a FOR loop against a set created with the SORT statement). If the SET command is used on a field_operand in an invalid context, then it is rejected with an error message. The field specified must exist in the file that contains the current record, or the command is rejected with an error message.

    If a field occurrence subscript is not specified, then a default of one is used. Setting a field operand is similar to the User Language CHANGE statement. If the requested occurrence number is present in the current record, then its value is changed to the value specified. If there are no occurrences of the field in the current record, then an occurrence is added with the value specified. If the occurrence number specified exceeds the number of occurrences in the record, then a new occurrence is added with the value specified. Finally, if the new value specified is a zero length string, the occurrence is deleted from the record.

    Security

    The user must have update access to the file in question. In addition, if field level security is in place, they must have the same security level as needed to update the field with a User Language CHANGE statement. In either case, the command is rejected with an error message if the user's access to the file is not sufficient.

    Record locking

    An exclusive record lock is obtained for the current record (if one is not already held). If this lock cannot be obtained, the command is rejected with an error message. The locking behavior is identical to that of an update statement within a record loop except no ON unit is invoked if the lock cannot be obtained.

    Items that cannot be set

    Neither invisible fields nor the sort key of a sorted file may be set. Remote files may not be updated. In these cases, the command is rejected with an error message.

    Constraints

    Finally, if the SET command would cause an update to the file that would violate any file or field constraint defined for the file, then the command is rejected with an error message. The user can only perform updates that would be legal in a User Language program. SoftSpy strictly enforces all file and field constraints.

    Constraint violations include:

    • The value is too long for a pre-allocated field.
    • The occurrence number exceeds the OCCURS specification of a pre-allocated field.
    • The value causes a uniqueness violation (note that any ON FCC unit is not raised).
    • The value cannot be converted to a number on a numeric (FLOAT or BINARY) field in a numeric validation file (FILEMODL=1).
    • The value fails KANJI conversion for either a mixed or pure DBCS field.
    • The occurrence number would cause an attempt to add another occurrence of an AT MOST ONE field.

    Sir2000 Field Migration Facility

    If you are using the Sirius Software Sir2000 Field Migration Facility, use caution when using the SET command to update date fields. The SET command will not automatically update a Sir2000 RELATEd date field.

    Setting Global Variables

    If a new global_variable_operand is specified, the G. global_variable_operand prefix is required. If room is not available in the global table, an error message is issued and the global_variable_operand is not altered. A global_variable_operand can only be set in the COMPILE_ERROR and EVAL contexts, and the SoftSpy interactive debugging option is required.

    Setting Percent Variables

    If a percent_variable_operand is specified, a conversion is performed from the expression to the target percent_variable_operand type using Model 204 conversion rules. If the correct number of subscripts are not specified, a subscript is out of range, or the percent_variable_operand is a complex subroutine input parameter, an error message is issued and the percent_variable_operand is not altered. If the percent_variable_operand is defined as a string and the value exceeds its defined length, a warning message is issued and the value is truncated. A percent_variable_operand can only be set in the EVAL context, and the SoftSpy interactive debugging option is required.

    One use of setting a percent variable is terminating a loop early, without ending the request. For example, a loop initiated by the statement FOR %I FROM 1 TO 10 can be terminated early by setting %I to 11 while inside the loop.

    Setting SoftSpy Variables

    The value assigned to a softspy_variable of numeric type must be numeric. If it is not then an error message is issued and the variable is set to UNKNOWN. A value assigned to a softspy_variable of string type is truncated if it is longer than the declared length.

    Examples

    SET %WORD = 'HELLO'
    SET %ARRAY(2,3) = 'THERE'
    SET %AGE = 35
    SET %NAMELIST(%CURVAL) = 'SALLY'
    SET %LAST_NAME = G.LAST_NAME
    SET %NAME = %FIRST_NAME WITH ' ' WITH %LAST_NAME
    SET G.NAME = 'MICHAEL'
    SET NAME = OLDNAME
    SET LINE = %X WITH %SCREEN.LINE1
    SET G.'M.I.' = 'A'
    SET $SPY_MESSAGE = 'MACRO EXECUTION SUCCESSFUL'
    SET $SPY_MESSAGE =
    SET $DEFAULT_JUMP_LIMIT = 333
    SET $JUMP_LIMIT = 1616
    SET $CURRENT_LINE('SOURCE') = $CURRENT_LINE('SOURCE') + 1
    SET $SAVED_WINDOW = $ACTIVE_WINDOW
    SET $I = $I + 1
    SET F.FIRSTNAME = 'MOE'
    SET F.PETS(1) = 'SPOT'
    SET F.AGE = F.AGE + 1
    SET F.'LAST NAME' = 'HOWARD'


    SHOW

    Function Add columns to the source window that display statistic, usage, quality assurance, or compilation operands by line.
    Syntax SHOW column_definition [ , column_definition ] . . .

    Where each column_definition is of the following form:

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

    SHOW Screen

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

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

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

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

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

    Column Titles

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

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

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

    Column Width

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

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

    Decimal Places

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

    Data Collection

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

    Numeric Data

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

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

    Character Data

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

    Histograms

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

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

    SHOW Histogram Screen

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

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

    Brackets

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

    SHOW Bracket Screen

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

    The following characters are used to draw the brackets:

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

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

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

    Missing Data

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

    Examples

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

    See Also COLLECT, DISPLAY, UNCOLLECT, UNSHOW, WATCH

    SPY AUDIT OFF

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

    SPY AUDIT OFF

    See Also AUDIT, AUDIT Environment, SPY AUDIT ON

    SPY AUDIT ON

    Function Activate the SoftSpy Audit feature.
    Syntax SPY AUDIT ON
    Restrictions The audit option is required. SPY AUDIT ON must be issued from the Model 204 command line by user zero or a System Manager.
    Description The SPY AUDIT ON command activates the SoftSpy Audit feature.

    With this feature active whenever a run-time error occurs during evaluation of a User Language request the following information is written to the audit trail:

    SPY >>> Runtime Procedure Error in Subsystem: [*NONE* | subsystem_name] Procfile: [*NONE* | procfile_name]
    SPY >>> Procedure: procedure_name
    SPY >>> QTBL quad offset: quad_offset
    SPY >>> Call issued from QTBL quad offset: quad_offset
    .
    .
    .

    This information is written to the audit trail immediately before the error to which it refers. If the error did not occur in a subroutine no “Call issued from” lines will be present.

    Once SPY AUDIT ON has been issued, it remains on for the entire online run unless SPY AUDIT OFF is issued.

    Examples

    SPY AUDIT ON

    See Also AUDIT, AUDIT Environment, SPY AUDIT OFF

    SPY OFF

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

    SPY OFF

    See Also QUIT, SPY ON, SPY ON THREAD, SPY ON USER

    SPY ON

    Function Start a SoftSpy session.
    Syntax SPY [ ON [ CLASS=class_name ] ]
    Restrictions The SPY ON privilege is required. SPY ON must be issued from the Model 204 command line.
    Description The SPY ON command turns SoftSpy on for your use, if possible. It requires that a SoftSpy server be available for use. An error message is issued if a server is not available, or if sufficient storage is not available to establish the SoftSpy environment. An informational message is issued if you have already turned SoftSpy on.

    The optional CLASS parameter is used to specify a class_name for the server. If CLASS is specified then only a server started with the same CLASS parameter will be used. If CLASS is omitted, then only servers started with CLASS omitted will be used. The class name may be up to eight characters long. The first character must be alphabetic, and any additional characters must be alphanumeric or the underscore.

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

    Examples

    SPY
    SPY ON
    SPY ON CLASS=ADMIN

    See Also SPY OFF, SPY ON THREAD, SPY ON USER, SPY SERVER

    SPY ON THREAD

    Function Start a SoftSpy server session to debug another User Language thread.
    Syntax SPY ON THREAD threadnum
    Restrictions The SPY SERVER privilege is required. SPY ON THREAD must be issued from the Model 204 command line.
    Description The thread specified by threadnum is validated to see if it is within the range from 1 to NUSERS, and that it is not the thread from which SPY ON THREAD was issued. In addition, the thread number may not specify a thread that is currently using SoftSpy or is a SoftSpy server. The IODEV type of the selected thread is then examined for validity. All thread types from which User Language requests can be run are legal except for Horizon and Janus threads. If any of these rules is violated, an error message is issued and the command is rejected.

    Once a thread has been selected, the thread that issued the command is turned into a SoftSpy server, and the terminal will lock up until the selected thread runs a User Language request. When the selected thread runs a request, the SoftSpy screen appears on the SoftSpy server terminal session. SoftSpy can then be used in the normal manner. From the SoftSpy screen, issuing SPY OFF will convert the thread from a SoftSpy server back into a normal thread, and disconnect it from the selected thread.

    This feature can be used for two purposes. First, it can be used to interactively execute non-terminal threads such as BATCH2, and IODEV=3 threads. Second, it can be used if you have an environment (such as Microsoft Windows) where you can have multiple terminal sessions, and you do not want the output of the SoftSpy screen and the application sharing the same terminal session.

    Examples

    SPY ON THREAD 4
    SPY ON THREAD 666

    See Also SPY ON, SPY OFF, SPY SERVER

    SPY ON USER

    Function Start a SoftSpy server session to debug another User Language thread.
    Syntax SPY ON USER userid
    Restrictions The SPY SERVER privilege is required. SPY ON USER must be issued from the Model 204 command line.
    Description

    All logged in threads that run User Language with the exception of Horizon, Janus, and the thread issuing SPY ON USER are matched against userid. If no such threads are found, or more than one are found, then the command is rejected and an error message is issued. If one such thread is found, it is validated to ensure that it is not user 0, a SoftSpy server, or a SoftSpy user. If any of these rules is violated, the command is rejected with an error message.

    Once a thread has been selected, the thread that issued the command is turned into a SoftSpy server, and the terminal will lock up until the selected thread runs a User Language request. When the selected thread runs a request, the SoftSpy screen appears on the SoftSpy server terminal session. SoftSpy can then be used in the normal manner. From the SoftSpy screen, issuing SPY OFF will convert the thread from a SoftSpy server back into a normal thread, and disconnect it from the selected thread.

    This feature can be used for two purposes. First, it can be used to interactively execute non-terminal threads, such as BATCH, and IODEV=3 threads. Second, it can be used if you have an environment (such as Windows) where you can have multiple terminal sessions and do not want the output of the SoftSpy screen and the application sharing the same terminal session.

    Examples

    SPY ON USER MOE
    SPY ON USER SHEMP

    See Also SPY ON, SPY OFF, SPY SERVER

    SPY SERVER

    Function Start a SoftSpy server.
    Syntax SPY SERVER [ CLASS=class_name ]
    Restrictions The SPY SERVER privilege is required to use SPY SERVER unless it is issued by user zero or an IODEV=3 thread. SPY SERVER must be issued from the Model 204 command line.
    Description The SPY SERVER command starts a SoftSpy server. SPY SERVER can be used to dynamically create a SoftSpy server if all IODEV=55 SoftSpy server threads are in use. The optional CLASS parameter is used to specify a class_name for the server. Use of the server is restricted to users that specify the same CLASS in the SPY ON command. If CLASS is omitted then use of the server will be restricted to users that omit CLASS in the SPY ON command. The class name can be up to eight characters long. The first character must be alphabetic, and any additional characters must be alphanumeric or the underscore.

    A SoftSpy server is created based on the authorized configuration specified with the EDIT CONFIG command. If a valid configuration is defined and enough storage is available the user becomes a SoftSpy server. Control is not normally returned after this command is issued.

    The value of OUTPB must be the same for both the SPY ON thread and the SPY SERVER thread.

    If system initialization is not complete when the SPY SERVER command is issued, then processing of the command is delayed until it is complete.

    Examples

    SPY SERVER
    SPY SERVER CLASS=ADMIN

    See Also SPY ON, EDIT CONFIG

    SPY softspy_command

    Function Issue SoftSpy commands from the Model 204 command line.
    Syntax SPY softspy_command
    Restrictions SPY must be issued from the Model 204 command line.
    Description SPY executes the SoftSpy command specified. Any command can be specified except those requiring the COMPILE_ERROR or EVAL context.

    If system initialization is not complete when the SPY command is issued, then processing of the command is delayed until it is complete.

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

    Examples

    SPY LIST MACRO
    SPY COPY MACRO PROFILE TO MACRO OLD_PROFILE
    SPY EDIT CONFIG


    STATS

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

    An error message is issued if there is no default watch window.

    Examples STATS

    STEP

    Function Start or resume evaluation of a User Language request for a specified number of statements or until an interrupt occurs.
    Syntax STEP [ n ]
    Restrictions The context must be EVAL.
    Description The STEP command resumes request evaluation. Evaluation is normally suspended again when any of the following conditions occur:
    • The number of statements specified with STEP have been executed, or a single statement has been executed if a number of statements was not specified
    • A break point is encountered
    • An evaluation-time error occurs (either cancelling or non-cancelling)
    • Evaluation of a User Language request is completed
    • Evaluation of a User Language request is begun.
    • A User Language request fails to successfully compile and the interactive debugging option is available

    After evaluation is suspended, the actions specified by the most recent DEFAULT LINE command are performed. These actions include setting the current line to either the last statement executed or the next statement to be executed. They also include resetting the position in the history of executed statements.

    If evaluation is suspended for any reason other than execution of the specified number of statements, the action specified by the most recent ON statement for the specified condition is performed. This allows specific actions to be taken automatically on start or end of request, when compilation or evaluation-time errors occur, or when break points are encountered.

    When terminal process-to-process communication is active, control cannot be returned to SoftSpy. Return of control is delayed until terminal process-to-process communication is terminated.

    The GO statement can also be used to resume request evaluation.

    Examples

    STEP
    STEP 10

    See Also DEFAULT LINE, GO, ON

    TOP

    Function Scroll to the top of the active window.
    Syntax TOP
    Description The TOP macro scrolls to the first line of data available in the active window. The first line becomes the current line.

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

    Examples

    TOP
    IN MONITOR TOP
    IN WINDOW SOURCE TOP

    See Also BOTTOM

    TRACE

    Function Produce a debugging trace when macros are run.
    Syntax TRACE {ON | OFF}
    Description The TRACE command controls whether or not a SoftSpy macro debugging trace is produced when macros are run. If tracing is enabled when a macro is run, debugging output is written to the open printer. The default printer is used if no printer is open.

    If no TRACE command has been issued then a debugging trace is not produced. TRACE ON enables a debugging trace. TRACE OFF terminates a debugging trace.

    Macro debugging output consists of three types of lines:

    • When a macro is entered (or returned to), a line containing MACRO: followed by the macro_identifier is printed.

      For example, the line MACRO: REPORT would be printed when the REPORT macro is run.

    • As each line of a macro is executed, a line containing the macro line number followed by the macro_line_text is printed.

      For example, 20 COLLECT VTBL would be printed when the 20th line of a macro containing the text COLLECT VTBL is run.

    • If a message is issued from within a macro, the debugging trace will include the text of the message following the line that caused it to be issued.
    Examples

    TRACE ON
    TRACE OFF


    TRACER

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

    TRACER


    TRANSFER

    Function Transfer control to a command from a macro.
    Syntax TRANSFER SoftSpy_command
    Restrictions Must be issued in a macro.
    Description TRANSFER provides a one-way transfer of control to a different macro or command from a macro. The macro containing the TRANSFER command is terminated and the specified SoftSpy command is run. When the new command is done, control is returned: not to the original macro, but to wherever that macro was invoked.

    TRANSFER can only be used in macros, otherwise an error message is issued and the transfer is not performed.

    Examples

    TRANSFER GO
    TRANSFER ERROR 'CONTEXT MUST BE EVAL'
    TRANSFER COMMAND 'HELP ' WITH $CURSOR_HYPERTEXT

    See Also EXEC, RETURN

    TUNE

    Function Establish the interactive performance tuning environment.
    Syntax TUNE
    Restrictions The context must be EVAL and the interactive performance tuning option is required.
    Description The TUNE macro switches to the interactive performance tuning environment, or reinitializes the interactive performance tuning environment. This environment is designed to help you tune the performance of your User Language requests.

    The lines of User Language requests are prefixed with three columns. These columns show the CPU time used in milliseconds, the number of logical page reads, and the average change in CCATEMP scratch file usage. The default line is set to the last statement executed. Any prior data collection is terminated and any collected data is discarded.

    TUNE screen

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

    The interactive performance tuning environment can be customized on an individual user basis. The TUNE macro looks for a macro named userid_TUNE, where userid is your user id. If such a macro is found, it is run to customize the tuning environment.
    See the description of the TUNE environment for a complete description of the facilities available when interactively performance tuning a User Language request.
    Examples

    TUNE

    See Also AUDIT, DEBUG, QA, TUNE Environment

    UL CONTINUE

    Function Advance the execution position to the next iteration of a FOR or REPEAT loop.
    Syntax UL CONTINUE
    Restrictions The context must be EVAL and the quality assurance option is required.
    Description If the current execution position is not inside a FOR or REPEAT loop, an error message is issued and the command is rejected. In addition, this command is only valid if the execution position is in a loop within the current routine: it is not valid from a subroutine that is called in a loop.

    If the current execution position is inside a loop, the loop is immediately advanced to its next iteration. If the execution position is in a loop that is nested inside of one or more outer loops, the inner most loop that contains the execution position is the loop that UL CONTINUE operates on.

    The alteration of the flow of control is identical to the behavior that would be seen if there was a label on the END FOR or END REPEAT that was jumped to. If there are more iterations remaining, then the execution position is placed on the first statement in the loop body. If there are no more iterations remaining, the execution position is placed on the first statement after the END of the loop.

    On record, value, or occurrence loops (FOR EACH RECORD, FOR EACH VALUE, FOR EACH OCCURRENCE), the next record, value, or occurrence is made current. On index loops (FOR %I FROM x TO y, REPEAT n TIMES), the index is incremented. Note that on a FOR RECORD NUMBER loop, UL CONTINUE simply causes an exit from the loop since this type of loop only has one iteration.

    Note that if the loop is exited, all the normal processing that occurs at the end of a loop still occurs, such as releasing of resources and locks.

    Examples

    UL CONTINUE

    See Also QA, QA Environment, UL JUMP TO LABEL, UL JUMP TO LINE, UL LOOP END, UL RESULT, UL RETURN

    UL JUMP TO LABEL

    Function Advance the execution position to a statement label or statement number and execute that statement.
    Syntax UL JUMP TO [LABEL] label
    Restrictions The context must be EVAL and the quality assurance option is required.
    Description label specifies a statement label or number within the request. If no such statement label or number is found, then an error message is issued and the command is rejected.

    The execution position is transferred to the statement with the matching label and that statement is executed.

    Not all jumps are valid. If any of the following rules are violated, an error message is issued and the command is rejected:

    • Jumping into or out of subroutines is not permitted.
    • Jumping into or out of ON UNITS is not permitted.
    • Jumping into the body of a FOR or REPEAT loop is not permitted.

    As an alternative to UL JUMP TO LABEL, the “J” prefix command may be entered directly into the prefix area of a line to jump to. Using this prefix command on a line is identical to determining the line’s number and issuing a UL JUMP TO LINE for that line number.

    Examples

    UL JUMP TO LABEL X UL JUMP TO EXITLOGIC UL JUMP TO 1 UL JUMP TO LABEL LINE

    See Also QA, QA Environment, UL CONTINUE, UL JUMP TO LINE, UL LOOP END, UL RESULT, UL RETURN

    UL JUMP TO LINE

    Function Advance the execution position to a line and execute the first statement on the line.
    Syntax UL JUMP TO LINE linenumber
    Restrictions The context must be EVAL and the quality assurance option is required.
    Description linenumber must be an integer in the range from 1 to the number of source lines, and must specify a line that is the first line of an executable statement. (It corresponds to the LINENO compilation_operand.) If linenumber is not valid, then an error message is issued, and the command is rejected.

    The execution position is transferred to the statement on the selected line, and that statement is executed. If more than one statement is on the line, then the first statement is transferred to and executed.

    Not all jumps are valid. If any of the following rules are violated, an error message is issued and the command is rejected:

    • Jumping into or out of subroutines is not permitted.
    • Jumping into or out of ON UNITS is not permitted.
    • Jumping into the body of a FOR or REPEAT loop is not permitted.

    As an alternative to UL JUMP TO LINE, the “J” prefix command may be entered directly into the prefix area of a line to jump to. Using this prefix command on a line is identical to determining the line’s number and issuing a UL JUMP TO LINE for that line number.

    Examples

    UL JUMP TO LINE 5 UL JUMP TO LINE 20

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

    ExamplesUL 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.
    ExamplesUNCOLLECT *
    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