The Extract List 2 command is designed for those cases where the CL
program is being used as a CPP and a command passes a list. When the
list must be passed to another command which uses the same list or to
a HLL program, the list often needs to be cleaned up before it is
passed. EXTLST2 performs the cleanup.
Assume you have passed a list from a command of 10 byte values with a
maximum of 40 entries. The list is passed to the CPP as 402 bytes.
A typical EXTLST2 use would be:
PGM PARM(&CMDLST)
DCL &CMDLST *CHAR LEN(402)
DCL &RTNLIST *CHAR LEN(6000)
DCL &LIST *CHAR LEN(400)
EXTLST2 LIST(&CMDLST) ELMLEN(10) RTNLIST(&RTNLIST)
CHGVAR &LIST &RTNLIST
The LIST parameter accepts up to 6000 bytes. The RTNLIST parameter
must be specified as 6000 bytes. The CHGVAR command then shortens
the value to 400 bytes. The &LIST variable will contain the values
entered by the user followed by blanks.
The &LIST variable is ready to be passed as a parameter to a HLL
program.
If used as a string for QCMDEXC, you should specify SPACE(*YES).
This causes an extra space between the values. For example, if the
list is 10 character names and a 10 character name is entered, there
would be no space between the 10 character name and the next name in
the list.
Only simple lists are supported (the ELEM statement cannot be used in
the command definition).
Why is EXTLST2 needed
---------------------
When a user enters less than the maximum number of values into a
list, the value that appears in the CPP often has garbage in the
unused positions. For example, if the user entered 3 values into a
list of 10, the values 4-7 may have garbage.
This is why you must process the list knowing how many values were
entered (the binary count in positions 1-2). EXTLST2 gets rid of the
garbage so you can pass on a clean list.
Command parameters *CMD
------------------
LIST The input variable containing the list. Up to 6000
bytes may be specified. The list must be in the
format as passed by a command definition list.
ELMLEN The length of an element in the list. A list of
lists is not supported so the value entered for
ELMLEN must be the value of the LEN parameter in
command definition.
RTNLST A required return variable that will contain a value
that is ready for use as a parameter or in a string
for use by QCMDEXC. The variable must be specified
as *CHAR LEN(6000).
Because of the size of the variable returned, you
will probably want to declare another variable that
is the required length and move the RTNLST variable
to your specific variable.
RTNCNT An optional return variable that will contain the
number of elements in the list. If used, it must be
specified as *DEC LEN(5 0).
SPACE A *YES/*NO value for whether the list should be
returned with a space between the values. *NO is
the default.
*YES should be specified when using QCMDEXC to allow
for the case where a value is passed which is the
full length of the element.
For example, if the list is 10 character names and a
10 character name is entered, there would be no
space between the 10 character name and the next
name in the list. *YES forces a space between the
names.
QUOTE A *YES/*NO value for whether each element should be
returned with surrounding quotes. *NO is the
default.
If *YES is specified, SPACE(*YES) must also be
specified. The intent of QUOTE(*YES) is to allow a
value such as *55 to be passed which may be
interpreted as an expression in a subsequent
command. Using the value '*55' may allow the
subsequent command to be processed correctly.
Restrictions
------------
Because the command returns a variable, the command can only be used
in a CL program.
Lists of lists are not supported (you cannot use the ELEM keyword in
command definition).
Prerequisites
-------------
None.
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
EXTLST2 *CMD TAACLQO QATTCMD
TAACLQOC *PGM CLP TAACLQOC QATTCL
|
