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

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.