The Parse command allows the parsing of an input value into one or
more return variables. A list of separator characters must be
specified (default is 'blank') to determine how the input value
should be parsed. Up to 30 return variables of a maximum length of
200 bytes may be returned. PARSE is not intended to parse an i5/OS
command string.
A typical series of commands would be:
DCL &RTNVAL1 *CHAR LEN(200)
DCL &RTNVAL2 *CHAR LEN(200)
DCL &RTNVAL3 *CHAR LEN(200)
.
PARSE INPVAL(&xxx) RTNVAL1(&RTNVAL1) +
RTNVAL2(&RTNVAL2) RTNVAL3(&RTNVAL3)
The INPVAL value is parsed into 3 possible return variables. The
default separator character of blank is used.
If the INPVAL value was 'ABC DEF GHI', the results would be: RTNVAL1
= 'ABC', RTNVAL2 = 'DEF', RTNVAL3 = 'GHI'.
Examples
--------
Each of the columns represents a parameter on the command.
----- Input parameters ------ ------- Return parameters --------
INPVAL SEP BLANKS RTNCNT RTNVAL1 RTNVAL2 RTNVAL3
------ --- ------ ------ ------- ------- -------
'ABC DEF' ' ' *IGNORE 2 ABC DEF
' ABC DEF' ' ' *IGNORE 2 ABC DEF
' ABC DEF' ' ' *IGNORE 2 ABC DEF
' ABC DE F' ' ' *IGNORE 3 ABC DE F
'ABC,DEF' ',' *IGNORE 2 ABC DEF
'ABC,DEF,' ',' *IGNORE 2 ABC DEF
' ABC,DEF' ',' *IGNORE 2 ABC DEF
',ABC,DEF' ',' *IGNORE 3 ABC DEF
'AB C,D EF' ',' *IGNORE 2 ABC DEF
'ABC,DEF' ',' *KEEP 2 ABC DEF
'ABC,DEF,' ',' *KEEP 2 ABC DEF
' ABC,DEF' ',' *KEEP 2 ABC DEF
',ABC,DEF' ',' *KEEP 3 ABC DEF
' ,ABC,DEF' ',' *KEEP 3 ABC DEF
'AB C,D EF' ',' *KEEP 2 AB C D EF
'AB,C#DEF' ',#' *KEEP 3 AB C DEF
'AB C#DEF' ' #' *IGNORE 3 AB C DEF
'AB C#DEF' ' #' *IGNORE 3 AB C DEF
PARSE escape messages you can monitor for
-----------------------------------------
TAA9891 The INPVAL value may not be all blank.
TAA9892 A parsed value exceeds 200 bytes.
Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
INPVAL The input value to be parsed. The value may be up
to 5000 bytes and may not be all blanks.
BLANKS Whether to ignore blanks when creating the return
variables. *IGNORE is the default meaning any
leading blanks will be ignored as well as any
embedded blanks. Trailing blanks are always ignored
regardless of *IGNORE/*KEEP.
*KEEP may be specified to include blanks in the
return variables. *KEEP is not valid if one of the
separator characters is a blank (X'40').
SEPARATOR A list of up to 10 separator characters to determine
how to parse the input value. The default is blank
(X'40').
A list can be entered such as ',#'. If a blank is
also to be considered as a separator, it must be
either the first character or embedded in the list
such as ', #'. The blank cannot be the last
character.
RTNCNT The number of values that were parsed. This is an
optional return variable that if used must be
specified as *DEC LEN(3 0).
PARSE will not send an error message if the number
of return values exceeds the number of RTNVALn
parameters specified. You should check the count to
see if you have planned for the possible maximum or
if the count exceeds 30 (the maximum number of
possible return variables).
RTNVAL1 The first return value. This is an optional return
variable that if used must be specified as *CHAR
LEN(200).
RTNVAL2 - 30 The other return values. It is not an error to
specify fewer return values than exist. These
return values are optional, but if used must be
specified as *CHAR LEN(200).
Restrictions
------------
** Because return values exist, PARSE may only be used in a CL
program.
** Up to 30 values may be parsed.
** A parsed value may not exceed 200 bytes.
Prerequisites
-------------
The following TAA Tools must be on your system:
RTVVALA Retrieve value attributes
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
------ ---- --------- ---------- ----------
PARSE *CMD TAACLRO QATTCMD
TAACLROC *PGM CLP TAACLROC QATTCL
|
