SoftSpy functions

From m204wiki
Revision as of 20:48, 15 April 2015 by ELowell (talk | contribs) (→‎$SOURCE_LINE_INFO)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

$ACTIVE_WINDOW

Return the name of the active window.

$COMMAND

Return the value contained on the SoftSpy command line.

$CONTEXT

Return the SoftSpy context.

$COUNT_LINES

Return a count of the number of lines in the source window that meet a specified condition.

$COUNT_RECORDS

Return a count of the number of records in a record set.

$CURRENT_LINE

Specify the current line number in a window.

$CURSOR_HYPERTEXT

Return the name of the help topic on which the cursor is positioned.

$CURSOR_LINE

Return the line number on which the cursor is positioned in a window.

$DEFAULT_JUMP_LIMIT

Specify the default limit on the number of JUMP TO statements that can be executed in a macro.

$DEFAULT_WATCH_WINDOW

Return the default window name for WATCH and UNWATCH commands.

$ERRMSG

Return the last counting error message or request cancellation message.

$INDEX

Return the position of one string in another string.

$INTERRUPT_TYPE

Return the type of interrupt that suspended request evaluation.

$JUMP_LIMIT

Specify a limit on the number of JUMP TO statements that can be executed in the current macro.

$LEN

Return the length of a string.

$LOCATE_LINE

Return the line number of a line in the source window that meets a specified condition.

$MACRO_ARGS

Return the argument string passed to the current macro.

$MACRO_EXISTS

Test for the existence of a macro.

$MATCH

Return the position of the first character in a string that matches any character in another string.

$MAX_LINE

Return the number of lines in a window.

$MUSE_DEFAULT_HANDLE

Return the name of the default MUSE handle.

$OPTION

Test if an optional SoftSpy feature is available.

$PAD

Pad a string to a specified length.

$PROCFILE

Return the name of the file containing the procedure containing the current User Language request.

$PROCNAME

Return the name of the procedure containing current User Language request.

$READ

Prompt the user for input and return the response.

$SOURCE_LINE_DATA

Return data about a line in the source window.

$SOURCE_LINE_INFO

Return information that can be displayed in the source window with the SHOW command.

$SPY_MESSAGE

Return the most recent SoftSpy message.

$STATUS

Return the value of the Model 204 $STATUS function.

$STATUSD

Return the value of the Model 204 $STATUSD function.

$SUBSTR

Return a string, or substring that is part of another string.

$SUBSYS

Return the name of the current subsystem.

$TEMPITEM

Return the number of CCATEMP pages used by a record set

$TEMPTOTAL

Return the number of pages of CCATEMP used for a specified purpose

$UNMATCH

Return the position of the first character in a string that does not match any character in another string.

$UPDATE

Test for pending updates.

$USERID

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