SoftSpy operands

Introduction

SoftSpy features a number of operand types that access a wide variety of information about User Language requests. In addition, string_constants and numeric constants allow you to specify strings and numbers.

The table below lists the types of operands available in SoftSpy.

Operand	Description
compilation operand	Reference compile-time information about a request.
field operand	Reference a field in the current record.
global variable operand	Reference a global variable.
image item operand	Reference an item in an image definition.
menu item operand	Reference an item in a menu definition.
numeric constant	Specify a numeric value.
parameter operand	Reference a Model 204 parameter.
percent variable operand	Reference a User Language percent variable.
quality assurance operand	Reference quality assurance information about a request.
screen item operand	Reference an item in a screen definition.
softspy variable	Reference user-defined operands in macros and commands.
statistic operand	Reference statistics.
string constant	Specify a character string value.
usage operand	Reference usage information about server tables and the CCATEMP scratch file.

Operands normally have a character, numeric, or boolean result. However, the result of an operand can also be invalid, not available, not present, undefined, or unknown. The meaning of the results for each operand, and the reasons they occur, are explained in detail for each operand.

Operands are used in expressions and in the DISPLAY, UNWATCH, and WATCH commands. Functions can also be used wherever operands can be used.

compilation operand

Function

Reference compile-time information about a request.

Syntax

[C.] compilation_operand

Restrictions

The context must be COMPILE_ERROR or EVAL.

Description

Compilation operands indicate static compile time information about a User Language request. They have values for each line within the request. The prefix C. indicates compile-time use. It must be specified for server tables since all server tables are available as run-time usage_operands, which is the default.

Server table compilation operands show the compile time usage of a specified server table in bytes at the end of compilation of the request line when used in the SHOW command or the $SOURCE_LINE_INFO function. When used elsewhere, they return the total usage at the end of compilation. The interactive performance tuning feature must be available to use server table compilation operands within a SHOW command. The audit feature enables the QTBL compilation operand to be used within a SHOW command.

Information on the following server tables is available:

Table	Description
SERVER	The total of all of the following tables
FSCB	Full Screen Buffer Table
FTBL	File Group Table
GTBL	Global Variable Table
ITBL	Dummy String and $READ Table
NTBL	Labels, Names and Variables Table
OUTPB	Output Page Buffer
PDL	User Pushdown List
QTBL	Internal Statement Table
RTBL	User, Field, Group Security Table
STBL	Character String Table
TTBL	Temporary Work Page List Table
VTBL	Compiler Variable Table
XTBL	Procedure Security Table

A number of additional compilation operands are available. They show the indicated information for each request line when used in the SHOW command or the $SOURCE_LINE_INFO function. When used elsewhere they return the indicated information for the current line in the source window. The additional compilation operands are summarized below.

Operand	Description
INC	The include level. It starts at zero and increases by one in each procedure included with an INCLUDE at either command level or User Language statement level.
LINENO	Expanded request line number.
NEST	The nesting level at the beginning of the request line. It starts at 0 and is increased by 1 in each IF BLOCK, REPEAT LOOP, FOR LOOP, ON UNIT or SUBROUTINE.
TYPE	The line type. It is "C" if the line is blank or a comment or a comment continuation, "X" if the line is the first line of an executable statement (you can set a break point on it), or blank otherwise.

Examples

C.SERVER C.QTBL NEST C.NEST TYPE LINENO SHOW C.SERVER SHOW BRACKET NEST

field operand

Function

Reference a field in the current record.

Syntax

Restrictions

The context must be EVAL and the interactive debugging option is required.

Description

A field operand refers to a field in the current record and file. Any field name may be specified. If a field name does not begin with an alphabetic character, or contains non-alphanumeric characters, the second form of the field operand must be used in which the field name is specified using a string constant. The third form specifies a percent variable that contains the field name. The specified percent variable cannot be an array.

The optional simple expression enclosed in parentheses following the field name specifies the field occurrence number. If it is not specified then occurrence one is assumed.

The F. prefix must be included if the field name specified is also a compilation, global variable, parameter, quality assurance, statistic, or usage operand. Otherwise SoftSpy assumes that the other operand with the same name is referenced rather than the field.

