keybuild Routine--Build a Key from the Value
The keybuild routine builds an isam, B-tree, or hash key from the value.
This routine constructs a key pair for use by the system. Place the address of this routine in the dtd_keybld_addr field of the IIADD_DT_DFN structure. If the II_DT_NOKEY attribute is present, then this routine is not necessary.
A key pair consists of a high-key/low-key combination whose values represent the largest and smallest values that match the key, respectively. The key pair that results from this routine is based upon the type of key desired.
The DBMS query optimizer uses this operation for building keys for traversing hash, isam, or B-tree tables. Whenever the DBMS Server must look up a value in a table using an ordered index (either hash, isam, or B-tree), it uses that value to form two other values. These two values represent the 'key', that is, the upper and lower limits of the search space. It is not guaranteed that all values in the relation matching the value are between the upper and lower limits produced by keybuild().
Along with the value being keyed on, the caller of keybuild must specify the comparison operator being used (for example, '<'). One of the input parameters for this routine, .adc_opkey, represents the type of operation for which this key is being built. The possible values for this parameter and the operators they represent are:
• II_EQ_OP ('=')
• II_NE_OP ('!=')
• II_LT_OP ('<')
• II_LE_OP ('<=')
• II_GT_OP ('>')
• II_GE_OP ('>=')
Keybuild's main purpose is to build the upper and lower values of the search space. These values are called the high key and low key, respectively. In addition, keybuild returns the type of key that was formed, which tells what type of search must be performed.
The value returned in adc_tykey determines whether or not a key pair is built and, if built, whether the pair is the high or low key. If you are interested only in what type of key is built and not in the actual search space, then set the db_data field (in the II_DATA_VALUE structure pointed to by adc_lokey and/or adc_hikey) to point to a zero address.
The following are the values returned in adc_tykey and their interpretations:
II_KNOMATCH
No values in the table match, so no scan of the table is done. In this case, the low key is set to maximum value for the data type and length of the column being keyed and the high key is set to the minimum.
II_KEXACTKEY
Only a single value from the table matchs. The low and high keys are set to the same value. The execution phase seeks to this point and scans forward until it is sure that it has exhausted all possible matching values.
II_KRANGEKEY
All values in the table that match lay within a range. The low key is set to represent the lowest matching value in the table and the high key is set to represent the highest matching value. The execution phase seeks to the point matching the low key and scans forward until it has exhausted all values that might be less than or equal to the high key.
II_KHIGHKEY
All values in the table that match lie at the low end of the table; they are less than or equal to some value. In this case, the high key is set to that value (the upper bound) and the low key is set to the minimum value for the data type and length of the column being keyed (unbounded). The execution phase starts at the beginning of the table and seeks forward until it has exhausted all values that might be less than or equal to the high key.
II_KLOWKEY
All values in the table that match lie at the high end of the table; they are greater than or equal to some value. In this case, the low key is set to that value (the lower bound) and the high key is set to the maximum value for the data type and length of the column being keyed (unbounded). The execution phase seeks to the point of the low key and scans forward from there.
II_KALLMATCH
All values in the table may match. The low key is set to minimum value for the data type and length of the column being keyed and the high key is set to the maximum value. A full scan of the table must be performed.
The most likely combinations are:
• II_EQ_OP ('=') returns II_KEXACTKEY, low_key == value provided
• II_NE_OP ('!=') returns II_KALLMATCH, no key provided
• II_LT_OP ('<') and II_LE_OP ('<=') return II_KHIGHKEY, with the high_key == value provided
• II_GT_OP ('>') and II_GE_OP ('>=') return II_KLOWKEY, with the low_key == value provided
Although there is fairly strong correlation between the key operator and the type of key built, you cannot use the key operator to predict with certainty the type of key built. For example, assume that you are keying on an i2 column with the '<' operator but the supplied key value is an i4 whose value is 50000. The key that is built is II_KALLMATCH, not II_KHIGHKEY, as might be expected. Do not rely on the key operator to tell you what type of key is built.
Note: The data type of the datavalue in the .adc_kdv may not be same type as the required key resulting from this routine. If it is not, you must supply a coercion to change it to the required data type.
Inputs
The inputs for this function are:
scb
Pointer to SCB
key_block
Pointer to key block data structure:
adc_kdv
Datavalue for which to build a key.
This datavalue does not need to be of the same type as the required key.
adc_opkey
Operator type for which key is being built
adc_lokey
Pointer to area for key. If 0, do not build key.
adc_hikey
Pointer to area for key. If 0, do not build key.
adc_lokey, adc_hikey, and adc_kdv
Point to II_DATA_VALUEs
Outputs
The outputs for this function are:
*key_block
Key block filled with following:
adc_tykey
Type key provided.
adc_lokey
Pointer to area for key. If 0, do not build key. If adc_tykey is II_KEXACTKEY or II_KLOWKEY, this is key built.
adc_hikey
Pointer to area for key. If 0, do not build key. If adc_tykey is II_KEXACTKEY or II_KHIGHKEY, this is the key built.
Returns
II_STATUS