`LOOKUP          Lookup on a CL Variable                TAACLTF`
```
The  Lookup  command  provides  a search  within  a  CL  program  in  a
character  variable that  is an array  of equal  length elements.   The
variable  must be  declared as  *CHAR LEN(32000).   An  alternate array
may  be specified  and  the  corresponding  element  returned  after  a
successful  lookup.    The   alternate  array  variable  must  also  be
declared as *CHAR LEN(32000).

It  is critical that both arrays be  declared as *CHAR LEN(32000).  The
CL compiler  has  a  maximum input  length  for a  parameter  of  5,000
bytes,  but  a return  variable  may  be  up  to 32,767.    Both  array
parameters  are specified as  RTNVAL(*YES) to allow  the larger length.
The arrays  are  passed  in  by your  program,  but  neither  array  is
updated by the command.

Assume  you  have &ARRAY1  which  is  24  bytes  in length  and  has  8
elements of  3 bytes each.   You have  a second array  of corresponding
15  byte names.   You have an  input value to  lookup against the first
array and  want a  return of the  corresponding element  in the  second
array.

A typical series of commands would be:

DCL       &ARGUMENT *CHAR LEN(3)
DCL       &VAR *CHAR LEN(32000)
DCL       &ALTVAR *CHAR LEN(32000)
DCL       &VARLEN *DEC LEN(5 0)
DCL       &ALTVARELM *CHAR LEN(100)
.
LOOKUP    ARGUMENT(&ARGUMENT) VAR(&VAR) +
ELMLEN(3) +
ALTVAR(&ALTVAR) ALTELMLEN(15) +
ALTRTNELM(&ALTRTNELM)
/*                                   * /
/*                                   * /
/* &ALTRTNELM has the corresponding value */

You can just  use the search argument to confirm  that the value exists
such as:

LOOKUP    ARGUMENT(&ARGUMENT) VAR(&ARRAY1) +
ELMLEN(3)

Optional  return values  include the  number of  the element  found and
the location in each array where the value was found.

Using EXTLST2
-------------

Another solution for loading an array  is when you have a command  with
a list input to your  program such as a list of names  that you want in
an  array.   The  EXTLST2  command  strips off  the  leading  bytes and
leaves blanks at the end of the return variable.

Assume you list  has a maximum of  300 to character  names.  Your  code
would look like:

DCL        &LIST *CHAR LEN(3002)
DCL        &RTNLIST *CHAR LEN(6000)
DCL        &ARRAY *CHAR LEN(32000)
.
EXTLST2    LIST(&LIST) ELMLEN(10) RTNLIST(&RTNLIST)
CHGVAR     &ARRAY &RTNLIST

Removing an entry
-----------------

If you  want to remove  an entry,  a typical solution  would be to  set
the  value  to something  like  '%%%'  or some  value  that will  never
appear in your data.  Using blanks is generally not a good choice.

Using a shorter lookup length
-----------------------------

The  LOOKUPLEN parameter defaults to ELMLEN  meaning the same length is
used for  the lookup  as  the length  of each  element.   Specifying  a
shorter  length allows additional  information to  be placed  after the
search  value  and  is  carried  along  if  a  sort  is  used (see  the
SORTCLPVAR Tool).

For example, assume you want to  count the number of object types  that
exist in a library  and then present the results  in sequence by object
type.

A  sample program for  this exists in  TAACLTFC11 to analyzed  the QGPL
library.

CALL     TAACLTFC11

LOOKUP escape messages you can monitor for
------------------------------------------

Escape messages from based on functions will be re-sent.

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

ARGUMENT      The argument  to search  for.   It can  be up  to  100
bytes in length.

VAR           The variable to be  searched.  It must be  an array of
equal  length elements and  must be declared  as *CHAR
LEN(32000).    The command  parameter is  described as
RTNVAL(*YES) which  allows  a larger  than 5,000  byte
parameter to  be declared.   The array is  not changed
within the program.

The  length of each  element as defined  by the ELMLEN
parameter does not have  to divide into 32000  evenly.

ELMLEN        The length of  each element within the  VAR parameter.
It must be a value between 1 and 100.

LOOKUPLEN     The  length of  of the  argument  to be  searched for.
The default  is *ELMLEN  meaning  the same  length  as
specified for the  ELMLEN parameter.  If  specified it
must be  a number between  1 and 100 and  must be less
than the ELMLEN value.

Allowing  a  shorter  lookup  length  allows  an array
where  the  leading   bytes  are   the  key  and   the
remaining  bytes  can provide  additional  information
alternate array is that the  array can be sorted  (see
the SORTCLPVAR  Tool) and  the additional  information
is  carried  along  with the  sorted  result.   If  an
alternate array  is  used, the  corresponding  element
locations are  no longer  consistent after  a sort  of
the primary array.

See the discussion with the tool documentation.

ENDBLKVAL     A  *NO/*YES parameter  for whether  to end  the search
if a blank value is found in the VAR value.

*NO  is  the default  meaning  all values  in  the VAR
value are searched.

*YES may  be specified to  end the  search if a  blank
value is  found as  the next entry  to be  compared in
the  VAR value.  TAA9893 is  sent as an escape message
if a blank is found.

RTNNBR        The  number  of  the  element  where  the  search  was
found.   This is  an optional  return variable and  if
used must be specified as *DEC LEN(5 0).

RTNLOC        The  return location  within the  VAR array  where the
argument was  found.    This  is  an  optional  return
variable and if  used must be specified as  *DEC LEN(5
0).

ALTVAR        The  alternate  array.   This  is  an optional  return
variable  that  if  used  must  be  declared  as *CHAR
LEN(32000).   It  must be  an  array of  equal  length
elements.    The  command  parameter is  described  as
RTNVAL(*YES)  which allows  a  larger than  5,000 byte
parameter to be  declared.  The  array is not  changed
within the program.

The  length  of   each  element  as  defined   by  the
ALTELMLEN  parameter  does  not  have  to divide  into
32000 evenly.

ALTELMLEN     The  length  of   each  element   within  the   ALTVAR
parameter.     If  an   ALTVAR  array  is   specified,
ALTELMLEN  must  be  specified  and  must be  a  value
between 1 and 100.

ALTRTNELM     If  an  ALTVAR is  used,  an alternate  return element
may  be   specified  to   contain  the   corresponding
element  of where the  argument was  found in  the ALT
array.   This is an optional  return variable, that if
used must be specified as *CHAR LEN(100).

ALTRTNLOC     If  an  ALTVAR  is  specified,  an  alternate   return
location   may    be   specified   to    contain   the
corresponding  location in the ALTVAR  array where the
argument was  found in  the  ALT array.   This  is  an
optional  return  variable,  that  if   used  must  be
specified as *DEC LEN(5 0).

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

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

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

The following TAA Tools must be on your system:

SNDESCINF       Send escape information
SNDESCMSG       Send escape message

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

None, the tool is ready to use.

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

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

LOOKUP        *CMD                   TAACLTF       QATTCMD
TAACLTFC      *PGM       CLP         TAACLTFC      QATTCL
TAACLTFC11    *PGM       CLP         TAACLTFC11    QATTCL

TAACLTFC11 is a sample program.
```

Added to TAA Productivity tools January 15, 2009