SCNVAR SCAN A VARIABLE TAACLPG |
The SCNVAR command scans a CL variable for a pattern. The function
provides a command interface to the QCLSCAN function provided by the
system. Two commands are provided. SCNVAR allows a variable to be
scanned of up to 999 bytes. SCNVAR2 allows up to 5000 bytes and uses
an RPGLE program to perform the scan.
To scan a 20 byte variable &NAME for the letters ABC, you would
specify:
SCNVAR RESULT(&RESULT) STRING(&NAME) STRLEN(20) +
PATTERN(ABC) PATTERNLEN(3)
IF (&RESULT *GT 0) DO /* Pattern was found */
.
.
If the &RESULT variable is greater than zero, it indicates that the
pattern was found and the first location within the string where it
was found.
Examples
--------
1. SCNVAR RESULT(&RESULT) STRING('Now is the time')
STRINGLEN(15) PATTERN('the')
PATTERNLEN(3) TRIM(*NO)
&RESULT = 8
2. SCNVAR RESULT(&RESULT) STRING('Now is the time')
STRINGLEN(15) PATTERN('the')
PATTERNLEN(4) TRIM(*NO)
&RESULT = 8
Since the both the string and the
pattern have 'the', a match occurs
3. SCNVAR RESULT(&RESULT) STRING('Now is the time')
STRINGLEN(15) PATTERN('the')
PATTERNLEN(5) TRIM(*NO)
&RESULT = 0
Since the string has 'the t..'
a match does not occur
4. DCL &PATTERN *CHAR LEN(100) VALUE('the')
.
SCNVAR RESULT(&RESULT) STRING('Now is the time')
STRINGLEN(15) PATTERN(&PATTERN) +
PATTERNLEN(100) TRIM(*YES)
&RESULT = 8
Since the pattern is trimmed to a
a value of 'the', a match occurs.
If TRIM(*NO) had been used, the
compare would be for 100 bytes and
no match would occur.
Command interface
-----------------
The command interface resembles the parameters that are on the
QCLSCAN program provided by the system. SCNVAR uses QCLSCAN to
perform the scan. SCNVAR2 uses an RPG IV program and runs faster
that QCLSCAN in some situations.
SCNVAR Command parameters *CMD
-------------------------
RESULT The result field to be returned. It must be defined
as LEN(3 0). If the scan is not successful, the
value will be zero. If the scan is successful, the
value will be the first position where the pattern
matches.
STRING The string to be scanned. It must be a character
value of up to 999 bytes.
STRLEN The length of the string to be scanned. It must be
in a range of 1 - 999.
STRPOS The start position in the string to start the scan.
The default is 1.
PATTERN The pattern to be scanned for. It must be a
character value of up to 999 bytes.
If a variable is used for the parameter, you may
want to trim off trailing blanks. See the TRIM
parameter.
PATTERNLEN The length of the pattern variable. It must be in a
range of 1 - 999.
TRANSLATE A *YES/*NO value that defaults to *NO meaning no
translation of the STRING value is performed.
*YES may be specified to translate the STRING
variable to all upper case before performing the
scan. Only the lower case letters ('a' to 'z') are
translated.
TRIM A *YES/*NO value that defaults to *NO meaning the
entire STRING value is scanned.
*YES may be specified when you use a variable for
the PATTERN parameter and want to trim off the
trailing blanks before performing the scan.
WILD The single character that will act as a wild card.
A blank is the default and means that no wild card
character should be used. The wild card may be in
any position in the PATTERN except for position 1.
SCNVAR2 Command parameters *CMD
--------------------------
RESULT The result field to be returned. It must be defined
as LEN(5 0). If the scan is not successful, the
value will be zero. If the scan is successful, the
value will be the first position where the pattern
matches.
STRING The string to be scanned. It must be a character
value of up to 5,000 bytes.
STRLEN The length of the string to be scanned. It must be
in a range of 1 - 5000.
STRPOS The start position in the string to start the scan.
The default is 1.
PATTERN The pattern to be scanned for. It must be a
character value of up to 999 bytes.
If a variable is used for the parameter, you may
want to trim off trailing blanks. See the TRIM
parameter.
PATTERNLEN The length of the pattern variable.
TRANSLATE A *YES/*NO value that defaults to *NO meaning no
translation of the STRING value is performed.
*YES may be specified to to translate the STRING
variable to all upper case before performing the
scan. Only the lower case letters ('a' o 'z') are
translated.
TRIM A *YES/*NO value that defaults to *NO meaning the
entire STRING value is scanned.
*YES may be specified when you use a variable for
the PATTERN parameter and want to trim off the
trailing blanks before performing the scan.
WILD The single character that will act as a wild card.
A blank is the default and means that no wild card
character should be used. The wild card may be in
any position in the PATTERN except for position 1.
RCLACTGRP Whether to reclaim the activation group created.
The default is *YES to reclaim the activation group.
*NO may be specified if you are repeatedly running
the SCNVAR2 command.
*ONLY may be specified to reclaim the activation
group without performing a scan. This is intended
if you have been using *NO for repeated use and then
no longer need the function.
Considerations
--------------
QCLSCAN will return negative values for error conditions such as if
the pattern length is less than 1. These are turned into CPF9898
escape messages with specific text to help identify the problem.
SCNVAR2 emulates the same error conditions.
Restrictions
------------
The TRANSLATE(*YES) function only operates on a-z.
The wild card character may be used in any position of the pattern
except position 1.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ----- --------- ---------- -----------
SCNVAR *CMD TAACLPG QATTCMD
SCNVAR2 *CMD TAACLPG2 QATTCMD
TAACLPGC *PGM CLP TAACLPGC QATTCL
TAACLPGC2 *PGM CLP TAACLPGC2 QATTCL
TAACLPGR2 *PGM RPGLE TAACLPGR2 QATTRPG
|
Added to TAA Productivity tools April 1, 1995