A result of UNDEFINED is returned if there is no current record, the field is not defined in the current file, or field level security prevents read access. A result of NOT PRESENT is returned if there is a current record, the field is defined in the current file, and field level security allows read access but the requested occurrence does not exist. A result of INVALID is returned if the occurrence number is not a positive integer. A result of NOT AVAILABLE is returned if the interactive debugging option is not available, or if the context is not EVAL.

Examples

F.DESCRIPTION DESCRIPTION DESCRIPTION(2) F.'DESCRIPTION LINE' F.'DESCRIPTION LINE'(2) WATCH F.'DESCRIPTION LINE'(%I) WATCH %%FIELD

global variable operand

Function

Reference a global variable.

Syntax

Restrictions

The context must be COMPILE_ERROR or EVAL and the interactive debugging option is required.

Description

A global variable operand refers to a global variable. Any global variable name may be specified. If the variable name does not begin with an alphabetic character, or contains non-alphanumeric characters, the second form of the global operand must be used in which the variable name is specified using a string constant. Global variable names are case sensitive.

The G. prefix must be included if the global variable name specified is also a compilation, parameter, quality assurance, statistic, or usage operand. Otherwise SoftSpy assumes the other operand with the same name is referenced rather than the global variable. Similarly, the G. prefix should be specified if the global variable might be undefined when a field with the same name is defined. Otherwise the field is referenced rather than the undefined global.

A result of UNDEFINED is returned if the global variable is not defined. A result of NOT AVAILABLE is returned if the interactive debugging feature is not available, or if the context is not COMPILE_ERROR or EVAL.

Examples

G.NAME NAME G.'FIRST NAME' G.'M.I.' WATCH G.COMM

image item operand

Function

Reference an item in an image definition.

Syntax

Restrictions

The context must be EVAL and the interactive debugging option is required.

Description

An image item operand refers to an item in an image definition. Two forms of image item operands are permitted. The first explicitly specifies an image item name. The second specifies a percent variable operand that contains the image item name. The specified percent variable cannot be an array.

If the image item is an array then subscript values must be provided for each dimension, up to the maximum of three dimensions supported by SoftSpy. The subscripts may be simple_expressions. In DISPLAY and WATCH commands an asterisk can be used for a subscript to indicate that the value of the image item should be displayed or watched for each allowed subscript value.

The scope of images and the associated image items can be limited to portions of a User Language request. For example, image items defined in a complex subroutine that are not declared common have definitions specific to that subroutine. References to image items are always in the scope of the next statement to execute in the User Language request.

A result of UNDEFINED is returned if the image or image item is not defined. A result of NOT PRESENT is returned if the image item is defined, but the image is not active. A result of INVALID is returned if the image item is not an array, and subscripts are specified, or if it is an array, but the number or value of the subscripts is not valid. A result of NOT AVAILABLE is returned if the interactive debugging feature is not available, or if the context is not EVAL.

Examples

%PRINT_DATA:HEADER_LINE %PRINT_DATA:DATA_LINE(1) %COURSE.DATA:COURSE.NAME(%I) %COURSE.DATA:COURSE.STUDENT(%I,1) %RECORD:READLEN  :%IMAGE_ITEM_NAME WATCH %PRINT_DATA:DATA_LINE(*) WATCH %COURSE.DATA:COURSE.STUDENT(%I,*)

menu item operand

Function

Reference an item in a menu definition.

Syntax

Restrictions

The context must be EVAL and the interactive debugging option is required.

Description

A menu item operand refers to an item in a menu definition. Two forms of menu item operands are permitted. The first explicitly specifies a menu item name. The second specifies a percent_variable_operand containing the menu item name. The specified percent variable cannot be an array.

The scope of menus and the associated menu items can be limited to portions of a User Language request. For example, menu items defined in a complex subroutine that are not declared common have definitions specific to that subroutine. References to menu items are always in the scope of the next statement to execute in the User Language request.

A result of UNDEFINED is returned if the menu or menu item is not defined. A result of INVALID is returned if subscripts are specified. A result of NOT AVAILABLE is returned if the interactive debugging feature is not available, or if the context is not EVAL.

Examples

%MENU:SELECTION :%MENU_ITEM_NAME DISPLAY %MENU:SELECTION

numeric constant

Function

Specify a numeric value.

Syntax

{ digit } ...

Description

