The Create List command is intended for the case where a CL program
wants to create a variable that can be used to simulate a list passed
from a command. This can be used with the TAA EXTLST function.
The typical use of CRTLST is when:
** A command supports a list parameter and a SNGVAL(*ALL) is
needed.
** The CPP processing code does not support an *ALL function, but
must be done for for each item.
** The *ALL function is for something like all source files in a
library, the libraries on the current *LIBL, the libraries
found from the system value QUSRLIBL.
** You want to use a function such as EXTLST to extract each
item.
CRTLST helps make the CPP processing code the same.
Command definition list parameters
----------------------------------
Command definition allows for a list parameter which appears on a
display such as:
Source file . . . . . . . . . . __________ Name, *ALL
+ for more values __________
The list is specified in command definition source using the MAX
parameter which describes the maximum that can exist such as:
PARM KWD(FILE) TYPE(*NAME) MIN(1) MAX(300) +
SNGVAL(*ALL) +
PROMPT('Source File')
The value is passed to the command processing program (CPP) with the
first two bytes as a binary count of the number that was specified by
the user followed by the entries. For example, if the user entered:
SRCFILE(NAME1 NAME2 NAME3)
the variable would appear as:
XXNAME1 NAME2 NAME3 xxxxxxxxxxxxxxxxxx...
The XX value would be X'0003' meaning 3 values were entered.
When processing a list passed from a command, you must process based
on the count. The reason for this is that there may be extraneous
data for the remainder of the variable that is passed to the program.
You cannot loop on the list values and rely on ending on a blank
value.
The EXTLST TAA Tool is designed to process such a list. The code can
be copied from the EXTLST member in QATTINFO. It looks as follows:
DCL &LIST *CHAR LEN(302)
DCL &FILE *CHAR LEN(10)
DCL &CURNBR *DEC LEN(5 0)
DCL &ELEMENT *CHAR LEN(100)
LOOP: 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 */
Each time thru the loop, an element (up to a max of 100 bytes) is
extracted and then moved to your variable name (in this case &FILE).
You begin the loop with &CURNBR = 0. Each time EXTLST is run, it
returns &CURNBR with the number of the element that has been
extracted. When the list has been exhausted, EXTLST returns with
&CURNBR = 0. This allows a simple approach to say IF CURNBR *GT 0
then a list entry exists and should be processed.
Using CRTLST to simulate the variable needed by EXTLST
------------------------------------------------------
If you have a command prompt such as:
Source file . . . . . . . . . . __________ Name, *ALL
+ for more values __________
Source library . . . . . . . . . __________ Name
and EXTLST is used to process the named source files, what should
your code do if the value is *ALL (specified as a SNGVAL in command
definition)?
A solution is to simulate what the variable looks like before EXTLST
is used.
The TAA RTVLIBSRCF command may be used to determine the source file
names (up to 999) that may exist in a library. RTVLIBSRCF returns a
variable of 10 x 999 = 9999 bytes. If the list parameter for source
files allows a max of 300 files, the variable to receive the list
should be declared as 3002 bytes (2 bytes for the binary count + (10
x 300)). The CRTLST parameter allows input of up to 5000 bytes and
requires a return variable of 5002 bytes.
When simulating the variable to be used with EXTLST, you must use a
different variable than that passed to the program. Because the
space used for the variable is in the command analyzer work area, you
might overlay some additional parameter values.
Thus the code to create the variable for EXTLST would look like:
DCL &LIST1 *CHAR LEN(3002)
DCL &LIST2 *CHAR LEN(3002)
DCL &FILE *CHAR LEN(10)
DCL &CURNBR *DEC LEN(5 0)
DCL &ELEMENT *CHAR LEN(100)
DCL &ELMCNT *DEC LEN(5 0)
DCL &CHAR9999 *CHAR LEN(9999)
DCL &CHAR5002 *CHAR LEN(5002)
DCL &CHAR5000 *CHAR LEN(5000)
.
CHGVAR &LIST2 &LIST1
CHGVAR &FILE %SST(&LIST1 3 10)
IF (&FILE *EQ '*ALL') DO /* All src files */
RTVLIBSRCF LIB(&SRCLIB) SRCFILES(&CHAR9999) +
FILCNT(&ELMCNT)
CHGVAR &CHAR5000 &CHAR9999
CRTLST INPLST(&CHAR5000) ELMCNT(&ELMCNT) +
RTNLST(&CHAR5002)
CHGVAR &LIST2 &CHAR5002
ENDDO /* All src files */
LOOP: EXTLST LIST(&LIST2) ELMLEN(10) ELEMENT(&ELEMENT) +
CURNBR(&CURNBR)
.
The list passed in (&LIST1) is placed in &LIST2 which will be used by
EXTLST if one or more source files were named.
The first element of the list (there must be at least 1) is extracted
from &LIST1. If the first element is *ALL, RTVLIBSRCF is used to
return a list of source files in the library (good practice would be
to check that the number is not greater than the 300 which is the
maximum allowed in &LIST1).
The 9999 byte variable is moved to a 5000 byte variable to allow
input to CRTLST (any variable size from 3000 to 5000 could be used).
CRTLST constructs the return variable from the &ELMCNT value and the
5000 bytes passed in. The return value is 5002 bytes and this is
moved to the &LIST2 variable which is declared as 3002 bytes (same as
the &LIST1 variable passed in).
EXTLST is then used on &LIST2. &LIST2 has the same format regardless
of whether the values were entered on the command or accessed by
RTVLIBSRCF.
CRTLST escape messages you can monitor for
------------------------------------------
None. Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
INPLST The input list. This may be up to 5000 bytes and
contains the list that you want to simulate to look
as if it had been passed by the command analyzer.
ELMCNT The number of elements in the list.
RTNLST The return list that is in the same format as if
passed from the command analyzer. The variable must
be declared as *CHAR LEN(5002).
Restrictions
------------
** Because CRTLST returns a variable, it may only be used in a CL
program.
** Only simple lists are supported (ELEM keywords are not used to
define the list in the command definition source).
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCINF Send escape information
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CRTLST *CMD TAACLRL QATTCMD
TAACLRLC *PGM CLP TAACLRLC QATTCL
|
