df_setkey: Setting up a key in a key list

Use this group of functions to set up a key list.

You can use the following group of functions to set up a key list:
df_setkey
Use this standard function to set up a key list.
df_setkey_add
Use this function to set up a key list specifically for the dfadd_multi function. You can also use the df_setkey_add function to set up a key list for any other dfadd function. The search argument is generated by using the address of the new LREC and the same displacement (the dsp parameter) as the key field in the LREC.
df_setkey_bool
Use this function to set up a key list where keys must be connected with boolean connectors. Do not use the df_setkey_bool function unless at least one of your keys is connected with DF_OR or DF_ORIF.
df_setkey_dbdef
Use this function to select default add or read keys that are defined in DBDEF.
df_setkey_mod
Use this function to set up a modification key list that determines which LRECs to modify on the dfmod function.

A key list is activated by using the dfkey function (except the modification key list that can only be activated when any of the dfmod_all parameters are specified on the dfmod function). For more information about key lists, see Specifying logical records (LRECs) using keys.

Last updated

  • Changed for PUT14 (information only; no code change).
  • Changed for PUT09.
  • Changed for PUT00.

Format

void df_setkey(dft_kyl *key_list, short int nbr, short int dsp, short int len,
        char con, char *sea, char msk, char org, char typ);
void df_setkey_add(dft_kyl *key_list, short int nbr, short int dsp, short int len, char con,
        char org, char typ);

void df_setkey_bool(dft_kyl *key_list, short int nbr, short int dsp, short int len, char con,
        char *sea, char msk, char org, char typ, char bool);
void df_setkey_dbdef(dft_kyl *key_list, char *sea, char msk);
void df_setkey_mod(dft_kyl *key_list, short int nbr, short int dsp, short int len, char *sea,
        char msk, char oper);
bool
The type of Boolean connector between the current and subsequent Boolean slots. Use one of the following values:
DF_OR
Specifies the OR connector.
DF_AND
Specifies the AND connector.
DF_ORIF
Specifies the ORIF connector.
DF_ANDIF
Specifies the ANDIF connector.
Note: Do not use the df_setkey_bool function when you set up a key to add an LREC to a subfile.
con
The condition that must exist for the match to be successful.

Use one of the following values if you specify the DF_CONST, DF_CHAR, or DF_PACKED value for the typ parameter:

DF_EQ
Specifies the LREC key field is equal to the search argument.
DF_NE
Specifies the LREC key field is not equal to the search argument.
DF_GT
Specifies the LREC key field is greater than the search argument.
DF_LE
Specifies the LREC key field is less than or equal to the search argument.
DF_LT
Specifies the LREC key field is less than the search argument.
DF_GE
Specifies the LREC key field is greater than or equal to the search argument.

Use one of the following values if you specify the DF_MASK value for the typ parameter:

DF_Z
Specifies the result is all zeros.
DF_O
Specifies the result is all ones.
DF_M
Specifies the result is mixed ones and zeros.
DF_NZ
Specifies the result is not all zeros.
DF_NM
Specifies the result is not mixed ones and zeros.
DF_NO
Specifies the result is not all ones.
Note: You can use only the DF_EQ value when you set up a key to add an LREC to a subfile.
dsp
The displacement in bytes of the key field in the LREC. For example, if the LREC is a variable-length LREC and you want to specify the LREC ID as the key field, the value is 2.
Note: If you use the df_setkey function to add an LREC to a subfile, this displacement is used to compare existing LRECs in the subfile with the value that the sea parameter specifies. This displacement is not used to compare the value at the specified displacement in the new LREC.
key_list
A pointer to the key list that will be used to set up the active keys.
len
The length in bytes of the key field in the LREC. For example, if you want to specify the LREC ID as the key field, the value is 1. If you are using a mask field (the DF_MASK value of the typ parameter), len must be 1.
msk
One of the following values based on the function you are using:
  • For the df_setkey, df_setkey_bool, and df_setkey_mod functions, msk is a 1-byte search argument or a 1-byte mask, for example, 0xFF. Set this to zero when you are using the sea parameter.
  • For the df_setkey_dbdef function, msk is the default key LREC ID. For read-only default keys, use X'01'–X'0F'; for read and add operations, use X'10'–X'EF'.
  • Do not use the msk parameter with the df_setkey_add function or when you define a key to add an LREC to a subfile.
nbr
The key number you are setting up. Use a number in the range 1 - 180 for a selection key list or a sort/merge key list. Use a number in the range 1 - 6 for a modification key list. Use 1 for a default-key key list.
oper
Specifies the operation to perform during a global modification of LRECs. The operation is applied to the key fields in the LRECs using the values in the modification key list.

Use one of the following values to indicate the operation to be performed on the LRECs being globally modified:

