An OUT parameter

An OUT parameter is a routine argument that is always passed by reference to the C user-defined function.

A C user-defined function can use an OUT parameter to return a value indirectly. For the OUT parameter, the database server allocates storage for an opaque data type or for a data type that you can pass by value (but not for a varying-length data type) and passes a pointer to that storage to the UDR. Multiple OUT parameters are supported and they are allowed anywhere in the argument list, not just at the end.

For a C user-defined function to receive an OUT parameter, it must perform the following actions:

Declare the OUT parameter as a pointer to the appropriate data type
The size of the OUT parameter must be the size of an MI_DATUM structure. The passing mechanism for the parameter must be pass by reference regardless of the data type that you pass back.
Set the argument-value array of the MI_FPARAM structure to NULL.
The UDR will update the argument-value array.

modules often use OUT parameters for Boolean functions to return rank or scoring information (which can indicate how closely the return result matched the query criteria). For example, the following code fragment shows a C UDR, named out_test(), that does not actually search a particular title for a string, but returns a 100 percent relative weight of match success as an OUT parameter.

mi_integer out_test(
   mi_lvarchar *doc,
   mi_lvarchar *query,
   mi_integer *weight,    /* OUT parameter */
   MI_FPARAM *fp)
{
   /* Set the value of the OUT parameter */
   *weight = 100;

   /* Set the value of the OUT parameter to "not null" */
   mi_fp_setargisnull(fp, 2, MI_FALSE);

   return MI_TRUE;
}

In preceding code fragment, the call to the mi_fp_setargisnull() function sets the third argument, which is the OUT parameter, to MI_FALSE, which indicates that the argument does not contain an SQL NULL value. The MI_FPARAM structure stores routine arguments in zero-based arrays. Therefore, the mi_fp_setargisnull() function specifies a position of 2 to access the third argument.

Tip: For more information about how to access the MI_FPARAM structure, see Access MI_FPARAM routine-state information.

When you register the user-defined function, precede the OUT parameter with the OUT keyword. For example, the following CREATE FUNCTION statement registers the out_test() function (which is defined in the preceding code fragment):

CREATE FUNCTION out_test(doc LVARCHAR, 
                  query VARCHAR(120), 
                  OUT weight INTEGER)
   RETURNING BOOLEAN
   EXTERNAL NAME '/usr/udrs/udrs.so'
   LANGUAGE C;