A numeric constant is used to specify a numeric value. Allowed values are in the following range:

0 - 999,999,999,999,999 

Note: Do not enter the commas, which are provided here for clarity.

Examples

0 255 2147483647 999999999999999

parameter operand

Function

Reference a Model 204 parameter.

Syntax

[P.]parameter_name [ ( [FILE] file_name ) ]

Restrictions

The context must be COMPILE_ERROR or EVAL.

Description

A parameter_operand refers to a Model 204 parameter. Any Model 204 parameter can be specified. If a parameter requires a file context and one is not specified, the current file is assumed. An error message is issued if a file context is specified for a parameter not related to a file.

If a valid parameter name is not used an error message is issued. A result of INVALID is returned if a file context is specified for a parameter, but the file is not open. A result of NOT AVAILABLE is returned if the parameter is a file parameter and security prevents viewing file parameters, or if the context is not COMPILE_ERROR or EVAL.

Examples

P.LSTBL LSTBL FREESIZE(METADATA) WATCH FREESIZE(FILE METADATA)

percent variable operand

Function

Reference a User Language percent variable.

Syntax

%variable_name [ (simple_expression[,simple_expression[,simple_expression] ] ) ]

Restrictions

The context must be EVAL and the interactive debugging option is required.

Description

A percent variable operand refers to a User Language percent variable. Any percent variable may be specified. If the percent variable is an array, subscript values must be provided for each dimension. The subscripts must be simple_expressions. In DISPLAY and WATCH commands an asterisk can be used for a subscript to indicate that the value of the percent variable should be displayed or watched for each allowed subscript value.

The scope of percent variables can be limited to portions of a User Language request. For example, percent variables defined in a complex subroutine have definitions specific to the subroutine. References to percent variables are always in the scope of the next statement to execute in the User Language request.

A result of UNDEFINED is returned if a percent variable is not defined. A result of INVALID is returned if a percent variable is not an array and subscripts are specified, or if it is an array, but the number or value of the subscripts is not valid. A result of NOT AVAILABLE is returned if the interactive debugging feature is not available, or if the context is not EVAL.

Examples

%I %NAME %ADDRESS_LINE(1) %ADDRESS_LINE(%I) %VALUE(%I,%J,%K) WATCH %ADDRESS_LINE(*) WATCH %VALUE(%I,*,*)

quality assurance operand

Function

Reference quality assurance information about a request.

Syntax

Restrictions

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

Description

A quality assurance operand accesses data that is useful when testing an application and may be specified with an operand qualifier of Q. Each of these operands is described in the following table.

Name	Meaning
TESTED	Indicates if a statement has been tested. It has the value 'T' if the line is the first line of an executable statement with an EXECOUNT greater than zero. Otherwise it has a value of blank.
UNTESTED	Indicates if a statement has not been tested. It has the value 'U' if the line is the first line of an executable statement with an EXECOUNT of zero. Otherwise it has a value of blank.
TEST_STATUS	Indicates the testing status of a statement. It has the value 'T' if the line is the first line of an executable statement with an EXECOUNT greater than zero, 'U' if the line is the first line of an executable statement with an EXECOUNT of zero, or blank otherwise.
REACHABLE	Indicates if a statement is reachable. It has the value 'R'if the line is the first line of a reachable executable statement. Otherwise it has a value of blank.
UNREACHABLE	Indicates if a statement is unreachable. It has the value 'U' if the line is the first line of an unreachable executable statement. Otherwise it has a value of blank.
REACH_STATUS	Indicates the reachability status of a statement. It has the value 'R' if the line is the first line of a reachable executable statement, 'U' if the line is the first line of an unreachable executable statement, or blank otherwise.

An unreachable statement can never be executed no matter what execution path a request takes, for example, statements in a subroutine that is never called.

When a quality assurance operand is used other than as a parameter to SHOW or $SOURCE_LINE_INFO, it returns the value for the current line.

A quality assurance operand has a result of NOT AVAILABLE in the following cases:

• A request is not being evaluated (the context is not EVAL).
• The QA option is not available.
• EXECOUNT is not being collected on TESTED, UNTESTED, and TEST_STATUS.

Examples

Q.TESTED TESTED UNTESTED TEST_STATUS REACHABLE UNREACHABLE SHOW TEST_STATUS

