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,*)
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
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 Can be:
- object variables - for example: %r1 is object rectangle
- object member variables
- enumerations
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
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