Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html
ChangeSet
1.2642 05/03/05 20:53:05 paul@stripped +1 -0
manual.texi:
More UDF general revision.
Docs/manual.texi
1.2461 05/03/05 20:52:39 paul@stripped +128 -75
More UDF general revision.
# This is a BitKeeper patch. What follows are the unified diffs for the
# set of deltas contained in the patch. The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: paul
# Host: frost.snake.net
# Root: /Volumes/frost2/MySQL/bk/mysqldoc
--- 1.2460/Docs/manual.texi 2005-03-05 13:47:27 -06:00
+++ 1.2461/Docs/manual.texi 2005-03-05 20:52:39 -06:00
@@ -10837,7 +10837,8 @@
@strong{Incompatible change:}
The interface to aggregate user-defined functions has changed a bit as of MySQL
4.1.1. You must declare a @code{xxx_clear()} function for each aggregate
-function @code{XXX()}.
+function @code{XXX()}. @code{xxx_clear()} is used instead of
+@code{xxx_reset()}.
@xref{UDF aggr. calling}.
@end itemize
@@ -91749,14 +91750,14 @@
@itemize @bullet
@item
-You can add the function through the user-defined function (UDF) interface.
+You can add functions through the user-defined function (UDF) interface.
User-defined functions are compiled as object files and then added to and
removed from the server dynamically using the @code{CREATE FUNCTION} and
@code{DROP FUNCTION} statements.
@xref{CREATE FUNCTION, , @code{CREATE FUNCTION}}.
@item
-You can add the function as a native (built in) MySQL function. Native
+You can add functions as native (built-in) MySQL functions. Native
functions are compiled into the @command{mysqld} server and become available
on a permanent basis.
@end itemize
@@ -91765,8 +91766,8 @@
@itemize @bullet
@item
-If you write a user-defined function, you must install the object file
-in addition to the server itself. If you compile your function into the
+If you write user-defined functions, you must install object files in
+addition to the server itself. If you compile your function into the
server, you don't need to do that.
@item
You can add UDFs to a binary MySQL distribution. Native functions
@@ -91774,26 +91775,71 @@
@item
If you upgrade your MySQL distribution, you can continue to use your
previously installed UDFs, unless you upgrade to a newer version for which
-the UDF interface changes. For native functions, you must repeat your
+the UDF interface changes. (An incompatible change occurred in MySQL 4.1.1
+for aggregate functions. A function named @code{xxx_clear()} must be defined
+rather than @code{xxx_reset()}.) For native functions, you must repeat your
modifications each time you upgrade.
@end itemize
-Whichever method you use to add new functions, they may be used just like
-native functions such as @code{ABS()} or @code{SOUNDEX()}.
+Whichever method you use to add new functions, they can be invoked in SQL
+statements just like native functions such as @code{ABS()} or
+@code{SOUNDEX()}.
-Another way to add functions is by defining stored functions. These are
+Another way to add functions is by creating stored functions. These are
written using SQL statements rather than by compiling object code. The
syntax for writing stored functions is described in @code{Stored
Procedures}.
+The following sections describe features of the UDF interface and provide
+instructions for writing UDFs.
+
+@c The following sections describe features of the UDF interface, provide
+@c instructions for writing UDFs, and discuss security precautions that MySQL
+@c takes to prevent UDF misuse.
+
+For example source code that illustrates how to write UDFs, take a look at
+the @file{sql/udf_example.cc} file that is provided in MySQL source
+distributions.
+
@menu
+* UDF features:: Features of the User-Defined Function Interface
* CREATE FUNCTION:: @code{CREATE FUNCTION/DROP FUNCTION} Syntax
* Adding UDF:: Adding a New User-defined Function
* Adding native function:: Adding a New Native Function
@end menu
-@node CREATE FUNCTION, Adding UDF, Adding functions, Adding functions
+@node UDF features, CREATE FUNCTION, Adding functions, Adding functions
+@subsection Features of the User-Defined Function Interface
+
+The MySQL interface for user-defined functions provides the following features
+and capabilties:
+
+@itemize @bullet
+
+@item
+Functions can return string, integer, or real values.
+
+@item
+You can define simple functions that operate on a single row at a time, or
+aggregate functions that operate on groups of rows.
+
+@item
+Information is provided to functions that enables them to check the number and
+types of the arguments passed to them.
+
+@item
+You can tell MySQL to coerce arguments to a given type before passing them to
+a function.
+
+@item
+You can indicate that a function returns @code{NULL} or that an error
+occurred.
+
+@end itemize
+
+
+@node CREATE FUNCTION, Adding UDF, UDF features, Adding functions
@subsection @code{CREATE FUNCTION/DROP FUNCTION} Syntax
TODO: Note: 5.0.3 adds DECIMAL as a legal value after RETURNS, but
@@ -91812,21 +91858,31 @@
@c help_category Functions
@c example_for_help_topic FUNCTION
@example
-CREATE [AGGREGATE] FUNCTION function_name RETURNS @{STRING|REAL|INTEGER@}
- SONAME shared_library_name
+CREATE [AGGREGATE] FUNCTION @var{function_name} RETURNS @{STRING|INTEGER|REAL@}
+ SONAME @var{shared_library_name}
-DROP FUNCTION function_name
+DROP FUNCTION @var{function_name}
@end example
+
@c help_category Functions
@c description_for_help_topic FUNCTION AGGREGATE CREATE FUNCTION DROP STRING REAL INTEGER RETURNS SONAME
A user-defined function (UDF) is a way to extend MySQL with a new
-function that works like a native (built in) MySQL function such as
+function that works like a native (built-in) MySQL function such as
@code{ABS()} or @code{CONCAT()}.
-To create and drop functions, you must have the @code{INSERT} and
-@code{DELETE} privileges for the @code{mysql} database. This is because
-@code{CREATE FUNCTION} saves the function's name, type, and shared library
-name in the @code{mysql.func} system table. If you do not have this table,
+@var{function_name} is the name that should be used in SQL statements to
+invoke the function. The @code{RETURNS} clause indicates the type of the
+function's return value. @var{shared_library_name} is the basename of the
+shared object file that contains the code that implements the function. The
+file must be located in a directory that is searched by your system's
+dynamic linker.
+
+To create a function, you must have the @code{INSERT} and privilege for the
+@code{mysql} database. To drop a function, you must have the @code{DELETE}
+privilege for the @code{mysql} database. This is because @code{CREATE
+FUNCTION} adds a row to the @code{mysql.func} system table that records the
+function's name, type, and shared library name, and @code{DROP FUNCTION}
+deletes the function's row from that table. If you do not have this table,
you should run the @command{mysql_fix_privilege_tables} script to create it.
@xref{Upgrading-grant-tables}.
@c end_description_for_help_topic
@@ -91842,14 +91898,12 @@
C++, your operating system must support dynamic loading and you must have
compiled @command{mysqld} dynamically (not statically).
-@code{AGGREGATE} is a new option for MySQL 3.23. An
-@code{AGGREGATE} function works exactly like a native MySQL aggregate
-(summary) function such as @code{SUM} or @code{COUNT()}.
-
-For @code{AGGREGATE} to work, your @code{mysql.func} table must contain a
-@code{type} column. If your @code{mysql.func} table does not have this
-column, you should run the @command{mysql_fix_privilege_tables} script to
-create it.
+@code{AGGREGATE} is a new option for MySQL 3.23. An @code{AGGREGATE}
+function works exactly like a native MySQL aggregate (summary) function such
+as @code{SUM} or @code{COUNT()}. For @code{AGGREGATE} to work, your
+@code{mysql.func} table must contain a @code{type} column. If your
+@code{mysql.func} table does not have this column, you should run the
+@command{mysql_fix_privilege_tables} script to create it.
@node Adding UDF, Adding native function, CREATE FUNCTION, Adding functions
@@ -91950,18 +92004,18 @@
Reset the current aggregate value and insert the argument as the initial
aggregate value for a new group.
@item @code{xxx_clear()} (required starting from 4.1.1)
-Reset the current aggregate value (but does not insert the argument as the
-initial aggregate value for a new group).
+Reset the current aggregate value but do not insert the argument as the
+initial aggregate value for a new group.
@item @code{xxx_add()} (required)
Add the argument to the current aggregate value.
@end table
-When using aggregate UDFs, MySQL works like this:
+MySQL handles aggregate UDFs as follows:
@enumerate
@item
-Call @code{xxx_init()} to let the aggregate function allocate the memory it
-needs to store results.
+Call @code{xxx_init()} to let the aggregate function allocate any memory it
+needs for storing results.
@item
Sort the table according to the @code{GROUP BY} expression.
@item
@@ -92048,21 +92102,21 @@
because @code{1.345} has 3 decimals.
@item unsigned int max_length
-The maximum length of the result. The default value differs depending on
-the result type of the function. For string functions, the default is the
-length of the longest argument. For integer functions, the default is 21
-digits. For real functions, the default is 13 plus the number of decimals
-indicated by @code{initid->decimals}. (For numeric functions, the length
-includes any sign or decimal point characters.)
+The maximum length of the result. The default @code{max_length} value
+differs depending on the result type of the function. For string functions,
+the default is the length of the longest argument. For integer functions,
+the default is 21 digits. For real functions, the default is 13 plus the
+number of decimals indicated by @code{initid->decimals}. (For numeric
+functions, the length includes any sign or decimal point characters.)
If you want to return a blob value, you can set @code{max_length} to 65KB or
-16MB. Memory is not allocated, but this value is used to decide which column
-type to use if there is a need to temporary store the data.
+16MB. This memory is not allocated, but the value is used to decide which
+column type to use if there is a need to temporarily store the data.
@item char *ptr
A pointer that the function can use for its own purposes. For example,
-functions can use @code{initid->ptr} to communicate allocated memory between
-functions. @code{xxx_init()} should allocate the memory and assign it to
+functions can use @code{initid->ptr} to communicate allocated memory among
+themselves. @code{xxx_init()} should allocate the memory and assign it to
this pointer:
@example
@@ -92087,10 +92141,10 @@
@item xxx_reset()
-This function is called when MySQL finds the first row in a new group. In
-the function you should reset any internal summary variables and then set
-the given @code{UDF_ARGS} argument as the first value in your internal
-summary value for the group. Declare @code{xxx_reset()} as follows:
+This function is called when MySQL finds the first row in a new group. It
+should reset any internal summary variables and then use the given
+@code{UDF_ARGS} argument as the first value in your internal summary value
+for the group. Declare @code{xxx_reset()} as follows:
@example
char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
@@ -92101,17 +92155,17 @@
needed or used as of MySQL 4.1.1, when the UDF interface changed to use
@code{xxx_clear()} instead. However, you can define both @code{xxx_reset()}
and @code{xxx_clear()} if you want to have your UDF work both before and
-after the interface change.
-
-In many cases, the @code{xxx_reset()} function can be implemented internally
-by resetting all variables (for example, by calling @code{xxx_clear()}), and
-then calling @code{xxx_add()}.
+after the interface change. (If you do include both functions, the
+@code{xxx_reset()} function in many cases can be implemented internally by
+calling @code{xxx_clear()} to reset all variables, and then calling
+@code{xxx_add()} to add the @code{UDF_ARGS} argument as the first value in
+the group.)
@item xxx_clear()
This function is called when MySQL needs to reset the summary results.
It is called at the beginning for each new group but can also be
-called to reset the values for a query where there was no matching rows.
+called to reset the values for a query where there were no matching rows.
Declare @code{xxx_clear()} as follows:
@example
@@ -92123,7 +92177,7 @@
If something went wrong, you can store a value in the variable to
which the @code{error} argument points. @code{error} points to a single-byte
-value, not to a string buffer.
+variable, not to a string buffer.
@code{xxx_clear()} is required only by MySQL 4.1.1 and above. Before MySQL
4.1.1, use @code{xxx_reset()} instead.
@@ -92162,13 +92216,13 @@
@code{xxx()}.
You can use this to remember that you got an error or whether the @code{xxx()}
function should return @code{NULL}. You should not store a string
-into @code{*error}! @code{error} points to a single-byte value, not to a
+into @code{*error}! @code{error} points to a single-byte variable, not to a
string buffer.
-@code{is_null} is reset for each group (before calling @code{xxx_clear()}).
-@code{error} is never reset.
+@code{*is_null} is reset for each group (before calling @code{xxx_clear()}).
+@code{*error} is never reset.
-If @code{is_null} or @code{error} are set when @code{xxx()} returns, MySQL
+If @code{*is_null} or @code{*error} are set when @code{xxx()} returns, MySQL
returns @code{NULL} as the result for the group function.
@@ -92217,10 +92271,10 @@
As an alternative to requiring your function's arguments to be of particular
types, you can use the initialization function to set the @code{arg_type}
-elements to the types you want. This causes MySQL to coerce
-arguments to those types for each call to @code{xxx()}. For example, to
-specify coercion of the first two arguments to string and integer, do this in
-@code{xxx_init()}:
+elements to the types you want. This causes MySQL to coerce arguments to
+those types for each call to @code{xxx()}. For example, to specify that the
+first two arguments should be coerced to string and integer, respectively,
+do this in @code{xxx_init()}:
@example
args->arg_type[0] = STRING_RESULT;
@@ -92229,7 +92283,7 @@
@item char **args
@code{args->args} communicates information to the initialization function
-about the general nature of the arguments your function was called with. For a
+about the general nature of the arguments passed to your function. For a
constant argument @code{i}, @code{args->args[i]} points to the argument
value. (See below for instructions on how to access the value properly.)
For a non-constant argument, @code{args->args[i]} is @code{0}.
@@ -92299,10 +92353,8 @@
The return value of the main function @code{xxx()} is the function value, for
@code{long long} and @code{double} functions. A string function should
-return a pointer to the result and store the length of the string in the
-@code{length} argument.
-
-Set these to the contents and length of the return value. For example:
+return a pointer to the result and set @code{*result} and @code{*length}
+to the contents and length of the return value. For example:
@example
memcpy(result, "result string", 13);
@@ -92321,14 +92373,14 @@
future @code{xxx()} calls. @xref{UDF calling}.
To indicate a return value of @code{NULL} in the main function, set
-@code{is_null} to @code{1}:
+@code{*is_null} to @code{1}:
@example
*is_null = 1;
@end example
-To indicate an error return in the main function, set the @code{error}
-parameter to @code{1}:
+To indicate an error return in the main function, set @code{*error} to
+@code{1}:
@example
*error = 1;
@@ -92355,7 +92407,8 @@
Files implementing UDFs must be compiled and installed on the host where
the server runs. This process is described below for the example UDF
-file @file{udf_example.cc} that is included in the MySQL source distribution.
+file @file{sql/udf_example.cc} that is included in the MySQL source
+distribution.
The immediately following instructions are for Unix. Instructions for
Windows are given later in this section.
@@ -92372,7 +92425,7 @@
@item
@code{myfunc_int()} returns the sum of the length of its arguments.
@item
-@code{sequence([const int])} returns an sequence starting from the given
+@code{sequence([const int])} returns a sequence starting from the given
number or 1 if no number has been given.
@item
@code{lookup()} returns the IP number for a hostname.
@@ -92409,11 +92462,11 @@
and add @code{-o udf_example.so} to the end of the line. (On some systems,
you may need to leave the @code{-c} on the command.)
-Once you compile a shared object containing UDFs, you must install it and
+After you compile a shared object containing UDFs, you must install it and
tell MySQL about it. Compiling a shared object from @file{udf_example.cc}
produces a file named something like @file{udf_example.so} (the exact name
-may vary from platform to platform). Copy this file to some directory
-searched by the dynamic linker @code{ld}, such as @file{/usr/lib} or add the
+may vary from platform to platform). Copy this file to some directory such
+as @file{/usr/lib} that searched by the dynamic linker @code{ld}, or add the
directory in which you placed the shared object to the linker configuration
file (for example, @file{/etc/ld.so.conf}).
@@ -92425,7 +92478,7 @@
@command{mysqld}.
On some systems, the @command{ldconfig} program that configures the dynamic
-linker does not recognize shared objects unless their name begins with
+linker does not recognize a shared object unless its name begins with
@code{lib}. In this case you should rename a file such as
@file{udf_example.so} to @file{libudf_example.so}.
@@ -99949,7 +100002,7 @@
@item
The interface to aggregate user-defined functions has changed a bit. You
must now declare a @code{xxx_clear()} function for each aggregate function
-@code{XXX()}.
+@code{XXX()}. @code{xxx_clear()} is used instead of @code{xxx_reset()}.
@item
Added new @code{ADDTIME()}, @code{DATE()}, @code{DATEDIFF()}, @code{LAST_DAY()},
@code{MAKEDATE()}, @code{MAKETIME()}, @code{MICROSECOND()}, @code{SUBTIME()},
| Thread |
|---|
| • bk commit - mysqldoc tree (paul:1.2642) | paul | 6 Mar |
