VARSCAN – Search a sequential object variable

VARSCAN <object> TARGET(<target1>[, <targetn>)] 
                [ACTION(ITERATIVE|LEAVE|RC)]
                [CASE(Y|N)] 
                [COLS(<from>,<to>)]
                [CURSOR(<rowvar>,<colvar>)]
                [DISTINCT(Y|N,[<separators>])]
                [FILTER(EQ|NE|GT|LT|LE|GE|CO|NC)] 
                [FOUND(<foundvar>)]
                [INSTANCE(<n>|1)]
                [ROWS(CURRENT|FIRST|LAST|<start>,<end>)]
 

<object>

Name of the object to search. You can omit the at sign (@), because this is a known object. The object must be a sequential object, such as one created by the READ command. Complex objects, like those created by LIST or SELECT cannot be read by this command.

ACTION(ITERATE|LEAVE|RC)

Determines the action to take if no match is found:

ITERATE

Continues to the next iteration of the loop. Typically performed in a FILTER loop.

LEAVE

Leaves the current loop. Typically performed in a SCAN loop.

RC

Sets return code 4 if the the FOUND keyword is not specified. This is the default.

CASE(Y|N)

Determines whether the target must be an exact match, including the case. If you specify N, differences in the case are tolerated. For example, Help would match with help. If you specify Y (default), the case must match exactly.

COLS(1|<left>,0|<right>)

Limits the columns across which the search is performed. For example, COLS(20,30) searches from column 20 to 30 included. You can use the value 0 for the right column, which allows searching to the end of the row. If a target starts within the column limits but finishes outside of the limits, it is not considered a match. The default is COLS(1,0).

CURSOR(<rowvar>,<colvar>)

Names a pair of variables within which to store a cursor position. Searching starts from the row named in the row name variable, and the column after the col name variable. This allows subsequent use of the same CURSOR to find the next occurrence of the target. If the named variables do not exist or do not contain whole numbers, they are initialized to the default start position, otherwise the current values is used. If no match is found, the row variable is set to the number of rows +1 and the column variable set to 0. The default cursor starting position is row 1, column 0, meaning that searching starts from row 1, column 1.

You can set the cursor position by setting each variable with the VARSET command (for example, VARSET MYROW=2). If you set the column variable, the search will start from the following column.

If the CURSOR position falls outside the limits of COLS or ROWS, the starting point is adjusted to fit within those limits. If it is already within those limits, the search starts from the CURSOR position.

If CURSOR is not specified, the search starts from the beginning of the object.

DISTINCT(Y|N,[delimiters])

Determines whether the target is found as a character match, or as a distinct word or label. If you select Y, a match occurs only if the preceding and following characters are not alphanumeric. Alternatively, you can specify as delimiters a list of characters, instead of the alphanumeric distinction. If the text is found at position 1, it is considered to have a preceding delimiter. The default is N, meaning that a match occurs by finding the specified set of characters, regardless of whether it is a distinct word. For example, if you set DISTINCT(N), the keyword TARGET(one) will match with gone, bone and one. If you set DISTINCT(Y), the keyword TARGET(one) will match only with one.

FILTER(EQ|NE|GT|LT|LE|GE|CO|NC)

Puts the scan command into FILTER mode. In FILTER mode the command compares only the current cursor row, or the nearest within the row limits, with the comparator specified and each or the targets. The comparison is done with the contents of the row between the column limits. For most comparators, only 1 needs to be matched for the row to be selected, with the exception of NE and NC where all must be true to be successful.

The following comparator values are allowed:

EQ

The column range must match a target string.

NE

The column range must not match all target strings.

GT

The column range must be greater than a target string.

LT

The column range must be less than a target string.

GE

The column range must be greater than or equal to a target string.

LE

The column range must be less than or equal to a target string.

CO

The column range must contain a target string.

NC

The column range must not contain a target string.

FOUND(<foundvar>)

Names a variable to store the number of the TARGET value that is found. If the first TARGET is found, 1 is stored in the named variable; if the second TARGET is found, 2 is stored and so on. If no TARGET is found, 0 is stored.

If you specify FOUND, the VARSCAN command issues a return code of 0 regardless of whether a TARGET is found, checking the FOUND variable be necessary to determine success or failure. If FOUND is not specified, the return code 4 is issued in the event of no match being found and ACTION(RC) being specified.

INSTANCE(<n>|1)

Specifies the instance of a potentially repeating match, for example TARGET(Thunderbird) INSTANCE(4) returns the fourth occurrence of Thunderbird found in the text. If you specify multiple TARGET values, it will count the overall matches regardless of the TARGET. For example, TARGET(Scott,Virgil,Gordon,Alan,John) INSTANCE(4) returns a pointer to Virgil from the string “John, Alan, Gordon, Virgil, Scott”. To find the fourth instance of Virgil, you need to specify VARSCAN with a single TARGET.

ROWS(CURRENT|FIRST|LAST|<n>,[endrow])

Sets the limit of the rows to search. The CURRENT keyword represents the current cursor position, FIRST is the first row of the object and LASTis the last row of the object. Specifying FIRST allows the search to start from row 1 regardless of CURSOR position. Specifying 1 as the starting row will honor the CURSOR position. Specifying CURRENT, FIRST or LAST alone will restrict the search to only that row, while combinations will search a range. For example, ROWS(FIRST,CURRENT) searches from the first row to the current cursor row.

TARGET(<target1>,[targetn])

Specifies the string or strings for which to search. You can specify a list of strings separated by a comma or a single string. For example, TARGET(alpha,beta) searches for either alpha or beta in the object. TARGET(alpha) searches only for alpha.

To search for a target containing commas specify 2 commas, where one is needed in the target. For example, TARGET(alpha,,beta,gamma) searches for “alpha,beta” and “gamma” as two separate target strings.