The EXTLST command allows a simple method of dealing with lists
passed from command definition. You specify a simple loop and
receive the elements one at a time.
The following describes two typical uses of the EXTLST command with
different forms of lists:
Simple list
-----------
The ELEM statement is not required in command definition for a simple
list. The MAX parameter on the PARM statement is required. A
typical list would be a list of names or values.
Assume you want a command that passes in up to 50 file names. The
LIST parameter would be entered by the user of your command as:
LIST(FILEA FILEB FILEC)
The command definition for the LIST parameter would be:
PARM KWD(FILE) TYPE(*NAME) LEN(10) MIN(1) MAX(50) +
PROMPT('File name')
Your command processing program could be written in CL and would
appear as follows:
PGM PARM(&LIST)
DCL &LIST *CHAR LEN(502)
DCL &FILE *CHAR LEN(10)
DCL &CURNBR *DEC LEN(5 0)
DCL &ELEMENT *CHAR LEN(100)
.
/********************************************/
/* */
LOOP: /* Extract from list */
/* */
/********************************************/
EXTLST LIST(&LIST) ELMLEN(10) ELEMENT(&ELEMENT) +
CURNBR(&CURNBR)
IF (&CURNBR *GT 0) DO /* Process element */
CHGVAR &FILE %SST(&ELEMENT 1 10)
/* */
/* Your processing of the FILE value */
/* */
GOTO LOOP
ENDDO /* Process element */
The EXTLST command names the list to be extracted, the element
length, the return value for the element and the current number
variable.
Normally, the current number variable is just passed back to the
command for the next element. It should be set to 1 less than the
element desired. When the command completes, it is updated with the
element returned. Therefore, the normal use is to declare a
variable, let the CL compiler initialize the variable to zero and let
the EXTLST command update it.
When there are no more elements to process, the EXTLST command will
return with a value of minus 1. You must end the loop when the value
returned is less than zero. You may reprocess the same list or a
different list by setting the &CURNBR to 0.
The ELEMENT field must be defined as a 100 byte character field. You
then move your value from the ELEMENT field using the CHGVAR command.
Note that the LIST parameter is specified as a length of 502. This
accounts for the 2 byte binary count field which describes the number
of elements in a list and the maximum number of elements (Command
definition MAX parameter) multiplied by the element length. In this
case 502 = 2 + (50 * 10).
Multiple list with fixed length elements
----------------------------------------
The ELEM statement is used in command definition and each sub list
consists of a fixed length containing two or more values. A typical
use would be where each sublist is a name and a type.
Assume you want a command that passes in up to 50 object names and
types. The LIST parameter would be entered by the user of your
command as:
LIST((OBJ1 *PGM)(OBJ2 *FILE)(OBJ3 *MSGQ))
The command definition would be as follows:
PARM KWD(LIST) TYPE(LIST1) MIN(1) MAX(50) +
PROMPT('List of objects and types')
LIST1: ELEM TYPE(*NAME) LEN(10) MIN(1) EXPR(*YES) +
PROMPT('Object name')
ELEM TYPE(*CHAR) LEN(7) RSTD(*YES) VALUES(*FILE +
*PGM *DTAARA *MSGQ) MIN(1) +
PROMPT('Object type')
The complete list of statements would be
PGM PARM(&LIST)
DCL &LIST *CHAR LEN(1052)
DCL &OBJ *CHAR LEN(10)
DCL &TYPE *CHAR LEN(7)
DCL &CURNBR *DEC LEN(5 0)
DCL &ELEMENT *CHAR LEN(100)
LOOP: EXTLST LIST(&LIST) ELMLEN(17) ELEMENT(&ELEMENT) +
CURNBR(&CURNBR) MULTILIST(*YES)
IF (&CURNBR *GT 0) DO /* Process element */
CHGVAR &OBJ %SST(&ELEMENT 1 10)
CHGVAR &TYPE %SST(&ELEMENT 11 7)
/* */
/* Your processing of &OBJ/&TYPE */
/* */
GOTO LOOP
ENDDO /* Process element */
The EXTLST command specifies the MULTILIST(*YES) value to describe
that a list of lists is to be used. The ELMLEN specified (17) is the
length of the two ELEM fields specified in command definition.
There are two CHGVAR commands to substring out the individual
elements:
The LIST parameter is specified as a length of 1052. This is made up
of:
2 Binary count of the number of lists
100 Maximum number of lists (50) multiplied by 2
(These are offset locations)
950 Length of each sub list. This is the maximum
number of lists multiplied by the sum of the
element lengths plus 2 for a binary count
of the elements. 950 = 50 * (10 + 7 + 2)
----
1052
******************************************************
* *
* There is an exception if you have a list *
* that has a minimum of 1. In this case, you *
* should follow the instructions for *
* MULTILIST(*YES), but specify MULTILIST(*NO). *
* The system passes the elements differently *
* when MIN(1) is specified. *
* *
******************************************************
The final code for the multiple list case would look as follows:
PGM PARM(&LIST)
DCL &LIST *CHAR LEN(1052)
DCL &OBJ *CHAR LEN(10)
DCL &TYPE *CHAR LEN(10)
DCL &CURNBR *DEC LEN(5 0)
DCL &ELEMENT *CHAR LEN(100)
LOOP: EXTLST LIST(&LIST) ELMLEN(17) ELEMENT(&ELEMENT) +
CURNBR(&CURNBR) MULTILIST(*YES)
IF (&CURNBR *GT 0) DO /* Process element */
CHGVAR &OBJ %SST(&ELEMENT 1 10)
CHGVAR &TYPE %SST(&ELEMENT 11 7)
/* */
/* Your processing of the OBJ and */
/* and TYPE values. */
/* */
GOTO LOOP
ENDDO /* Process element */
There are other forms of lists of lists that are not supported by
EXTLST. The EXTLST command is designed for the typical list
functions.
In some applications, it is desirable to reprocess the list within
the same CL program. For example, you may want to validate each item
on the list before proceeding with the processing function. This is
easily done by setting the CURNBR value back to zero and then
re-invoking the EXTLST command.
If your list contains a decimal value, it is passed to a CL program
as a packed field within the string of characters. To move the value
to a decimal field in your CL program, consider the use of the TAA
Tool MOVCHRDEC.
Command parameters *CMD
------------------
LIST The list as passed from command definition. A
maximum of 6000 bytes may be specified. Your list
may be less. You may specify a larger value (e.g.
always specify 6000) as long as the list that is
passed by command definition will not exceed 6000.
ELMLEN The element length. For a simple list, this is the
length of a single element. For a list of lists,
this is the sum of the ELEM lengths. It cannot
exceed 100 bytes.
ELEMENT This must be a 100 byte character field which is a
return variable containing the element extracted
from the list. If a multiple list (list of lists)
is used, you must substring out the values.
CURNBR This must be a 5 digit 0 decimal field. It should
be passed as 1 less than the value desired. It will
be returned as the element number to be processed.
If you want to step through the list beginning with
the first element, declare a variable, let the
compiler initialize it to zero and let the EXTLST
command update it.
This field will be set to minus 1 when there are no
more elements to process (or no elements exist).
You must test for this in your program.
A value of zero can be passed to the command, but
will never be returned.
If the value passed to the EXTLST command is
negative or greater than the number of lists,
CPF9898 will be sent as an escape message.
You may reinitialize this field to zero and use the
EXTLST command for multiple lists within the same
program or multiple loops through the same list.
MULTILIST A *YES or *NO value denoting if the list is a list
of lists. *NO is the default meaning only a simple
list exists. Use *YES when you are using the ELEM
command definition statement.
Using EXTLST via a program that unadopts
----------------------------------------
The TAACLPDC2 program is provided to allow the execution of the
EXTLST function via a program that 'unadopts'. This means the
program is created with CHGPGM USEADPAUT(*NO).
The following parameter list exists for TAACLPDC2:
LIST *CHAR 2000
ELMLEN *DEC 5 0
ELEMENT *CHAR 100
CURNBR *DEC 5 0
MULTILIST *CHAR 4
Restrictions
------------
None.
Prerequisites
-------------
None.
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ----- --------- ---------- -----------
EXTLST *CMD TAACLPD QATTCMD
TAACLPDC *PGM CLP TAACLPDC QATTCL
TAACLPDC2 *PGM CLP TAACLPDC2 QATTCL
|
