Checking Routine Arguments

The user state of a C UDR provides the following information about routine arguments:

• Data type information about any arguments
• Boolean value to indicate whether an argument is NULL

Table 61 lists the DataBlade API accessor functions that obtain and set information about routine arguments in an MI_FPARAM structure.

Determining the Data Type of UDR Arguments

With the MI_FPARAM structure, you can write UDRs that operate over a type hierarchy, rather than on a single type. At runtime, the routine can examine the MI_FPARAM structure to determine what data types were passed to the current invocation of the routine.

The MI_FPARAM structure stores the information about each UDR argument in several parallel arrays.

Use the appropriate MI_FPARAM accessor function in Table 61 to access the desired argument array.

All the argument arrays in the MI_FPARAM structure have zero-based indexes. To access information for the nth argument, provide an index value of n-1 to the appropriate accessor function, as Table 61 shows. Figure 45 shows how the information at index position 1 of these arrays holds the argument information for the second argument of the UDR.

Figure 45. Argument Arrays in the MI_FPARAM Structure

The following calls to the mi_fp_argtype( ) and mi_fp_arglen( ) functions obtain the type identifier (arg_type) and length (arg_len) for the second argument from an MI_FPARAM structure that fparam_ptr identifies:

mi_integer my_func(arg0, arg1, arg2, fparam_ptr)
   MI_DATUM arg0;
   MI_DATUM arg1;
   MI_DATUM arg2;
   MI_FPARAM *fparam_ptr;
{
   MI_TYPEID *arg_type;
   mi_integer arg_len;
   ...
   arg_type = mi_fp_argtype(fparam_ptr, 1);
   arg_len = mi_fp_arglen(fparam_ptr, 1);

To obtain the number of arguments passed to the UDR (which is also the number of elements in the argument arrays), use the mi_fp_nargs( ) function. For the argument arrays of the MI_FPARAM structure in the preceding code fragment, mi_fp_nargs( ) would return a value of 3. The mi_fp_setnargs( ) function stores the number of routine arguments in the MI_FPARAM structure.

Handling NULL Arguments with MI_FPARAM

By default, C UDRs do not handle SQL NULL values. A UDR is not executed if any of its arguments is NULL; the routine automatically returns a NULL value. If you want your UDR to be invoked when it receives NULL values as arguments, take the following steps:

1. Use the following DataBlade API functions to programmatically handle SQL NULL values within the C UDR:
   • Use the mi_fp_argisnull( ) function to determine whether an argument is NULL.
   • Use the mi_fp_setargisnull( ) function to set an argument to NULL.
2. Register the UDR that checks for and handles NULL values with the HANDLESNULLS routine modifier in the CREATE FUNCTION or CREATE PROCEDURE statement.

   For more information on how to register a UDR, see Registering a C UDR.

The mi_fp_argisnull( ) function obtains an mi_boolean value from an element in the null-argument array of the MI_FPARAM structure. If mi_fp_argisnull( ) returns MI_TRUE, your UDR can take the appropriate action, such as supplying a default value or exiting gracefully from the routine. The code in Figure 46 implements the add_one( ) function that returns a NULL value if the argument is NULL.

mi_integer add_one(i, fParam)
   mi_integer i;
   MI_FPARAM *fParam;
{
   /* determine if the first argument is NULL */
   if ( mi_fp_argisnull(fParam, 0) == MI_TRUE )
      {
      mi_db_error_raise(NULL, MI_MESSAGE, 
         "Addition to a NULL value is undefined.\n");

      /* return an SQL NULL value */
      mi_fp_setreturnisnull(fParam, 0, MI_TRUE);

      /* the argument to this "return" statement is ignored by the
       * database server because the previous call to the 
       * mi_fp_setreturnisnull( ) function has set the return value
       * to NULL
       */
      return 0;
      }
   else
      return(i+1);
}

The following CREATE FUNCTION statement registers a function named add_one( ) in the database:

CREATE FUNCTION add_one(i INTEGER) RETURNS INTEGER
   WITH (HANDLESNULLS)
   EXTERNAL NAME '/usr/lib/db_funcs/add.so(add_one)'
   LANGUAGE C;

This CREATE FUNCTION statement omits the MI_FPARAM parameter of the add_one( ) user-defined function from the definition of the SQL add_one( ) UDR.