SoftSpy functions
Introduction
SoftSpy includes numerous functions which augment expression handling and return useful information about the working environment in SoftSpy.
Functions normally have a character, numeric, or boolean result. However, the result of a function can also be invalid, not available, not present, undefined, or unknown. The meaning of the results for each function, and the reasons they occur, are explained in detail for each function. Functions can be used wherever operands can be used.
The following table describes the SoftSpy functions.
| Function | Description |
|---|---|
|
Return the name of the active window. |
|
|
Return the value contained on the SoftSpy command line. |
|
|
Return the SoftSpy context. |
|
|
Return a count of the number of lines in the source window that meet a specified condition. |
|
|
Return a count of the number of records in a record set. |
|
|
Specify the current line number in a window. |
|
|
Return the name of the help topic on which the cursor is positioned. |
|
|
Return the line number on which the cursor is positioned in a window. |
|
|
Specify the default limit on the number of JUMP TO statements that can be executed in a macro. |
|
|
Return the default window name for WATCH and UNWATCH commands. |
|
|
Return the last counting error message or request cancellation message. |
|
|
Return the position of one string in another string. |
|
|
Return the type of interrupt that suspended request evaluation. |
|
|
Specify a limit on the number of JUMP TO statements that can be executed in the current macro. |
|
|
Return the length of a string. |
|
|
Return the line number of a line in the source window that meets a specified condition. |
|
|
Return the argument string passed to the current macro. |
|
|
Test for the existence of a macro. |
|
|
Return the position of the first character in a string that matches any character in another string. |
|
|
Return the number of lines in a window. |
|
|
Return the name of the default MUSE handle. |
|
|
Test if an optional SoftSpy feature is available. |
|
|
Pad a string to a specified length. |
|
|
Return the name of the file containing the procedure containing the current User Language request. |
|
|
Return the name of the procedure containing current User Language request. |
|
|
Prompt the user for input and return the response. |
|
|
Return data about a line in the source window. |
|
|
Return information that can be displayed in the source window with the SHOW command. |
|
|
Return the most recent SoftSpy message. |
|
|
Return the value of the Model 204 $STATUS function. |
|
|
Return the value of the Model 204 $STATUSD function. |
|
|
Return a string, or substring that is part of another string. |
|
|
Return the name of the current subsystem. |
|
|
Return the number of CCATEMP pages used by a record set |
|
|
Return the number of pages of CCATEMP used for a specified purpose |
|
|
Return the position of the first character in a string that does not match any character in another string. |
|
|
Test for pending updates. |
|
|
Return the user identifier of the current user. |
$ACTIVE_WINDOW
Function
Return the name of the active window.
Syntax
$ACTIVE_WINDOW
Description
The $ACTIVE_WINDOW function returns the name of the active window.
When the context is COMPILE_ERROR or EVAL, the name of the active window is either SOURCE or the name of a window opened with the OPEN WINDOW command. The sequence of ACTIVE WINDOW and CLOSE WINDOW commands determines the current active window. If no ACTIVE WINDOW command has been issued, the active window name is the SOURCE window.
When the context is neither COMPILE_ERROR nor EVAL, the name of the active window is always the same as the context name. Thus the active window name matches the context name of BROWSE, CONFIG, EDIT, HELP, or LIST.
Examples
IF $ACTIVE_WINDOW EQ 'SOURCE' THEN RETURN COMMAND 'CLOSE WINDOW ' WITH $ACTIVE_WINDOW
See Also
ACTIVE WINDOW, CLOSE WINDOW
$COMMAND
Function
Return the value contained on the SoftSpy command line.
Syntax
$COMMAND
Description
The $COMMAND function returns the character string contained on the SoftSpy command line. Any leading or trailing blanks are deleted. $COMMAND is useful in program function key definitions, or macros used by program function key definitions, when the operation of the program function key should consider the value contained on the command line.
Examples
PF4 = COMMAND 'STEP ' WITH $COMMAND PF8 = COMMAND 'FORWARD ' WITH $COMMAND SET $OPERANDS = $COMMAND
$CONTEXT
Function
Return the SoftSpy context.
Syntax
$CONTEXT
Description
The $CONTEXT function returns the current SoftSpy context, or a null string if there is no current context. Context values are BROWSE, COMPILE_ERROR, CONFIG, EDIT, EVAL, HELP, and LIST. $CONTEXT is useful in macros or program function key definitions when the operation of a macro or program function key should consider the current context.
Examples
IF $CONTEXT EQ 'EVAL' THEN JUMP TO EVAL IF $CONTEXT NE 'HELP' THEN RETURN
$COUNT_LINES
Function
Return a count of the number of lines in the source window that meet a specified condition.
Syntax
$COUNT_LINES (operand, operator, value[, first_line [, last_line]])
Restrictions
The context must be COMPILE_ERROR or EVAL.
Parameters
$COUNT_LINES takes three required and two optional simple expressions as parameters. The operand, operator, and value parameters specify a condition which must be true for a line to be counted. The first_line and last_line parameters specify the range of lines to check.
Description
$COUNT_LINES examines a range of lines within the current User Language request for those that meet a specified condition. A count of the number of lines that meet the specified condition is returned.
The first three parameters specify the condition. The operand parameter must resolve to a compilation_operand, a quality_assurance_operand, a statistic_operand without a qualifier, or a usage_operand. Any evaluation time data must already be collected to be accessed by this function. The operator parameter must resolve to either EQ or NE. The value parameter must resolve to a value.
The value of the specified operand is compared with the specified value for each line. If the EQ operator is specified, a count of the number of lines where the operand and value are equal is returned. Otherwise, a count of the number of lines where they are not equal is returned.
The last two parameters specify a range of lines to include in the count. The first_line parameter indicates the first line to include in the count. If it is omitted it defaults to line number one. The last_line parameter indicates the last line to include in the count. If it is omitted it defaults to the last line in the current User Language request.
A result of UNDEFINED is returned if the operand parameter does not specify the name of a defined operand. A result of INVALID is returned if any of the parameters are not valid. A result of NOT AVAILABLE is returned if the context is not COMPILE_ERROR or EVAL, or if the specified operand is not available because it is not being collected or because a required optional feature is not available.
Examples
SET $TESTED = $COUNT_LINES('TESTED','EQ','T') SET $REACHABLE = $COUNT_LINES('REACHABLE','EQ','R') SET $UNREACHABLE = $COUNT_LINES('UNREACHABLE','EQ','U') IF $COUNT_LINES('UNTESTED','EQ','U') THEN JUMP TO UNTEST
$COUNT_RECORDS
Function
Return a count of the number of records in a record set.
Syntax
$COUNT_RECORDS(record_set)
Parameters
Takes a simple_expression that identifies a record set whose records are to be counted.
Restrictions
The context must be EVAL.
Description
$COUNT_RECORDS is used to count the number of records in a record set.
The record_set must resolve to one of three formats. If it resolves to a string of the form IN name then the number of records in the found set named is returned. If it resolves to a string of the form ON name then the number of records in the named record list is returned. If it just resolves to a name, then it is first used as a statement label or number for a found set, and secondly as a list name.
If record_set does not resolve to a syntactically correct result then a result of INVALID is returned. If the specified record set does not exist then a result of UNDEFINED is returned. If the context is not EVAL then the result is NOT AVAILABLE.
Examples
DISPLAY $COUNT_RECORDS('FD1') WATCH $COUNT_RECORDS('IN FD1') DISPLAY $COUNT_RECORDS('ON LIST1')
$CURRENT_LINE
Function
Specify the current line number in a window.
Syntax
$CURRENT_LINE[(window_identifier)]
Parameters
$CURRENT_LINE takes window_identifier, a single optional simple_expression which identifies the window to use.
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $CURRENT_LINE function returns the number of the current line in the specified window.
If the window_identifier parameter is omitted or null, the name of the active window is used. A result of INVALID is returned if the window_identifier does not identify an open window. If the EDIT CONFIG window is specified a result of UNDEFINED is returned.
When used in a SET command, $CURRENT_LINE can be used to set the current line for the source window. The window_identifier must be "SOURCE", otherwise an error is issued.
Examples
SET $SOURCE_LINE = $CURRENT_LINE('SOURCE') SET $CURRENT_LINE('SOURCE') = $N
$CURSOR_HYPERTEXT
Function
Return the name of the help topic on which the cursor is positioned.
Syntax
$CURSOR_HYPERTEXT
Restrictions
The context must be HELP.
Description
The $CURSOR_HYPERTEXT function returns the hypertext link value for the cursor position. If the cursor is positioned on a topic for which help is available, $CURSOR_HYPERTEXT returns the name of the help topic. This function is useful when tailoring the help context.
A result of NOT AVAILABLE is returned if the context is not HELP.
Examples
TRANSFER COMMAND 'HELP ' WITH $CURSOR_HYPERTEXT IF $CURSOR_HYPERTEXT EQ THEN JUMP TO ERROR
See Also
HELP
$CURSOR_LINE
Function
Return the line number on which the cursor is positioned in a window.
Syntax
$CURSOR_LINE(window_identifier)
Parameters
$CURSOR_LINE takes window_identifier, a single simple_expression that identifies the window to use.
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
$CURSOR_LINE returns the number of the line the cursor is on. This number is relative to the entire contents of the window, including lines not displayed on the screen. A zero is returned if the cursor is not in the window specified.
Window_identifier is a simple expression that must resolve to "SOURCE".
Examples
SET $L = $CURSOR_LINE('SOURCE') IF $CURSOR_LINE('SOURCE') THEN JUMP TO HAVE_CURSOR
$DEFAULT_JUMP_LIMIT
Function
Specify the default limit on the number of JUMP TO statements that can be executed in a macro.
Syntax
$DEFAULT_JUMP_LIMIT
Description
$DEFAULT_JUMP_LIMIT determines the initial value for $JUMP_LIMIT in a macro. The value of $JUMP_LIMIT controls the maximum number of JUMP TO statements that may be executed in a macro. If the value is zero, no limit is enforced. A non-zero value terminates infinite loops.
$DEFAULT_JUMP_LIMIT can be used as an operand or can be assigned a value in a SET statement. It can only be set to zero or a positive integer. The initial value of $DEFAULT_JUMP_LIMIT is 1000.
Changing the value of $DEFAULT_JUMP_LIMIT only changes the initial value of $JUMP_LIMIT for subsequently executed macros. The value of $JUMP_LIMIT for already executing macros is not affected.
Examples
SET $DEFAULT_JUMP_LIMIT = 666 SET $DEFAULT_JUMP_LIMIT = 0 DISPLAY $DEFAULT_JUMP_LIMIT
See Also
$JUMP_LIMIT, EXEC
$DEFAULT_WATCH_WINDOW
Function
Return the default window name for WATCH and UNWATCH commands.
Syntax
$DEFAULT_WATCH_WINDOW
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $DEFAULT_WATCH_WINDOW function returns the active window name, unless it is the SOURCE window. If the active window is the source window and only one window other than the SOURCE window is open the name of that window is returned. If no window other than the SOURCE window is open a null string is returned. If the SOURCE window is the active window and two or more additional windows are open a null string is also returned.
A result of NOT AVAILABLE is returned unless the context is COMPILE_ERROR or EVAL.
Examples
IF $DEFAULT_WATCH_WINDOW NE THEN JUMP TO HAVE_WINDOW COMMAND 'IN ' WITH $DEFAULT_WATCH_WINDOW WITH ' TOP'
See Also
ACTIVE WINDOW, IN WINDOW, WATCH
$ERRMSG
Function
Return the last counting error message or request cancellation message.
Syntax
$ERRMSG
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $ERRMSG function returns the text of the last counting error message or request cancellation message for the user. This message text includes the error message prefix. A null string is returned if no counting error or request cancellation has occurred since the start of the user's Model 204 session.
A result of NOT AVAILABLE is returned unless the context is COMPILE_ERROR or EVAL.
Examples
PRINT LINE $ERRMSG
$INDEX
Function
Return the position of one string in another string.
Syntax
$INDEX(string,sought_string)
Parameters
$INDEX takes two simple_expressions, string and sought_string.
Description
$INDEX locates the first occurrence of the sought_string within string and returns a number equal to the position where it begins. If the sought_string cannot be found in the string, or either string is a null string, a value of zero is returned.
If the result of either parameter is not known, $INDEX returns a result of INVALID.
Examples
IF NOT $INDEX($SKIP_SUBSYSTEMS,$SUBSYS) THEN RETURN SET $I = $INDEX($TEXT,$RIGHT_PAREN)
$INTERRUPT_TYPE
Function
Return the type of interrupt that suspended request evaluation.
Syntax
$INTERRUPT_TYPE
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $INTERRUPT_TYPE function returns the reason processing of your application was suspended. If processing was suspended because a GO UNTIL condition was satisfied or because the number of statements specified in a STEP command were successfully executed, then null string is returned since an interrupt did not occur.
The interrupt type values are as follows:
| Value | Meaning |
|---|---|
| BREAK | A break point was encountered. |
| CANCEL | Request evaluation was cancelled due to an error. |
| COMPILE_ERROR | A request failed to compile successfully. |
| END_EVAL | Evaluation of a request was completed. |
| EVAL | Evaluation of a new request was begun. |
| NON_CANCEL | An error occurred during request evaluation, but the request has not been cancelled (for example, division by zero). |
| USER_CANCEL | Request evaluation was cancelled by the user (for example, *CANCEL). |
A result of NOT AVAILABLE is returned if the context is not COMPILE_ERROR or EVAL.
Examples
IF $INTERRUPT_TYPE EQ '' THEN JUMP TO LOOP PRINT LINE '* TERMINATED BY ' WITH $INTERRUPT_TYPE
$JUMP_LIMIT
Function
Specify a limit on the number of JUMP TO statements that can be executed in the current macro.
Syntax
$JUMP_LIMIT
Restrictions
Must be used in a macro.
Description
The value of $JUMP_LIMIT in a macro controls the maximum number of JUMP TO statements that may be executed in that macro. If the value is zero, no limit is enforced. If the $JUMP_LIMIT constraint is violated the macro is terminated. This prevents infinite loops.
$JUMP_LIMIT may be used as an operand or may be assigned a value in a SET statement. It can only be set to zero or a positive integer.
Each executing macro has its own distinct value for $JUMP_LIMIT. The value of $JUMP_LIMIT for a particular executing macro is initialized to the value of $DEFAULT_JUMP_LIMIT at the time the macro is invoked. The value of $JUMP_LIMIT is UNDEFINED if a macro is not running.
Examples
SET $JUMP_LIMIT = 0 SET $JUMP_LIMIT = 100 DISPLAY $JUMP_LIMIT
See Also
$DEFAULT_JUMP_LIMIT,EXEC, JUMP TO
$LEN
Function
Return the length of a string.
Syntax
$LEN(string)
Parameters
$LEN takes a single simple_expression.
Description
$LEN returns the length in bytes of the string being evaluated. If the parameter string is null, a zero will be returned. If the value of a string is not known then the result is INVALID.
Examples
IF $LEN($SCROLLF) NE 2 THEN JUMP TO FORWARD_ORDERED SET $N = $LEN($S)
$LOCATE_LINE
Function
Return the line number of a line in the source window that meets a specified condition.
Syntax
$LOCATE_LINE(operand, operator, value [, first_line[,last_line]])
Restrictions
The context must be COMPILE_ERROR or EVAL.
Parameters
$LOCATE_LINE takes three required and two optional simple_expressions as parameters. The operand, operator, and value parameters specify a condition which is true for the line to be returned. The first_line and last_line parameters specify the range of lines to check.
Description
$LOCATE_LINE examines a range of lines within the current User Language request for a line that meets the specified condition. The line number of the first such line is returned. If no lines are found then a result of NOT PRESENT is returned.
The first three parameters specify the condition. The operand parameter must resolve to a compilation_operand, a quality_assurance_operand, a statistic_operand without a qualifier, or a usage_operand. Any evaluation time data must already be collected to be accessed by this function. The operator parameter must resolve to EQ, NE, MAX LT, or MIN GT. The value parameter must resolve to a value. Both the operand and the value parameters must be numeric if the operator is MAX LT or MIN GT.
The value of the specified operand is compared with the specified value for each line. If the EQ operator is specified the line number of the first line where the operand and value are equal is returned. If the NE operator is specified the line number of the first line where the operand and value are not equal is returned. If the MAX LT operator is specified the line number of the first line with the largest value of operand that is numerically less than value is returned. If the MIN GT operator is specified the line number of the first line with the smallest value of operand that is numerically greater than value is returned.
The last two parameters specify the range of lines to search. The first_line parameter indicates the first line to search. If it is omitted it defaults to line number one. The last_line parameter indicates the last line to search. If it is omitted it defaults to the last line in the current User Language request. A forward search is performed when first_line is smaller than last_line. A backward search is performed when first_line is greater than last_line.
A result of UNDEFINED is returned if the operand parameter does not specify the name of a defined operand. A result of INVALID is returned if any of the parameters are not valid. A result of NOT AVAILABLE is returned if the context is not COMPILE_ERROR or EVAL, or if the specified operand is not available because it is not being collected or because a required optional feature is not available.
Examples
SET $LINE = $LOCATE_LINE('CPU','MAX LT','999999999') SET $N = $LOCATE_LINE($SCROLLO,$SCROLLF,$SCROLLV,$L) SET $N = $LOCATE_LINE($SCROLLO,$SCROLLB,$SCROLLV,$L,1) SET $CURRENT_LINE('SOURCE') = $LOCATE_LINE('UNTESTED','EQ','U')
$MACRO_ARGS
Function
Return the argument string passed to the current macro.
Syntax
$MACRO_ARGS
Restrictions
Must be used in a macro.
Description
$MACRO_ARGS returns the argument, or parameter information specified with a macro when it is run. $MACRO_ARGS must be issued while a macro is executing. The value returned will be the text that follows the macro name, with leading and trailing blanks stripped.
If an attempt to use $MACRO_ARGS is made when a macro is not running, a result of UNDEFINED is returned.
Examples
COMMAND 'DISPLAY ' WITH $MACRO_ARGS COMMAND $MACRO_ARGS WITH ' ' WITH $OPERANDS IF $MACRO_ARGS EQ '' THEN JUMP TO FORWARD IF $MACRO_ARGS EQ 'TOP' THEN JUMP TO TOP TRANSFER COMMAND 'EXEC SCROLL_SET ' WITH $MACRO_ARGS SET $S = $MACRO_ARGS
See Also
EXEC
$MACRO_EXISTS
Function
Test for the existence of a macro.
Syntax
$MACRO_EXISTS(macro_identifier)
Parameters
$MACRO_EXISTS takes macro_identifier, a simple_expression which specifies the name of the macro being tested.
Description
$MACRO_EXISTS tests for the existence of a macro named by the macro_identifier parameter. It returns a value of true if it exists and a value of false if it does not exist.
A result of INVALID is returned if the macro_identifier parameter does not specify a syntactically correct macro name.
Examples
IF $MACRO_EXISTS($MACRO_NAME) THEN COMMAND $MACRO_NAME
$MATCH
Function
Return the position of the first character in a string that matches any character in another string.
Syntax
$MATCH(string,set)
Parameters
$MATCH takes two simple_expressions as parameters. The first identifies the string to search. The second specifies the set of characters to match against.
Description
The $MATCH function returns the first position within the first string where any of the characters specified in the second string appears. If either string is null, or if no character in the second string is found in the first string, a value of zero is returned.
If the value of either parameter is not known, $MATCH returns a result of INVALID.
Examples
IF $MATCH($STRING,':') THEN JUMP TO SCREEN_ITEM SET $I = $MATCH($TEXT,$DELIMITERS)
$MAX_LINE
Function
Return the number of lines in a window.
Syntax
$MAX_LINE[(window_identifier)]
Parameters
$MAX_LINE takes window_identifier, a single optional simple_expression which identifies the window to use.
Description
$MAX_LINE returns the total number of lines in the specified window. This includes lines not displayed on the screen. If the parameter is omitted or null then the active window name is used.
If $MAX_LINE fails to identify an open window, a result of INVALID is returned. If the context is CONFIG, a result of UNDEFINED is returned.
Examples
IF $L IS NUM GT $MAX_LINE('SOURCE') THEN JUMP TO MISSING SET $L = $MAX_LINE('SOURCE') SET $L = $MAX_LINE SET $L = $MAX_LINE($WINDOW)
$MUSE_DEFAULT_HANDLE
Function
Return the name of the default MUSE handle.
Syntax
$MUSE_DEFAULT_HANDLE
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
$MUSE_DEFAULT_HANDLE returns the name of the current default MUSE handle.
- If output is directed to the terminal, a value of TERMINAL is returned.
- If output is directed to a USE output stream opened with a USE command, a value of USE is returned.
- If output is directed to a USE output stream opened with a MUSE OPEN command, the name of the handle associated with the stream is returned.
A result of NOT AVAILABLE is returned unless the context is COMPILE_ERROR or EVAL.
Examples
WATCH $MUSE_DEFAULT_HANDLE
$OPTION
Function
Test whether an optional SoftSpy feature is available.
Syntax
$OPTION(feature_name)
Parameters
$OPTION takes feature_name, a simple_expression that identifies the optional feature whose availability is to be determined.
Description
$OPTION returns a value of true if the optional feature specified is available, and a value of false if the optional feature specified is not available. The permitted feature names are DEBUG, QA, and TUNE. If an invalid feature name is specified then a result of INVALID is returned.
Examples
IF $OPTION('DEBUG') THEN JUMP TO DEBUG IF NOT $OPTION('QA') THEN TRANSFER ERROR 'QA UNAVAILABLE'
$PAD
Function
Pad a string to a specified length.
Syntax
$PAD (string,pad_character,length)
Parameters
$PAD takes three simple_expressions as parameters. The first identifies the string to be padded. The second is the pad_character used. The third is the length of the padded string.
Description
The $PAD function lets you add a padding character to the left of a specified string. This is sometimes useful in producing columnar output for reports.
The pad_character parameter must specify a single character to add to the left of the string if it is shorter than the specified length. If the parameter does not specify a single character then the result is INVALID.
The result string is equal in length to the length parameter specified. If the string parameter is less than the length, it is padded on the left to the specified length with the pad_character. If the string parameter is greater than the length, it is truncated from the left to the specified length. If the length is not an integer in the range zero to 255 then a result of INVALID is returned.
Examples
PRINT LINE $PAD('*','*',70) PRINT LINE $PAD($L,' ',5) WITH ' ' WITH $TEXT
$PROCFILE
Function
Return the name of the file containing the procedure containing the current User Language request.
Syntax
$PROCFILE
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $PROCFILE function returns the name of the procedure file containing the User Language request being evaluated. A null string is returned if the executing request is not contained in a procedure file. If the request is contained in multiple procedures then the name of the file containing the procedure containing the BEGIN or MORE command is used.
A result of NOT AVAILABLE is returned unless the context is COMPILE_ERROR or EVAL.
Examples
PRINT LINE 'IN ' WITH $PROCFILE
See Also
$PROCNAME
$PROCNAME
Function
Return the name of the procedure containing the current User Language request.
Syntax
$PROCNAME
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $PROCNAME function returns the name of the procedure containing the User Language request being evaluated. If this request is not contained in an included procedure, a value of "0" is returned since the current request is contained in a temporary request named "0". If the request is contained in multiple procedures, then the name of the procedure containing the BEGIN or MORE command is used.
A result of NOT AVAILABLE is returned unless the context is COMPILE_ERROR or EVAL.
Examples
PRINT LINE $PROCNAME GO UNTIL $PROCNAME EQ 'DESIRED.PROCEDURE'
See Also
$PROCFILE
$READ
Function
Prompt the user for input and return the response.
Syntax
$READ[([prompt][,case])]
Parameters
$READ accepts two optional simple_expressions as parameters. The first provides a screen prompt, the second determines the case of the string returned.
Description
$READ provides a mechanism for soliciting input from the user.
The prompt specified is prefixed by "$$" when displayed on the terminal. If the prompt parameter is omitted a null string is used for the prompt. Thus when no prompt is defined, "$$" is displayed on screen. If the result of prompt is not known, the user is not prompted, and a result of INVALID is returned.
The user's response to $READ is returned as a string modified according to the case parameter. If the case parameter is not present, or if it is present and resolves to either UPCASE or a null string, then the response is converted to uppercase before it is returned. If the case parameter resolves to NOCASE the user's response is not converted to uppercase. Any other value for the case parameter causes a result of INVALID to be returned.
Examples
SET $INPUT = $READ SET $INPUT = $READ($PROMPT) SET $INPUT = $READ('ENTER MIXED CASE VAR NAME','NOCASE')
$SOURCE_LINE_DATA
Function
Return data about a line in the source window.
Syntax
$SOURCE_LINE_DATA(desired_data,line_number)
Parameters
$SOURCE_LINE_DATA uses two parameters. Desired_data is a simple_expression that specifies the data to return for the specified line. Line_number is a simple_expression that specifies a line number.
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The data item specified by desired_data is returned for the line specified by line_number.
The desired_data parameter must resolve to one of the following values:
| Value | Meaning |
|---|---|
| BREAK | Returns a value of true if the line is the first line of an executable statement with a break point set on it. Otherwise a value of false is returned. |
| ERROR | Returns a value of true if the line is the first line of an executable statement that has a compilation error associated with it. Otherwise a value of false is returned. |
| ERROR_MSG | Returns a value of true if the line is an error message. Otherwise a value of false is returned. |
| LOOPEND | Returns a value of true if the line is a LOOPEND statement inserted by SoftSpy. Otherwise a value of false is returned. |
| TEXT | Returns the text of the source program line. |
If desired_data resolves to a single keyword other than the keywords listed above a result of UNDEFINED is returned. If it does not resolve to a single keyword then a result of INVALID is returned.
The line_number specified must correspond with a line in the expanded source request listing contained in the SOURCE window. It must be an integer in the range one to $MAX_LINE('SOURCE'), otherwise a result of INVALID is returned.
Examples
SET $TEXT = $SOURCE_LINE_DATA('TEXT',$STMTNUM) IF $SOURCE_LINE_DATA('BREAK',$LINE) THEN JUMP TO CLEAR
$SOURCE_LINE_INFO
Function
Return information that can be displayed in the source window with the SHOW command.
Syntax
$SOURCE_LINE_INFO(desired_information,line_number)
where desired_information resolves to a string of the form:
Parameters
$SOURCE_LINE_INFO takes two required parameters. Desired_information is a simple_expression that specifies the information to return. Line_number is a simple_expression which specifies the line number for which information is desired.
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
This function allows access to information that can be displayed in columns by the SHOW command. Any evaluation time data must already be collected to be accessed by this function.
The desired_information parameter must resolve to a string of the format described above. If a statistic_operand is specified a statistic operand qualifier must not be included.
If the PERCENT or AVERAGE keyword is used three decimal places of precision are returned. Otherwise, no decimal places are returned.
If the HISTOGRAM or BRACKET keyword is used, a string 15 characters long is returned.
The line_number specified must correspond to a line in the expanded source request listing contained in the SOURCE window. It must be an integer in the range from one to $MAX_LINE('SOURCE'), otherwise, a result of INVALID is returned.
If desired_information resolves to a multi-keyword string that is not of the form described above, a result of INVALID is returned. If it resolves to a single keyword that is not a valid operand name, a result of UNDEFINED is returned. NOT AVAILABLE is returned if the information is not being collected. NOT PRESENT is returned when information is not available for a line. Statistic and usage operands only have values available for those lines that are the first line of an executable statement.
Examples
SET $CPU = $SOURCE_LINE_INFO('CPU',$LINE) SET $PCT = $SOURCE_LINE_INFO('PERCENT CPU',$LINE) SET $AVG = $SOURCE_LINE_INFO('AVERAGE CPU',$LINE) SET $NEST = $SOURCE_LINE_INFO('BRACKET NEST',$LINE)
See Also
COLLECT, SHOW
$SPY_MESSAGE
Function
Return the most recent SoftSpy message.
Syntax
$SPY_MESSAGE
Description
The $SPY_MESSAGE function returns the text of the most recently issued message.
$SPY_MESSAGE can be used within a macro to determine if a command executed by the macro was successful. This is done by setting $SPY_MESSAGE to a null string, issuing the command, and then using the IF command to determine if $SPY_MESSAGE is no longer null. $SPY_MESSAGE can also be used as the target operand of the SET command in order to set or alter a message to be displayed at the terminal.
Examples
IF $SPY_MESSAGE NE '' THEN RETURN SET $SPY_MESSAGE = '' SET $SPY_MESSAGE = $UNREACH ' UNREACHABLE STATEMENTS'
See Also
ERROR
$STATUS
Function
Return the value of the Model 204 $STATUS function.
Syntax
$STATUS
Restrictions
The context must be EVAL.
Description
The SoftSpy $STATUS function returns the current value of the Model 204 $STATUS function. This function returns a numeric value indicating the success or failure of the most recently executed external I/O or program communication statement. If the context is not EVAL then a result of NOT AVAILABLE is returned.
Examples
WATCH $STATUS
See Also
$STATUSD
$STATUSD
Function
Return the value of the Model 204 $STATUSD function.
Syntax
$STATUSD
Restrictions
The context must be EVAL.
Description
The SoftSpy $STATUSD function returns the current value of the Model 204 $STATUSD function. Model 204 $STATUSD returns a numeric value indicating the failure or success of the most recently executed external program communication statement.
$STATUSD provides more detailed information than $STATUS. Also, unlike $STATUS, $STATUSD only provides information on program communications statements.
If the context is not EVAL then a result of NOT AVAILABLE is returned.
Examples
DISPLAY $STATUSD
See Also
$STATUS
$SUBSTR
Function
Return a string or substring that is part of another string.
Syntax
$SUBSTR (string,start[, length])
Parameters
$SUBSTR requires two parameters. The first is a simple_expression defining the string from which the substring is drawn. The second is a simple_expression indicating the start position of the new substring. A third optional simple_expression indicates the length of the new substring.
Description
By indicating the starting point and length of a new string, $SUBSTR creates a substring from the string expression you specify.
If the length parameter is omitted, or is greater than the length of the string, $SUBSTR returns a substring comprising the original string from the start position to its end.
If start points to a number greater than the length of the string, a null string is returned.
Values for start must be integers greater than zero. Values for length must be integers greater than or equal to zero. INVALID is returned if start and length do not conform to these restrictions.
Examples
IF $SUBSTR($TEXT,1,1) NE '(' THEN JUMP TO OPERAND_ADD SET $TEXT = $SUBSTR($TEXT,$I) IF $SUBSTR($S,1,1) NE $SUBSTR($S,$N,1) THEN JUMP TO BAD
$SUBSYS
Function
Return the name of the current subsystem.
Syntax
$SUBSYS
Restrictions
The context must be COMPILE_ERROR or EVAL.
Description
The $SUBSYS function returns the name of the current subsystem. A null string is returned if there is no current subsystem.
If the context is not COMPILE_ERROR or EVAL, NOT AVAILABLE is returned.
Examples
IF NOT $INDEX($SKIP_SUBSYSTEMS,$SUBSYS) THEN RETURN PRINT LINE 'SUBSYSTEM ' WITH $SUBSYS
$TEMPITEM
Function
Return the number of CCATEMP pages used by a record set.
Syntax
$TEMPITEM (record_set)
Parameters
Takes a simple expression that identifies a record set whose CCATEMP usage is to be determined.
Restrictions
The context must be EVAL and the interactive performance tuning option is required.
Description
$TEMPITEM is used to monitor CCATEMP usage. It returns the number of CCATEMP pages in use by a record set.
The record_set must resolve to one of three formats:
- If it resolves to a string of the form IN name, then the number of pages used by the found or sort set named is returned.
- If it resolves to a string of the form ON name, then the number of pages used by the named record list is returned.
- If it just resolves to a name, then it is first used as a statement label or number for a found or sort set, and secondly as a list name.
If record_set does not resolve to a syntactically correct result, then a result of INVALID is returned. If the specified record set does not exist, then a result of UNDEFINED is returned. If the context is not EVAL or the interactive performance tuning option is not available, then a result of NOT AVAILABLE is returned.
Examples
DISPLAY $TEMPITEM('FD1') DISPLAY $TEMPITEM('IN FD1') DISPLAY $TEMPITEM('ON LIST1')
See Also
$TEMPTOTAL, usage_operand
$TEMPTOTAL
Function
Return the number of pages of CCATEMP used for a specified purpose.
Syntax
$TEMPTOTAL (usage_class)
Restrictions
The context must be EVAL and the interactive performance tuning option is required.
Parameters
Takes a simple expression that identifies the class of usage of CCATEMP to be determined.
Description
$TEMPTOTAL is used to monitor CCATEMP usage by usage class. The total number of CCATEMP pages in use for the specified class of usage is returned. The allowed values and their meanings are shown in the table below.
| Value | Meaning |
|---|---|
| FIND | Found sets |
| LIST | Record lists |
| LPU | Pending update pool |
| SORT | Sort sets |
| TBOLOG | Transaction backout log |
If one of the allowed values is not specified, then the result is INVALID. If the context is not EVAL or the interactive performance tuning option is not available, then the result is NOT AVAILABLE.
Examples
WATCH $TEMPTOTAL('TBOLOG') DISPLAY $TEMPTOTAL('LPU') DISPLAY $TEMPTOTAL('LIST')
See Also
$TEMPITEM, usage_operand
$UNMATCH
Function
Return the position of the first character within a string that does not match any character in another string.
Syntax
$UNMATCH (string, set)
Parameters
$UNMATCH takes two simple expressions as parameters. The first identifies the string to search. The second specifies the set of characters to match against.
Description
The $UNMATCH function returns the first position within the first string where none of the characters specified in the second string appear. If either string is null, or if every character in the first string is present in the second string, a value of zero is returned.
If the value of either parameter is not known, $UNMATCH returns a result of INVALID.
Examples
IF $UNMATCH($STRING,'0123456789') THEN JUMP TO NON_NUMERIC
$UPDATE
Function
Test for pending updates.
Syntax
$UPDATE
Restrictions
Context must be EVAL.
Description
$UPDATE determines whether there are any Model 204 file updates pending. A value of false is returned if no updates have been made or if any updates have either been committed or backed out. A value of true is returned if updates have been made that have not been committed or backed out.
A result of NOT AVAILABLE is returned if the context is not EVAL.
Examples
GO UNTIL $UPDATE GO UNTIL $UPDATE AND SCREENS(STMT) WATCH $UPDATE
$USERID
Function
Return the user identifier of the current user.
Syntax
$USERID
Description
The $USERID function returns the user identifier for the current user. It is a character string up to ten characters in length.
Examples
SET $MACRO_NAME = $USERID WITH '_PROFILE' PRINT LINE '* REQUESTED BY ' WITH $USERID