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
