TAA Tools
CRTLST          CREATE LIST                            TAAMBRI

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
					

Added to TAA Productivity tools April 15, 2005


Home Page Up to Top