Setting up a key list

You can set up a key list in one of the following ways:
  • Specify the number of keys in field SW01NKY of the SW01SR DSECT by using an assembler instruction and then use the DBSETK macro to set up each key. See Using a key list with the DBSETK macro for an example of how to use this method.
    Note: For z/TPFDF multiple LREC buffers, you must use the DBMBUF SETKEY macro.
  • Specify the number of keys by using the df_nbrkeys function and then use the df_setkey function to set up each key. See Using a key list with the df_setkey function for an example of how to use this method.
    Note: For z/TPFDF multiple LREC buffers, you must use the dfmbuf_setkey function.
  • Use assembler instructions to fill in the key list structure, which is defined by the SW01SR DSECT. See Processing using a key list for an example of how to do this.
    Note: This method is provided only for compatibility with older applications; do not use this method for new applications or when updating existing applications.
  • You cannot share key lists between C/C++ applications and assembler applications; that is, you cannot set up a key list in a C/C++ application and activate that key list in an assembler application, or vice versa. If you set up a key list in an assembler application program, you must activate that key list in an assembler application program by specifying the KEYLIST or MODLIST parameter on an assembler macro. If you set up a key list in a C/C++ application program, you must use the dfkey function to activate that key list in a C/C++ application program. See dfkey: Activate a key list for information about the dfkey function.
    Note: For z/TPFDF multiple LREC buffers, you must use the dfmbuf_key function.

The first two bytes of a key list (field SW01NKY) specifies the number of keys in the key list. The maximum value for SW01NKY differs for each type of key list as follows.

Table 1. Key list types
Type of Key List Maximum Number of Keys
Selection key list 180 keys
Multiple LREC buffer key list 6 keys
Default-key key list 1 key
Modification key list 6 keys
Sort/merge key list 180 keys

Field SW01NKY is followed by the keys, each of which is 12 bytes, as follows.

Note: The key list structure has two different formats depending on whether it is used in assembler or C/C++applications. If used in an assembler application, the search address field is a 4-byte field (SW01SEA). If used in a C/C++ application, the search address field is an 8-byte field (SW01SEA8).
Note: For the DBMBUF SETKEY macro, the search address field is always an 8-byte field.
Table 2. Key list structure for assembler applications
Field Number of Bytes Description
SW01DIS 2 bytes Displacement into the LREC
SW01LEN 2 bytes Length of the key
SW01CON 1 byte Condition that must exist for the match to be successful
SW01MSK 1 byte One of the following:
  • 1-byte mask
  • Default key LREC ID used with default-key key lists.
SW01SEA 4 bytes One of the following:
  • Search argument
  • Pointer to prototype LREC used with default-key key lists.
SW01ID1 1 byte Option indicators
SW01ID2 1 byte One of the following:
  • Boolean connector
  • Modification operation used with modification key lists.
Table 3. Key list structure for C/C++ applications
Field Number of Bytes Description
SW01DIS 2 bytes Displacement into the LREC
SW01LEN 2 bytes Length of the key
SW01CON 1 byte Condition that must exist for the match to be successful
SW01MSK 1 byte One of the following:
  • 1-byte mask
  • Default key LREC ID used with default-key key lists.
SW01SEA8 8 bytes One of the following:
  • Search argument
  • Pointer to prototype LREC used with default-key key lists.
SW01ID1 1 byte Option indicators
SW01ID2 1 byte One of the following:
  • Boolean connector
  • Modification operation used with modification key lists
  • X'00', indicating all keys are separated with an AND connector.