DF_MVI
Moves the value contained in SW01MSK into the LREC at the displacement specified by SW01DIS.
DF_MVC
Moves the character string whose address is in SW01SEA into the LREC, starting at the displacement specified by SW01DIS for the length contained in SW01LEN.
DF_FILL
Propagates the character contained in SW01MSK into the LREC, starting at the displacement specified by SW01DIS for the length contained in SW01LEN.
DF_OI
Performs an OR-Immediate (OI) operation on the byte in the LREC at the displacement in SW01DIS by using the value specified in SW01MSK.
DF_OC
Performs an OR-Character (OC) operation in the LREC beginning on the byte whose displacement is specified in SW01DIS for a length given in SW01LEN by using the value whose address is given in SW01SEA.
DF_NI
Performs an AND-Immediate (NI) operation on the byte in the LREC at the displacement in SW01DIS by using the value specified in SW01MSK.
DF_NC
Performs an AND-Character (NC) operation in the LREC beginning on the byte whose displacement is specified in SW01DIS for a length given in SW01LEN by using the value whose address is given in SW01SEA.
DF_XI
Performs an Exclusive OR-Immediate (XI) operation on the byte in the LREC at the displacement in SW01DIS by using the value specified in SW01MSK.
DF_XC
Performs an Exclusive OR-Character (XC) operation in the LREC beginning on the byte whose displacement is specified in SW01DIS for a length given in SW01LEN by using the value whose address is given in SW01SEA.
DF_ADD
Adds the fullword value whose address is in SW01SEA to the fullword value in the LREC whose displacement is specified by SW01DIS.
DF_ADD_SHORT
Adds the halfword value whose address is in SW01SEA to the halfword value in the LREC whose displacement is specified by SW01DIS.
DF_SUB
Subtracts the fullword value whose address is in SW01SEA to the fullword value in the LREC whose displacement is specified by SW01DIS.
DF_SUB_SHORT
Subtracts the halfword value whose address is in SW01SEA to the halfword value in the LREC whose displacement is specified by SW01DIS.
DF_COUNT
Increments a fullword counter whose address is in SW01SEA. The application is responsible for initializing the counter before the global modification operation.
DF_COUNT_SHORT
Increments a halfword counter whose address is in SW01SEA. The application is responsible for initializing the counter before the global modification operation.
DF_SUM
Adds the fullword value in the LREC at the displacement specified in SW01DIS to the fullword sum whose address is in SW01SEA. The sum must be initialized before the global modification operation.
DF_SUM_SHORT
Adds the halfword value in the LREC at the displacement specified in SW01DIS to the halfword sum whose address is in SW01SEA. The sum must be initialized before the global modification operation.
DF_MAX
Finds the maximum value of the fullword value in the LREC at the displacement specified by SW01DIS and the current fullword maximum whose address is in SW01SEA. The new maximum value is stored at the address in SW01SEA. The value in SW01SEA does not have to be initialized before the global modification operation.
DF_MAX_SHORT
Finds the maximum value of the halfword value in the LREC at the displacement specified by SW01DIS and the current halfword maximum whose address is in SW01SEA. The new maximum value is stored at the address in SW01SEA. The value in SW01SEA does not have to be initialized before the global modification operation.
DF_MIN
Finds the minimum value of the fullword value in the LREC at the displacement specified by SW01DIS and the current fullword minimum whose address is in SW01SEA. The new minimum value is stored at the address in SW01SEA. The value in SW01SEA does not have to be initialized before the global modification operation.
DF_MIN_SHORT
Finds the minimum value of the halfword value in the LREC at the displacement specified by SW01DIS and the current halfword minimum whose address is in SW01SEA. The new minimum value is stored at the address in SW01SEA. The value in SW01SEA does not have to be initialized before the global modification operation.
org
Specifies the organization of the key fields. Use one of the following values:
DF_DOWNORG
Specifies that the subfile is DOWN organized on this key field.
DF_UPORG
Specifies that the subfile is UP organized on this key field.
DF_NOORG
Specifies that the subfile is not organized on this key field.
Note: Do not use this value when you set up a key to add an LREC to a subfile.
sea
One of the following values based on the function that you are using:
  • For the df_setkey, df_setkey_bool, and df_setkey_mod functions, the sea parameter specifies the address of the search argument. For add operations, the sea parameter specifies the address of the key field value in the new LREC that will be added. Set this parameter to zero when you are using the msk parameter.
  • For the df_setkey_dbdef function, sea is a pointer to the prototype logical record (LREC). The LREC ID contained in the prototype LREC must be in the range of nonread-only default keys (X'10' to X'EF').
typ
The type of search argument you are specifying. Use one of the following values to use the contents of the msk parameter for the search:
DF_CONST
Specifies that the msk parameter contains a 1-byte search argument.
DF_MASK
Specifies that the msk parameter contains a 1-byte mask.

Use one of the following values to use the contents of the string pointed to by the sea parameter for the search:

DF_CHAR
Specifies that the search argument is a variable-length character string.
DF_PACKED
Specifies that the search argument is a variable-length packed decimal string.

Entry requirements

None.

Return conditions

None.

Error return

None.

Programming considerations

  • The type definitions (for example, dft_fil, dft_ref, and dft_kyl) are defined in the c_cdfapi.h header file.
  • If any key is set to DF_NOORG, all subsequent keys must be set to DF_NOORG.
  • If you supply a mask (typ set to DF_MASK), the organization must be DF_NOORG.
  • If you specify a mask, the df_setkey and df_setkey_bool functions perform a bitwise AND (&) operation between the key field in the LREC and the contents of the msk parameter.
  • If you use the df_setkey_bool function for any key in a key list, you must use it for every key in the key list except for the last. Use the df_setkey function for the last key.
  • If you use the df_setkey_add function for any key in a key list, you must use it for every key in the key list.
  • When Boolean operators are specified in a key list, the file is treated as NOORG. That is, it is treated as a file that has no organization even if it has UP or DOWN organization. This may have an impact on the response time of functions that use the key list, such as the dfred, dfdel, and dfmod functions. Furthermore, if the file has a B+Tree index file associated with it, the index file will not be used when retrieving LRECs.
  • The df_setkey_mod function is used to set up the rules for global modifications but does not select the records to which those rules are applied.
  • 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