EXTLST2         EXTRACT LIST 2                         TAACLQO

 The Extract  List 2 command  is designed for  those cases where  the CL
 program is being  used as a CPP and a command passes  a list.  When the
 list  must be passed to another command which  uses the same list or to
 a HLL  program, the  list often needs  to be  cleaned up  before it  is
 passed.  EXTLST2 performs the cleanup.

 Assume you have passed  a list from a command of 10  byte values with a
 maximum  of 40 entries.   The list is  passed to the  CPP as 402 bytes.
 A typical EXTLST2 use would be:

             PGM            PARM(&CMDLST)
             DCL            &CMDLST *CHAR LEN(402)
             DCL            &RTNLIST *CHAR LEN(6000)
             DCL            &LIST *CHAR LEN(400)

             EXTLST2        LIST(&CMDLST) ELMLEN(10) RTNLIST(&RTNLIST)
             CHGVAR         &LIST &RTNLIST

 The LIST parameter  accepts up to  6000 bytes.   The RTNLIST  parameter
 must be  specified as  6000 bytes.   The  CHGVAR command then  shortens
 the  value to 400  bytes.  The  &LIST variable will  contain the values
 entered by the user followed by blanks.

 The &LIST  variable is  ready to  be passed  as a  parameter to  a  HLL
 program.

 If  used as  a  string for  QCMDEXC,  you should  specify  SPACE(*YES).
 This causes  an extra space  between the values.   For example,  if the
 list  is 10 character names  and a 10 character  name is entered, there
 would be no space  between the 10 character  name and the next  name in
 the list.

 Only simple lists  are supported (the ELEM statement  cannot be used in
 the command definition).

 Why is EXTLST2 needed
 ---------------------

 When  a user  enters  less than  the maximum  number  of values  into a
 list, the  value that  appears  in the  CPP often  has garbage  in  the
 unused positions.   For example,  if the user  entered 3 values  into a
 list of 10, the values 4-7 may have garbage.

 This  is why  you must process  the list  knowing how many  values were
 entered (the binary count in positions  1-2).  EXTLST2 gets rid of  the
 garbage so you can pass on a clean list.

 Command parameters                                    *CMD
 ------------------

    LIST          The input  variable containing the  list.  Up  to 6000
                  bytes  may be  specified.   The  list must  be  in the
                  format as passed by a command definition list.

    ELMLEN        The  length  of an  element in  the list.   A  list of
                  lists  is not  supported  so  the  value  entered  for
                  ELMLEN  must be  the  value of  the  LEN parameter  in
                  command definition.

    RTNLST        A  required return variable that  will contain a value
                  that is ready for  use as a  parameter or in a  string
                  for use  by QCMDEXC.   The variable must  be specified
                  as *CHAR LEN(6000).

                  Because  of  the size  of the  variable  returned, you
                  will probably want  to declare  another variable  that
                  is the  required length and  move the  RTNLST variable
                  to your specific variable.

    RTNCNT        An  optional  return variable  that  will contain  the
                  number  of elements in the list.   If used, it must be
                  specified as *DEC LEN(5 0).

    SPACE         A  *YES/*NO  value for  whether  the  list  should  be
                  returned  with a  space between  the values.    *NO is
                  the default.

                  *YES  should be specified when  using QCMDEXC to allow
                  for the  case where  a value  is passed  which is  the
                  full length of the element.

                  For example, if  the list is 10 character  names and a
                  10  character  name  is  entered,  there  would be  no
                  space between  the  10  character name  and  the  next
                  name in  the list.   *YES forces  a space between  the
                  names.

    QUOTE         A  *YES/*NO value for  whether each element  should be
                  returned   with  surrounding  quotes.     *NO  is  the
                  default.

                  If  *YES  is  specified,  SPACE(*YES)  must   also  be
                  specified.   The intent of  QUOTE(*YES) is to  allow a
                  value   such  as  *55  to  be   passed  which  may  be
                  interpreted  as   an   expression  in   a   subsequent
                  command.    Using  the   value  '*55'  may  allow  the
                  subsequent command to be processed correctly.

 Restrictions
 ------------

 Because  the command returns a  variable, the command can  only be used
 in a CL program.

 Lists of lists are  not supported (you cannot  use the ELEM keyword  in
 command definition).

 Prerequisites
 -------------

 None.

 Implementation
 --------------

 None, the tool is ready to use.

 Objects used by the tool
 ------------------------

    Object        Type    Attribute      Src member    Src file
    ------        ----    ---------      ----------    ----------

    EXTLST2       *CMD                   TAACLQO       QATTCMD
    TAACLQOC      *PGM       CLP         TAACLQOC      QATTCL

Added to TAA Productivity Tools September 1, 1996


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.