Documentation Home
MySQL 5.6 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 31.1Mb
PDF (A4) - 31.1Mb
PDF (RPM) - 30.4Mb
EPUB - 7.8Mb
HTML Download (TGZ) - 7.6Mb
HTML Download (Zip) - 7.6Mb
HTML Download (RPM) - 6.5Mb
Eclipse Doc Plugin (TGZ) - 8.3Mb
Eclipse Doc Plugin (Zip) - 10.1Mb
Man Pages (TGZ) - 182.5Kb
Man Pages (Zip) - 293.9Kb
Info (Gzip) - 2.9Mb
Info (Zip) - 2.9Mb
Excerpts from this Manual

24.4.2.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;
    }
    

    For other UDF_ARGS member values that are arrays, array references are zero-based. That is, refer to array members using index values from 0 to args->arg_count − 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, REAL_RESULT, and DECIMAL_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;
    }
    

    Arguments of type DECIMAL_RESULT are passed as strings, so you should handle them the same way as STRING_RESULT values.

    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;
    

    Exact-value decimal arguments such as 1.3 or DECIMAL column values are passed with a type of DECIMAL_RESULT. However, the values are passed as strings. If you want to receive a number, use the initialization function to specify that the argument should be coerced to a REAL_RESULT value:

    args->arg_type[2] = REAL_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 later for instructions on how to access the value properly.) For a nonconstant 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 nonconstant 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 nonconstant arguments.

    For each invocation of the main function, args->args contains the actual arguments that are passed for the row currently being processed.

    If argument i represents NULL, args->args[i] is a null pointer (0). If the argument is not NULL, functions can refer to it as follows:

    • An argument of type STRING_RESULT is given as a string pointer plus a length, to enable 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]. Do not assume that the string is 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]);
      
    • For an argument of type DECIMAL_RESULT, the value is passed as a string and should be handled like a STRING_RESULT value.

    • ROW_RESULT arguments are not implemented.

  • 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).

  • char *maybe_null

    For the initialization function, the maybe_null array indicates for each argument whether the argument value might be null (0 if no, 1 if yes).

  • char **attributes

    args->attributes communicates information about the names of the UDF arguments. For argument i, the attribute name is available as a string in args->attributes[i] and the attribute length is args->attribute_lengths[i]. Do not assume that the string is null-terminated.

    By default, the name of a UDF argument is the text of the expression used to specify the argument. For UDFs, an argument may also have an optional [AS] alias_name clause, in which case the argument name is alias_name. The attributes value for each argument thus depends on whether an alias was given.

    Suppose that a UDF my_udf() is invoked as follows:

    SELECT my_udf(expr1, expr2 AS alias1, expr3 alias2);
    

    In this case, the attributes and attribute_lengths arrays will have these values:

    args->attributes[0] = "expr1"
    args->attribute_lengths[0] = 5
    
    args->attributes[1] = "alias1"
    args->attribute_lengths[1] = 6
    
    args->attributes[2] = "alias2"
    args->attribute_lengths[2] = 6
    
  • unsigned long *attribute_lengths

    The attribute_lengths array indicates the length of each argument name.


User Comments
  Posted by Ben Christensen on April 15, 2009
Here is the code for the ***_add() function that works for me in an aggregate function to get the correct arguments (ints and strings) for each row.

The documentation above clearly explains how to get an int (long long), but I had to play around for a bit to get a string to be retrieved properly (since I'm not a C programmer and it wasn't obvious and most attempts ended up with corrupted data). Perhaps this code can help another programmer used to Java, C# etc trying to get started with a UDF in C.

The output from this via the fprintf commands will go into the MySQL error log.

NOTE: This code is not ready to go into prod ... it allocates memory (malloc) but does not clean it up.

void
show_row_arguments_add(UDF_INIT* initid, UDF_ARGS* args, char* is_null __attribute__((unused)), char* message __attribute__((unused))) {

fprintf(stderr, "------------------------------------------\n");

int numArgs = args->arg_count;
int i = 0;
while (i < numArgs) {

if (args->args[i]) {

if (args->arg_type[i] == 0) {

unsigned long argLength = args->lengths[i];
char *stringText = args->args[i];

char* myValue = NULL;
myValue = (char *)malloc(argLength);

strncpy(myValue, stringText,argLength);

fprintf(stderr, "args->args[%d] = %s - ", i, myValue);
fprintf(stderr, "STRING_RESULT \n");

}
else if (args->arg_type[i] == 1) {
fprintf(stderr, "args->args[%d] = %d - ", i, args->args[i]);
fprintf(stderr, "REAL_RESULT \n");
}
else if (args->arg_type[i] == 2) {
long long int_val;
int_val = *((long long*) args->args[i]);
fprintf(stderr, "args->args[%d] = %d - ", i, int_val);
fprintf(stderr, "INT_RESULT \n");
}
}
else {
fprintf(stderr, "args->args[%d] = null \n", i);
}
i++;
}

}

---------------------

A simple test with this could use the following table:

CREATE TABLE `test` (
`grp` int(11) DEFAULT NULL,
`a` varchar(50) DEFAULT NULL,
`b` varchar(50) DEFAULT NULL,
`c` int(11) DEFAULT NULL,
`d` int(11) DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8

insert into test values (1, 'HP', null, 1, 1);
insert into test values (1, 'Laser', null, 1, 1);
insert into test values (1, 'Printer', null, 1, 1);
insert into test values (1, null, ' COLOR' , 1, 1);

select show_row_arguments(a, b, c, d) from test group by grp;

You would see the following in the logs:

------------------------------------------
args->args[0] = HP - STRING_RESULT
args->args[1] = null
args->args[2] = 1 - INT_RESULT
args->args[3] = 1 - INT_RESULT
------------------------------------------
args->args[0] = Laser - STRING_RESULT
args->args[1] = null
args->args[2] = 1 - INT_RESULT
args->args[3] = 1 - INT_RESULT
------------------------------------------
args->args[0] = Printer - STRING_RESULT
args->args[1] = null
args->args[2] = 1 - INT_RESULT
args->args[3] = 1 - INT_RESULT
------------------------------------------
args->args[0] = null
args->args[1] = COLOR - STRING_RESULT
args->args[2] = 1 - INT_RESULT
args->args[3] = 1 - INT_RESULT

Sign Up Login You must be logged in to post a comment.