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)
MONMSG MSGID(TAA9893) EXEC(DO) /* Not found */
/* * /
/* Your handling of 'not found' * /
/* * /
ENDDO /* Not found */
/* &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)
MONMSG MSGID(TAA9893) EXEC(DO) /* Not found */
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
------------------------------------------
TAA9893 The argument was not found
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
about the entry. The advantage of this versus an
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.
|
