nction return values in an MI_FPARAM structure. (Only user-defined functions return values; user-defined procedures do not.)

Table 62. Return-Value Information in the MI_FPARAM Structure
Return-Value Information DataBlade API
Accessor Function
The number of return values for the C UDR with which the MI_FPARAM structure is associated mi_fp_nrets( )
mi_fp_setnrets( )
The type identifier of each return value that the MI_FPARAM structure contains mi_fp_rettype( )
mi_fp_setrettype( )
The length of each return value that the MI_FPARAM structure contains mi_fp_retlen( )
mi_fp_setretlen( )
The precision (total number of digits) of each return value that the MI_FPARAM structure contains mi_fp_retprec( )
mi_fp_setretprec( )
The scale (number of digits to the right of the decimal point) of each fixed-point and floating-point return value that the MI_FPARAM structure contains mi_fp_retscale( )
mi_fp_setretscale( )
Whether each return value that the MI_FPARAM structure contains is NULL mi_fp_returnisnull( )
mi_fp_setreturnisnull( )

Determining the Data Type of UDR Return Values

The database server sets the return-value data type of the user-defined function. Most user-defined functions might need to check the return-value data type but they do not need to set it.

The routine manager uses the return-value information to determine how to bind the return value to a return variable or an SQL value. You need to access return-value information only if your UDR needs to perform one of the following tasks:

If your UDR does not need to perform these tasks, it does not need to modify return-value information in the MI_FPARAM structure.

The MI_FPARAM structure uses several parallel arrays to store the following information about each return value.

Return-Value Array Contents
Return-type array Each element is a pointer to a type identifier (MI_TYPEID) that indicates the data type of the return value.
Return-length array Each element is the integer length of the data type for each return value.
Return-scale array Each element is the integer scale in the fixed-point return value.
Return-precision array Each element is the integer precision of the fixed-point or floating-point return value.
Return-null array Each element has either of the following values:
  • MI_FALSE: The return value is not an SQL NULL value.
  • MI_TRUE: The return value is an SQL NULL value.

For more information, see Returning a NULL Value.

Use the appropriate MI_FPARAM accessor function in Table 62 to access the desired return-value array.

All of the return-value arrays in the MI_FPARAM structure have zero-based indexes. To access information for the nth return value, provide an index value of n-1 to the appropriate accessor function in Table 62. Figure 47 shows how the information at index position 0 of these arrays holds the return-value information for the first (and only) return value of a user-defined function.

Figure 47. Return-Value Arrays in the MI_FPARAM Structure
begin figure description - This figure is described in the surrounding text. - end figure description

The following calls to the mi_fp_rettype( ) and mi_fp_retlen( ) functions obtain the type identifier (ret_type) and length (ret_len) for the first (and only) return value from an MI_FPARAM structure that fparam_ptr identifies: 

MI_FPARAM *fparam_ptr;
MI_TYPEID *ret_type;
mi_integer ret_len;
...
ret_type = mi_fp_rettype(fparam_ptr, 0);
ret_len = mi_fp_retlen(fparam_ptr, 0);

To obtain the number of return values of the user-defined function, use the mi_fp_nrets( ) function. However, the number of return values is always 1 for a C user-defined function. The mi_fp_setnrets( ) function stores the number of return values in the MI_FPARAM structure.

Returning a NULL Value

To return most values from a user-defined function, you use a C return statement. (For more information, see Returning a Value.) To return the SQL NULL value, however, you must access the MI_FPARAM structure of the UDR.

The DataBlade API provides the following functions to support the return of an SQL NULL value from a C user-defined function:

The mi_fp_setreturnisnull( ) function sets an mi_boolean value to indicate whether the return value is NULL. The code in Figure 46 implements the add_one( ) function that uses the mi_fp_setreturnisnull( ) function to return a NULL value when add_one( ) receives a NULL argument.

Warning:
Do not return a NULL-valued pointer from a UDR. If you need to have the UDR return an SQL NULL value, always use mi_fp_setreturnisnull( ). Otherwise, serious memory corruption might occur.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]