dfkey: Activate a key list

Use this function to activate a key list by generating key instructions and storing them in the SW00SR for the specified file to be used by subsequent functions that access the specified file. For more information about keys, see Specifying logical records (LRECs) using keys.

Last updated

  • Changed for PUT10.
  • Changed for PUT00.

Format

void dfkey(dft_fil *file, dft_kyl *key_list)
void dfkey_nbr(dft_fil *file, dft_kyl *key_list, short int n)
void dfkey_save(dft_fil *file, dft_kyl *key_list)
void dfkey_nbr_save(dft_fil *file, dft_kyl *key_list, short int n)
file
A pointer to the base address of the SW00SR slot (defined in c_sw00sr.h) of the file that you want to access and is returned by the dfifb or dfopn function. Use the acc parameter to specify a particular subfile to access. If you do not specify the acc parameter, the last subfile accessed with this SW00SR slot will be accessed.
key_list
is a pointer to the key list (SW01SR).
n
is the number of keys (1–180) that you have set up in the key list.

Entry requirements

None.

Return conditions

None.

Error return

For information about how to check the error indicators, see Identifying return indicators and errors.

Programming considerations

  • The type definitions (for example, dft_fil, dft_ref, and dft_kyl) are defined in the c_cdfapi.h header file.
  • The sea field (search field address) in the key list structure (SW01SR), which is referenced by the key_list parameter, can affect performance if passed above the 2 GB bar.
  • All dfkey functions generate the key instructions that are stored in the SW00SR for the specified file. The key list itself is no longer used by subsequent functions that access the file.
  • The dfkey_save and dfkey_nbr_save functions activate the key list and additionally save the contents of the sea field (search field address) in this SW00SR slot. This allows you to release the storage location of the search arguments, but also prevents you from changing the search argument without calling a subsequent dfkey function.
  • To avoid the possibility of corrupting the organization of a subfile, do not use keys (set up with a dfkey function) when adding LRECs to a file. Instead, have the database administrator set up keys in the database definition (DBDEF) that defines the file. These are called default keys and override any keys you set up with the dfkey function. For more information about defining default keys, see z/TPFDF Database Administration.
  • You can define any number of key list structures in your program. Each key list can have from 1–180 keys. For more information about key lists, see Specifying logical records (LRECs) using keys.

Examples

For examples of how to set up a key list, see Setting up a key list with less than six keys and Setting up a key list in the range 1-180.

Related information

See the following functions for more information: