6. Defining Function Instances : Structure IIADD_FI_DFN
 
Share this page                  
Structure IIADD_FI_DFN
Function instances are defined by filling in the structure IIADD_FI_DFN, once for each instance. IIADD_FI_DFN is included in the header file provided with Object Management Extension. The fields in this structure are as follows:
fid_object_type
Must contain the constant II_O_FUNCTION_INSTANCE.
fid_id
Must contain a valid function instance identifier. This is a 2-byte integer, starting at 16384 (II_FISTART). The DBMS Server uses this number internally to identify the function instance.
fid_cmplmnt
If you have defined fid_type as II_COMPARISON, this field must contain the fid_opid of this function instance's complement. For more information, see  Complementary Function Instances.
fid_opid
Contains the function identifier used to invoke this function instance. The function ID can be a constant identifying a standard SQL operator or the identifier of a new function that was defined using the IIADD_FO_DFN structure.
If the function instance that you are defining is a data type coercion (that is, fid_optype = II_COERCION), this value must match the function ID of the function used to convert to the data type being coerced to. For example, if the function being registered is a coercion from the user-defined data type (UDT) to CHAR then the fid_opid should be II_CHAR_OP, which is the function ID for the CHAR() function.The exception is coercion to II_LONGTEXT type, where the fid_opid should be II_NOOP. For the values associated with the functions for standard Ingres types, refer to $II_SYSTEM/ingres/files/iiadd.h.
For coercions to the UDT itself, an explicit conversion function must be added. The relevant entry in the IIADD_FI_DFN array will be almost the same as the one for the coercion but with the fid_optype field set to II_NORMAL instead of II_COERCION. An entry to IIADD_FO_DFN is also needed (see the "Defining Functions" chapter).
fid_optype
Contains the operation type invoked by the operator. The legal values for this field are:
II_COMPARISON
II_OPERATOR
II_NORMAL
II_COERCION
fid_attributes
Specifies how the function instance behaves.
II_FID_F0_NOFLAGS
II_FID_F4_WORKSPACE
II_FID_F8_INDIRECT
fid_wslength
Specifies the length of the workspace. Valid only if II_FID_F4_WORKSPACE is set.
fid_numargs
Number of arguments for this function. The fid_numargs field is a 4-byte integer. Values in this field are related to the values in the fid_optype field. If fid_optype is II_COMPARISON or II_OPERATION, this value must be 2. If it is II_COERCION, this value must be 1. If fid_optype is II_NORMAL, fid_numargs can be 0, 1, or 2.
fid_args
Pointer to an array of data types, which are the data types of the arguments for the function instance. Each array element is a 2-byte integer. The first element in the array must point to the first argument, the second element to the second argument, and so on. If the function instance has no arguments, set this pointer to 0.
The proprietary Ingres data types, date and money are not currently supported for user manipulation.
The specified argument data types can be user-defined data types or standard SQL data types. To specify a user-defined data type, use the value in the dtd_id field of the IIADD_DT_DFN structure for that data type.
To specify a data type, use one of the following values:
II_INTEGER
II_DECIMAL
II_FLOAT
II_CHAR
II_C
II_VARCHAR
II_TEXT
II_LONGTEXT
fid_result
The data type of the function instance result.
fid_rltype
Set this field to one of the following values to specify the method used to determine the length of the function instance's result. Note that the arguments referred to are the arguments to the routines that perform the operation defined by the function instance. Valid values:
II_RES_FIXED
II_RES_FIRST
II_RES_SECOND
II_RES_LONGER
II_RES_SHORTER
II_RES_KNOWN
II_RES_EXTERN
fid_rlength
Set this field to the length of the function instance's result if the fid_rltype field is II_RES_FIXED. Otherwise, set this field to II_LEN_UNKNOWN (-1).
fid_rprec
Precision of the data value. For most data types, this is not needed and should be set to 0. However, for DECIMAL, the high order byte will represent the value's precision (total number of significant digits), and the low order byte will hold the value's scale (the number of these digits that are to the right of an implied decimal point). Calculate this value and set accordingly.
fid_routine
Address of the routine that performs the function instance.
lenspec_routine
Address of the routine that can be called to compute the result length.