bdfp1m1m | Programming Concepts and Reference |
Use this group of functions to set up a key list. See Specifying Logical Records (LRECs) Using Keys for more information about key lists.
A key list is activated using the dfkey function.
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_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
- is 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.
- con
- is 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.
- dsp
- is 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.
- key_list
- is a pointer to the key list that will be used to set up the active
keys.
- len
- is 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 (value DF_MASK of the typ parameter),
len must be 1.
- msk
- is one of the following base 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'.
- nbr
- is the key number you are setting up. Use a number from 1-180
for a selection key list or a sort/merge key list. Use a number from
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.
- sea
- is one of the following based on the function you are using:
- For the df_setkey, df_setkey_bool, and
df_setkey_mod function, sea is the address of the
search argument. Set this 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
- is 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.
Normal Return
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.
- 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. See Specifying Logical Records (LRECs) Using Keys for more information about key lists.
Examples
Related Functions