(mysql.info) udf-arguments

Info Catalog

(mysql.info) udf-aggr-calling

(mysql.info) adding-udf

(mysql.info) udf-return-values

 
 24.2.4.3 UDF Argument Processing
 ................................
 
 The `args' parameter points to a `UDF_ARGS' structure that has the
 members listed here:
 
    * `unsigned int arg_count'
 
      The number of arguments. Check this value in the initialization
      function if you require your function to be called with a
      particular number of arguments. For example:
 
           if (args->arg_count != 2)
           {
               strcpy(message,"XXX() requires two arguments");
               return 1;
           }
 
    * `enum Item_result *arg_type'
 
      A pointer to an array containing the types for each argument. The
      possible type values are `STRING_RESULT', `INT_RESULT', and
      `REAL_RESULT'.
 
      To make sure that arguments are of a given type and return an
      error if they are not, check the `arg_type' array in the
      initialization function. For example:
 
           if (args->arg_type[0] != STRING_RESULT ||
               args->arg_type[1] != INT_RESULT)
           {
               strcpy(message,"XXX() requires a string and an integer");
               return 1;
           }
 
      As an alternative to requiring your function's arguments to be of
      particular types, you can use the initialization function to set
      the `arg_type' elements to the types you want. This causes MySQL
      to coerce arguments to those types for each call to `xxx()'. For
      example, to specify that the first two arguments should be coerced
      to string and integer, respectively, do this in `xxx_init()':
 
           args->arg_type[0] = STRING_RESULT;
           args->arg_type[1] = INT_RESULT;
 
    * `char **args'
 
      `args->args' communicates information to the initialization
      function about the general nature of the arguments passed to your
      function. For a constant argument `i', `args->args[i]' points to
      the argument value. (See below for instructions on how to access
      the value properly.) For a non-constant argument, `args->args[i]'
      is `0'. A constant argument is an expression that uses only
      constants, such as `3' or `4*7-2' or `SIN(3.14)'.  A non-constant
      argument is an expression that refers to values that may change
      from row to row, such as column names or functions that are called
      with non-constant arguments.
 
      For each invocation of the main function, `args->args' contains
      the actual arguments that are passed for the row currently being
      processed.
 
      Functions can refer to an argument `i' as follows:
 
         * An argument of type `STRING_RESULT' is given as a string
           pointer plus a length, to allow handling of binary data or
           data of arbitrary length.  The string contents are available
           as `args->args[i]' and the string length is
           `args->lengths[i]'. You should not assume that strings are
           null-terminated.
 
         * For an argument of type `INT_RESULT', you must cast
           `args->args[i]' to a `long long' value:
 
                long long int_val;
                int_val = *((long long*) args->args[i]);
 
         * For an argument of type `REAL_RESULT', you must cast
           `args->args[i]' to a `double' value:
 
                double    real_val;
                real_val = *((double*) args->args[i]);
 
    * `unsigned long *lengths'
 
      For the initialization function, the `lengths' array indicates the
      maximum string length for each argument. You should not change
      these. For each invocation of the main function, `lengths'
      contains the actual lengths of any string arguments that are
      passed for the row currently being processed. For arguments of
      types `INT_RESULT' or `REAL_RESULT', `lengths' still contains the
      maximum length of the argument (as for the initialization
      function).
 

Info Catalog

(mysql.info) udf-aggr-calling

(mysql.info) adding-udf

(mysql.info) udf-return-values