%KDS (Search Arguments in Data Structure)

%KDS(data-structure-name{:num-keys})

%KDS is allowed as the search argument for any keyed Input/Output operation (CHAIN, DELETE, READE, READPE, SETGT, SETLL) coded in a free-form group. The search argument is specified by the subfields of the data structure name coded as the first argument of the built-in function. The key data structure may be (but is not limited to), an externally described data structure with keyword EXTNAME(…:*KEY) or LIKEREC(…:*KEY)..

Note:

The first argument must be the name of a data structure. This includes any subfield defined with keyword LIKEDS or LIKEREC.
The second argument specifies how many of the subfields to use as the search argument.

It can be a constant, a variable, or an expression.
The individual key values in the compound key are taken from the top level subfields of the data structure. Subfields defined with LIKEDS are considered character data.
Subfields used to form the compound key must not be arrays.
The types of all subfields (up to the number specified by “num-keys”) must match the types of the actual keys. Where lengths, formats and CCSIDs differ, the value is converted.

See *STRICTKEYS for information about the effect Control keyword EXPROPTS(*STRICTKEYS) has on the rules for specifying keys with %KDS.
If the data structure is defined as an array data structure (using keyword DIM), an index must be supplied for the data structure.
Opcode extenders H, M, or R specified on the keyed Input/Output operations code affect the moving of the search argument to the corresponding position in the key build area.

Example:

Figure 1. Example of Search on Keyed Input/Output Operations

A..........T.Name++++++RLen++TDpB......Functions++++++++++++++++++
A          R CUSTR
A            NAME         100A
A            ZIP           10A
A            ADDR         100A
A          K NAME
A          K ZIP
FFilename++IPEASF.....L.....A.Device+.Keywords+++++++++++++++++++++++++
Fcustfile  if   e           k disk    rename(CUSTR:custRec)
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++
D custRecKeys     ds                  likerec(custRec : *key)
D numKeys         s             10i 0
 ...
 /free
         // custRecKeys is a qualified data structure
         custRecKeys.name = customer;
         custRecKeys.zip = zipcode;
         // The *KEY data structure is used as the search argument for CHAIN
         chain %kds(custRecKeys) custRec;
         // The number of keys can be a constant
         chain %kds(custRecKeys : 2) custRec;
         // The number of keys can be a variable or an expression
         numKeys = 1;
         chain %kds(custRecKeys : numKeys) custRec;
         chain %kds(custRecKeys : numKeys + 1) custRec;
 /end-free