TAA Tools
EXTLST        EXTRACT AN ELEMENT FROM A LIST         TAACLPD

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
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top