GNU Info

(mysql.info)UDF arguments

---

Next: UDF return values Prev: UDF calling sequences Up: Adding UDF

---

Enter node , (file) or (file)node

Argument Processing
...................

The `args' parameter points to a `UDF_ARGS' structure that thas the
members listed below:

`unsigned int arg_count'
     The number of arguments.  Check this value in the initialization
     function if you want 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'
     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 coercion of the first two arguments to string
     and integer, 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 your function
     was called with.  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.  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).