`LOOKUP2         LOOKUP2                                TAACLTG`
```
The  Lookup 2  command  provides a  search  within a  CL  program in  a
character  variable of 32,000  bytes that is  an array of  equal length
elements.    An  option  allows  the  insertion  into  the  first blank
element.   Another  option  allows  a  shorter length  for  the  lookup
argument  to  enable  additional  information  to  be  stored  in  each
element.  The array must be declared as *CHAR LEN(32000).

Assume  you  have &ARRAY  which has  10 byte  elements.   A  maximum of
3,200 elements could  exist.   You want  to load the  array within  the
same program and  then process it later  on.  Assume you  are accessing
information from a file.

A typical series of commands would be:

DCL       &ARGUMENT *CHAR LEN(10)
DCL       &ARRAY *CHAR LEN(3200)
DCL       &RTNNBR *DEC LEN(5 0)
DCL       &LX *DEC LEN(5 0)
DCL       &NAME *CHAR LEN(10)
.
.
LOOKUP     ARGUMENT(&ARGUMENT) VAR(&ARRAY) +
ELMLEN(10) INSFSTBLK(*YES)
MONMSG     MSGID(TAA9893) EXEC(DO) /* Too many */
/*   Or you may know that the 3,200      */
/*     limit will not be reached         */
ENDDO      /* Too many */
.
/* Process the entries                   */
CHGVAR     &LX - 9
NXTENTRY:   CHGVAR     &LX (&LX + 10)
IF         (&LX *GT 32000) DO /* Too many */
/*   Or you may know that the 3,200      */
/*     limit will not be reached         */
ENDDO      /* Too many */
/* Move element */
CHGVAR     &ARGUMENT %SST(&ARRAY &LX 10)
IF         (&ARGUMENT *NE ' ') DO /* Some entry */
/*                                       */
/*  Process the entry                    */
/*                                       */
GOTO       NXTENTRY
ENDDO      /* Some entry */

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 not  a good  choice as it  may
cause a new added entry to cause a duplicate in the array.

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 such  as if a sort is  used (see the
SORTCLPVAR Tool).

For  example, assume you want to generate  100 random numbers between 1
and 15 and count the occurrences.   The program uses the random  number
(2 bytes) as  the real search argument and additional  information as a
3  digit count field.   You  want to send  messages in sequence  of the
random number.

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

CALL     TAACLTGC11

LOOKUP2 escape messages you can monitor for
-------------------------------------------

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

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

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

If  you specify  INSFSTBLK, the  argument cannot  be a
blank value.

If  you  specify LOOKUPLEN  as  a shorter  length than
ELMLEN,   the   ARGUMENT   may    contain   additional
information  which will  be stored  in the  element if
it  is  to be  inserted.   See  the discussion  in the
tool  documentation  for   'Using  a  shorter   lookup
length'.

VAR           The variable to  be searched.  It must be  an array of
equal length  elements.  It must  be declared as *CHAR
LEN(32000).   The  element  length does  not  have  to
divide evenly into 32,000.

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

LOOKUPLEN     The  length  of the  argument  that  will  be used  to
search  the  array.   The  default is  *ELMLEN  or the
same length  at the ELMLEN  parameter.  If  specified,
it must be less than the ELMLEN value.

Specifying  a shorter  length  allows you  to pass  an
argument  that  is a  data structure  with  the search
value in the  first LOOKUPLEN  number of  bytes.   The
See  the  discussion  in  the  tool documentation  for
'Using a shorter lookup length'.

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  location within  the VAR  array where  the search
was  found.  This  is an optional  return variable and
if used must be specified as *DEC LEN(5 0).

RTNELM        The full  value of the  element where  the search  was
found.   This is  an optional  return variable  and if
used must be specified as *CHAR LEN(100).

The  purpose   of  this  parameter  is  for  use  when
LOOKUPLEN is used.   See  the discussion  in the  tool
documentation for 'Using a shorter lookup length'.

INSFSTBLK     A  *YES/*NO  parameter  for   whether  to  insert  the
argument  into the first  blank position  in the array
if the  argument  does  not  exist  before  the  first
blank position is found.

*NO is the default to not insert.

*YES may be specified to insert the argument.

INSERTED      A  *YES/*NO return  parameter  that describes  whether
the argument  was inserted by  the INSFSTBLK function.

*NO   would  be  returned   if  the  argument  already
exists.  *YES  would be returned  if the argument  was
inserted.

This  is an  optional  return parameter  that if  used
must be specified as *CHAR LEN(4).

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

Because  LOOKUP2 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
------        ----    ---------      ----------    ----------

LOOKUP2       *CMD                   TAACLTG       QATTCMD
TAACLTGC      *PGM       CLP         TAACLTGC      QATTCL
TAACLTGC11    *PGM       CLP         TAACLTGC11    QATTCL
```

Added to TAA Productivity tools January 15, 2009