TAA Tools
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 Up to Top