screen item operand

Function

Reference an item in a screen definition.

Syntax

Restrictions

The context must be EVAL and the interactive debugging option is required.

Description

A screen item operand refers to an item in a screen definition. Two forms of screen item operands are permitted. The first explicitly specifies a screen item name. The second specifies a percent variable operand containing the screen item name. The percent variable specified cannot be an array.

Screen_item_operands can specify any screen item. The scope of screens and the associated screen items can be limited to portions of a User Language request. For example, screens defined in a complex subroutine have definitions specific to that subroutine. References to screen items are always in the scope of the next statement to execute in the User Language request.

A result of UNDEFINED is returned if the screen or the screen item is not defined. A result of INVALID is returned if subscripts are used. A result of NOT AVAILABLE is returned if the interactive debugging feature is not available, or if the context is not EVAL.

Examples

%MAIN:LINE1 %SCREEN:ROW %SCREEN:COLUMN %SCREEN:PFKEY %SCREEN:ITEMID WATCH :%CURITEM

softspy variable

Function

Reference user-defined operands in macros and commands.

Syntax

Description

A softspy variable operand refers to a previously defined SoftSpy variable. If the softspy_variable reference occurs in a macro, and the softspy variable is defined with LOCAL scope in the macro, the value associated with that definition will be returned. Otherwise, the value associated with the definition of the softspy variable with SESSION scope will be returned.

If the softspy variable is not defined with LOCAL scope in the current macro or with SESSION scope, an error message is issued and the statement referencing the undefined softspy variable is not executed.

Examples

$TEMP $END_EVAL_SCROLL_TOP $SKIP_SUBSYSTEMS SET $L = $L IF $L IS NUM LE $MAX_LINE('SOURCE') THEN JUMP TO LOOP COMMAND $TEMP

SOUL object operand

In Model 204 Version 7.6 and up, SoftSpy can now access the values of SOUL objects. Prior to version 7.6, any attempt to watch or display or reference these items resulted in "xxx is undefined" being displayed, where xxx is the name of the SOUL object variable.

SOUL object operands include:

• object variables:

  %r1 is object rectangle

• object member variables:

  variable height is float readonly

• enumerations:

  variable isSquare is enumeration boolean readonly

statistic operand

Function

Reference statistics.

Syntax

Restrictions

The context must be EVAL.

Description

A statistic operand refers to a SoftSpy statistic. Included are all Model 204 user statistics and an additional SoftSpy statistic, EXECOUNT, which is a statement execution counter. If a statistic name contains parentheses, the second form of the statistic operand must be used in which the statistic name is specified using a string constant.

Statistics can be qualified with LOGIN, SPY, EVAL, or STMT. If a qualifier is not used, EVAL is assumed.

Statistic_operand qualifiers and their meanings are as follows:

Qualifier	Meaning
EVAL	The change in the statistic value since request evaluation began.
LOGIN	The value of the statistic.
SPY	The change in the statistic value since SoftSpy was turned on.
STMT	The change in the statistic value since the last STEP or GO command was issued during evaluation of the current User Language request.

EXECOUNT cannot be used with the LOGIN qualifier. The interactive performance tuning feature is required for all statistics except EXECOUNT. The quality assurance option is required for the EXECOUNT statistic. An error message is issued if a valid statistic name is not specified. The result is NOT AVAILABLE if a required optional feature is not available, or if the context is not EVAL.

Statistics and their meanings are as follows:

