TAA Tools
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)
              .
 LOAD:                  /* Load the entries */
              .
             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 */
             GOTO       LOAD
              .
                        /* 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
-------------------------------------------

      TAA9893    The argument was not found or could not be inserted

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
                 additional bytes  may contain  additional information.
                 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


Home Page Up to Top