QCLSCAN is an IBM-supplied program that allows you to scan a string to see if it contains a particular pattern. The Scan Variable (SCNVAR) QUSRTOOL command provides a command interface to the QCLSCAN program. The SCNVAR command uses the same parameters as the QCLSCAN program, although not in the same order. The command interface is simpler to use in a CL program because you can prompt it while in SEU. It also supplies default values for several of the parameters which can reduce the number of parameters you must specify.
The RESULT parameter passed back to your program can be used to determine the result of the scan request. The SCNVAR command formats escape message CPF9898 based on the return code. You should monitor for that message and use either the message text or the return code value to determine the nature of the error.
To install the SCNVAR tool, use the CRTTAATOOL tool. If you haven't yet created CRTTAATOOL, information on how to create it can be found in source member CRTTAATOOL in file QUSRTOOL/QATTINFO.
Specify the variable name that is to contain the result of the scan. If the value specified in PATTERN is located in the value specified in STRING, this variable is set to indicate the position within STRING where the first occurrence of PATTERN was found. If PATTERN is not found in STRING, this variable is set to zero. The variable parameter must be defined as a *DEC field with a length of three and zero decimal positions. If any errors occur during the QCLSCAN program, the RESULT parameter will contain a negative number.
Specify the variable name that contains the character string to be scanned, or specify the character string. This parameter must be defined as a *CHAR field and can be up to 999 bytes long.
Specify the length of the argument given in parameter STRING. This parameter must be defined as a *DEC field with a length of three and zero decimal positions. Valid values range from 1 to 999.
Specify the variable name that contains the starting position within the string specified in STRING, or specify the starting position for the scan. This parameter must be defined as a *DEC field with a length of three and zero decimal positions.
1: The scan starts at the first position of the string specified in STRING.
starting-position: Specify the starting position for the scan. Valid values range from 1 to 999.
Specify the variable name that contains the pattern, or specify the character string to be scanned for. This parameter must be defined as a *CHAR field and can be up to 999 bytes long.
Specify the length of the pattern specified in PATTERN. This parameter must be defined as a *DEC field with a length of three and zero decimal positions. Valid values range from 1 to 999.
Even though this parameter is optional, you need to specify a value. If you don't, the command will assume you mean zero and return an error because zero isn't a valid length value.
Specify whether the value specified in STRING is to be translated to all uppercase before the scan is performed.
*NO: The value is not translated.
*YES: The value is translated into uppercase. Only the letters "a" through "z" are translated.
Specify whether trailing blanks are to be trimmed from the variable specified in PATTERN before the scan is performed.
*NO: Trailing blanks are not trimmed.
*YES: Trailing blanks are trimmed.
Specify a single character that is to be used as a wild card when performing the scan. This parameter is used according to the rules for the QCLSCAN program.
SCNVAR RESULT(&RESULT) + STRING(&SRCSTRING) + STRINGLEN(80) STRPOS(7) + PATTERN('CHAIN') PATTERNLEN(5)
This command scans the source string contained within the variable &SRCSTRING for the pattern "CHAIN." The scan starts at position seven and scans for five characters. If the pattern is found in &SRCSTRING, the value of &RESULT is set to the starting position of the pattern; otherwise, &RESULT is set to zero unless an error is encountered.
INFO: SCNVAR (QATTINFO) CDO: TAACLPG (QATTCMD) CPP: TAACLPGC (QATTCL)
The foregoing article was adapted from Midrange Computing's QUSRTOOL Command Reference. The manual contains explanations and syntax diagrams for more than 300 obscure yet useful tools.