The Scan and Update Variable command allows a CL variable to be
changed based on an existing pattern within the variable. The
replace value must be the same length as the pattern to be replaced.
The same pattern can be replaced if it occurs multiple times.
The variable to be scanned and updated must be *CHAR LEN(999). You
would typically move the value to be scanned and updated to a work
variable and then move back.
A typical series of commands would be:
DCL &WRKVAR *CHAR LEN(999)
DCL &RPLCOUNT *DEC LEN(3 0)
.
CHGVAR &WRKVAR &VAR1 /* Move from your variable */
SCNUPDVAR UPDVAR(&WRKVAR) PATTERN(ABC) RPLVALUE(DEF) +
RPLCOUNT(&RPLCOUNT)
IF (&RPLCOUNT *EQ 1) DO /* Replaced */
CHGVAR &VAR1 &WRKVAR /* Move back to your var */
ENDDO /* Replaced */
IF (&RPLCOUNT *EQ 0) DO /* Not found */
The variable &WRKVAR would be scanned for the pattern. If found, the
first occurrence would be replaced with the value DEF.
The RPLCOUNT variable is returned with a count of how many times the
pattern was replaced. No escape message occurs if the pattern is not
found. You should specify RPLCOUNT and check the result if required
in your program.
You may optionally replace multiple of identical patterns within the
variable or start the scan at a position other than 1. The length of
the scan is determined by the length of data in UPDVAR parameter or
the ENDPOS value which ever is less. The ENDPOS value defaults to
*END meaning the length of the data in the UPDVAR.
A special function exists with the FRCLEN parameter to allow scanning
for and replacing blanks or Hex 00s.
Command parameters *CMD
------------------
UPDVAR The variable to be scanned and updated. The
variable must be declared as *CHAR LEN(999). The
length of the variable to be scanned is based on the
length of the data within the variable (trailing
blanks are not considered).
PATTERN The pattern to scan for within the UPDVAR variable.
A maximum of 32 bytes is supported. If a variable
is specified, the length of data within the the
variable can be less than the full length of the
variable. The actual length of the pattern is
determined by the length of the data (trailing
blanks are not considered).
For example, assume the UPDVAR has a value of
'ABCDEFGHI ' and the PATTERN has a value of 'DEF
'. The PATTERN is trimmed of trailing blanks, and
'DEF' would be scanned for and found beginning at
location 4 of the UPDVAR value. The trailing blanks
in the UPDVAR value would not be scanned.
RPLVALUE The replace value. A maximum of 32 bytes is
supported. The data within the value must be the
same length as the data length of the PATTERN value
or TAA9892 is sent as an escape message.
For example, if the PATTERN contains DEF, the
RPLVALUE must also be 3 bytes such as XYZ. If the
replace value is less than or greater than 3 bytes
(excluding trailing blanks), the escape message is
sent.
If the RPLVALUE is a variable, the length of the
data within the value (without trailing blanks)
determines the length to compare against the PATTERN
length.
RPLCOUNT The number of times the pattern was replaced. This
is an optional return variable that if specified
must be declared as *DEC LEN(3 0). Note that no
escape message occurs if the pattern is not found.
STRPOS The start position to begin the scan. The default
is 1.
ENDPOS The end position to end the scan. The default is
*END which means the length of the data in the
UPDVAR parameter. If a value is specified, it must
be greater than the STRPOS value.
If the value is ABCDEFGHIJ and a scan occurs for
GHI, it will be found if the ENDPOS is 7 or greater.
MULTSCAN Whether to scan the variable for multiple
occurrences. The default is *NO. If *YES is
specified, every occurrence of the PATTERN found
after the start position will be replaced by the
RPLVALUE.
FRCLEN Whether to force the length of the PATTERN value and
RPLVALUE value. The default is *NO meaning the
length of each is determined by scanning the field
from the right for the first non-blank.
A value from 1 to 32 may be entered to force the
length of both the PATTERN and the RPLVALUE to be
the length specified. The intent of using this
parameter is to allow for the case where a blank
(X'40') must be replaced by a null (X'00') or vice
versa. Because blanks have no length (scan occurs
from the right for the first non-blank), using a
FRCLEN value of 1 describes the length of both
values.
Restrictions
------------
Because the command returns variables, it may only be used in a CL
program.
Because trailing blanks are trimmed off, they cannot be considered to
be part of a valid pattern or replace value.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR Edit variable
RTVVALA Retrieve value attributes
SCNVAR Scan variable
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
SCNUPDVAR *CMD TAACLQU QATTCMD
TAACLQUC *PGM CLP TAACLQUC QATTCL
|