Statistic	Meaning
AUDIT	Journal lines written
BACKOUTS	Update unit backouts
BADD	Table B fields added
BCHG	Table B fields changed in place
BDEL	Table B fields deleted
BXCHNG	Ordered index segments changed
BXDELE	Ordered index deletes
BXFIND	Ordered index searches for single values
BXFREE	Ordered index nodes emptied
BXINSE	Ordered index inserts
BXNEXT	Ordered index entries examined during range retrievals
BXRFND	Ordered index searches for a range of values
BXSPLI	Ordered index node splits
CNCT	Elapsed time in seconds
COMMITS	Update unit commits
CPU	CPU time in milliseconds
DIRRCD	Table B records examined in direct searches
DKAR	Pages allocated (any prior contents of page discarded)
DKPR	Pages requested (with and without real I/O required)
DKRD	Pages requested (with real I/O required)
DKRR	Pages requested that Model 204 is aware were recently requested
DKWR	Pages written (with real I/O required)
DUMP	Pages written to dump data sets
EXECOUNT	Number of User Language statements executed
FBWT	Pages requested when no disk buffers were available
FINDS	Finds performed
IXADD	Key index entries added
IXDEL	Key index entries deleted
LONGUPDTS	Times the duration of an update unit exceeded the value of the MAXUD parameter
LONGUPDTIME(MS)	Total duration in milliseconds of all update units whose length exceeds the value of the MAXUD parameter
MOVE	Times the user was dispatched
PBRSFLT	Private buffer reservation faults
RECADD	Table B records added
RECDEL	Table B records deleted (excluding delete records statements)
RECDS	Table B records processed by for and sort statements
REQ	Requests evaluated and display procedure commands executed
REST	Pages read from dump data sets
SCHDCPU	CPU time used in milliseconds in the scheduler task with MP204
SCREENS	Screen read requests
SGMTI	Procedure lines read
SGMTO	Procedure lines written
SLIC	Times execution was suspended and a wait was not required
SORTS	Sort statements processed
SQRD	Terminal input lines read
SQWR	Terminal output lines written
STCPU	CPU time used in milliseconds in an offload subtask with MP204
STDEQ	Times user was dispatched in an offload subtask with MP204
STRECDS	Table B records processed by sort statements
SVPAGES	Server data set I/O volume in pages
SVRD	Server reads performed
SVWR	Server writes performed
UDD	Use data set lines written
UPDTTIME(MS)	Total duration in milliseconds of all update units
WAIT	Real operating system waits

Examples

S.CPU CPU DKPR(STMT) S.'UPDTTIME(MS)' WATCH EXECOUNT(EVAL) WATCH S.'UPDTTIME(MS)'(LOGIN) SHOW DKPR

string constant

Function

Specify a character string value.

Syntax

Description

A string constant specifies a character string value. Strings can be quoted with either single or double quotes. If a string constant is enclosed in single quotes then a pair of single quotes must be used within the constant to represent each instance of a single quote. Similarly, if a string constant is enclosed in double quotes then a pair of double quotes must be used within the constant to represent each instance of a double quote.

Examples

'EVAL' "EVAL" 'DON''T' "DON'T"

usage operand

Function

Reference usage information about server tables and the CCATEMP scratch file.

Syntax

[U.] usage_operand

Restrictions

The context must be EVAL.

Description

A usage operand refers to the current usage level of a Model 204 resource, including server table usage and CCATEMP scratch file usage.

The CCATEMP operand returns the number of CCATEMP file pages used by the request. If CCATEMP is specified and the interactive performance tuning feature is not available, or if the context is not EVAL, the result is NOT AVAILABLE.

Server table usage operands show the current usage of a specified server table in bytes. Server tables whose usage can be determined are summarized in the following table:

Table	Description
SERVER	The total of all of the following tables
FSCB	Full Screen Buffer Table
FTBL	File Group Table
GTBL	Global Variable Table
ITBL	Dummy String and $READ Table
NTBL	Labels, Names and Variables Table
OUTPB	Output Page Buffer
PDL	User Pushdown List
QTBL	Internal Statement Table
RTBL	User, Field, Group Security Table
STBL	Character String Table
TTBL	Temporary Work Page List Table
VTBL	Compiler Variable Table
XTBL	Procedure Security Table

The server table usage operands differ from the server table length parameters in two ways. First, the server table length parameters show the maximum permitted usage rather than actual current usage. Second, the server table length parameters are given in table allocation units, which are not always in bytes.

The value of a server table usage operand is based on the amount of the table in use after completion of the last statement and prior to execution of the next statement. Temporary usage of server tables during execution of a statement is never included. For example, space in STBL can be used during the execution of a statement, but released before execution of the statement is completed. Thus the evaluation time high water mark for a server table can exceed any observed server table usage value.

An error message is issued if the server table usage operand does not specify the name of a server table. A result of NOT AVAILABLE is returned if the context is not EVAL.

Examples

U.STBL VTBL U.CCATEMP PDL WATCH U.SERVER WATCH CCATEMP SHOW U.VTBL