An OUT parameter

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.

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;