Accessing Return-Value Information

Enterprise Edition Home | Express Edition Home | Previous Page | Next Page Database Access > Executing User-Defined Routines > Accessing MI_FPARAM Routine-State Information >

Accessing Return-Value Information

The MI_FPARAM structure of a C user-defined function provides the following information about function return values:

Data type information about any return values
Boolean value to indicate whether a return value is NULL

Important:

Because a user-defined function is written in the C language, it can only return a single value. However, this single value can be a structure (such as a row descriptor) that contains multiple values. For information on how to return multiple values, see Returning Multiple Values.

Table 62 lists the DataBlade API accessor functions that obtain and set information about function 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:

Override the expected return type (for type hierarchies)
You can set this return-value data type in the MI_FPARAM structure
Set the actual length, precision, or scale of the return value
Return an SQL NULL value
See Returning a NULL Value.
Check the return value of a UDR that you are going to execute with the Fastpath interface and for which you have created a user-allocated MI_FPARAM structure
See Using a User-Allocated MI_FPARAM Structure.

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:

To indicate that your user-defined function returns a NULL value, use the mi_fp_setreturnisnull( ) function to store the value of MI_TRUE at the appropriate index position in the null-return array of the MI_FPARAM structure.
The mi_fp_returnisnull( ) function accesses the MI_FPARAM structure to determine whether a return value is NULL.

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.