- function-name
- Names the user-defined function. The combination of name, schema name,
the number of parameters, and the data type of each parameter (without regard
for any length, precision, scale, or CCSID attributes of the data type) must
not identify a user-defined function that exists at the current server.
For SQL naming, the function will be created in the schema specified by the
implicit or explicit qualifier.
For system naming, the function will
be created in the schema that is specified by the qualifier. If no qualifier
is specified:
- If the value of the CURRENT SCHEMA special register is *LIBL, the function
will be created in the current library (*CURLIB).
- Otherwise, the function will be created in the current schema.
In general, more than one function can have the same name if the
function signature of each function is unique.
Certain function names
are reserved for system use. For more information see Choosing the Schema and Function Name.
- (parameter-declaration,...)
- Specifies the number of parameters of the function and the data type
of each parameter. Although not required, you can give each parameter a name.
The maximum number of parameters allowed in CREATE FUNCTION (External Table)
is 90. The maximum number of parameters may be additionally limited by the
maximum number of parameters allowed by the licensed program that is used
to compile the external program.
- parameter-name
- Names the parameter. Although not required, a parameter name
can be specified for each parameter. The name cannot be the same as any other parameter-name in the parameter list.
- data-type1
- Specifies the data type of the input parameter. The data
type can be a built-in data type or a distinct type.
- built-in-type
- Specifies a built-in data type. For a more complete description of each
built-in data type, see CREATE TABLE. Some data types are not supported
in all languages. For details on the mapping between the SQL data types and
host language data types, see Embedded SQL Programming book. Built-in data type specifications can be specified if they correspond
to the language that is used to write the user-defined function.
- distinct-type-name
- Specifies a user-defined distinct type. The length, precision, or scale
attributes for the parameter are those of the source type of the distinct
type (those specified on CREATE DISTINCT TYPE). For more information on creating
a distinct type, see CREATE DISTINCT TYPE.
If the name of the distinct type is
unqualified, the database manager resolves the schema name by searching the
schemas in the SQL path.
Parameters with a large object (LOB) data type are not supported
when PARAMETER STYLE JAVA is specified.
If a CCSID is specified, the
parameter will be converted to that CCSID prior to passing it to the function.
If a CCSID is not specified, the CCSID is determined by the default CCSID
at the current server at the time the function is invoked.
- AS LOCATOR
- Specifies that the input parameter is a locator to the value rather
than the actual value. You can specify AS LOCATOR only if the input parameter
has a LOB data type or a distinct type based on a LOB data type. If AS LOCATOR
is specified, FOR SBCS DATA or FOR MIXED DATA must not be specified.
- RETURNS TABLE
- Specifies the output table of the function.
Assume the number of parameters
is N. For PARAMETER STYLE DB2GENERAL, there must be no more than (255-(N*2))/2
columns. For PARAMETER STYLE DB2SQL, there must be no more than (247-(N*2))/2
columns.
- column-name
- Specifies the name of a column of the output table. Do not specify the
same name more than once.
- data-type2
- Specifies the data type and attributes of the output.
You can specify any built-in data type (except LONG VARCHAR, LONG VARGRAPHIC,
or DataLink) or a distinct type (that is not based on a DataLink).
If a DATE or TIME is specified, the table function must return the date or
time in ISO format.
If a CCSID is specified,
- If AS LOCATOR is not specified, the result returned is assumed to be encoded
in that CCSID.
- If AS LOCATOR is specified and the CCSID of the data the locator points
to is encoded in a different CCSID, the data is converted to the specified
CCSID.
If a CCSID is not specified,
- If AS LOCATOR is not specified, the result returned is assumed to be encoded
in the CCSID of the job (or associated graphic CCSID of the job for graphic
string return values).
- If AS LOCATOR is specified, the data the locator points to
is converted to the CCSID of the job, if the CCSID of the data the locator
points to is encoded in a different CCSID. To avoid any potential loss of
characters during the conversion, consider explicitly specifying a CCSID that
can represent any characters that will be returned from the function. This
is especially important if the data type is graphic string data. In this case,
consider using CCSID 1200 or 13488 (Unicode graphic string data).
- AS LOCATOR
- Specifies that the function returns a locator to the value for the column
rather than the actual value. You can specify AS LOCATOR only for a LOB data
type or a distinct type based on a LOB data type. If AS LOCATOR is specified,
FOR SBCS DATA or FOR MIXED DATA must not be specified.
- LANGUAGE (language clause)
- The language clause specifies the language of the external program.
If LANGUAGE is not specified, the LANGUAGE is determined from the program
attribute information associated with the external program at the time the
function is created. The language of the program is assumed to be C if:
- The program attribute information associated with the program does not
identify a recognizable language
- The program cannot be found
- C
- The external program is written in C.
- C++
- The external program is written in C++.
- CL
- The external program is written in CL or ILE CL.
- COBOL
- The external program is written in COBOL.
- COBOLLE
- The external program is written in ILE COBOL.
- FORTRAN
- The external program is written in FORTRAN.
- JAVA
- The external program is written in JAVA. The database manager will call
the user-defined function as a method in a Java(TM) class.
- PLI
- The external program is written in PL/I.
- RPG
- The external program is written in RPG.
- RPGLE
- The external program is written in ILE RPG.
- PARAMETER STYLE
- Specifies the conventions used for passing parameters to and returning
the values from functions:
- DB2GENERAL
- This parameter style is used to specify the conventions for passing
parameters to and returning the value from external functions that are defined
as a method in a Java class. All applicable parameters are passed.
The parameters are defined to be in the following order:
- The first N parameters are the input parameters that are specified on
the CREATE FUNCTION statement.
- The next M parameters are the result columns of the function that are
specified on the RETURNS TABLE clause.
DB2GENERAL is only allowed when the LANGUAGE is JAVA.
- DB2SQL
- All applicable parameters are passed. The parameters are defined to
be in the following order:
- The first N parameters are the input parameters that are specified on
the CREATE FUNCTION statement.
- The next M parameters are the result columns of the function that are
specified on the RETURNS TABLE clause.
- N parameters for indicator variables for the input parameters.
- M parameters for the indicator variables of the result columns of the
function that are specified on the RETURNS TABLE clause
- A CHAR(5) output parameter for SQLSTATE. The SQLSTATE returned indicates
the success or failure of the function. The SQLSTATE returned either be:
- A VARCHAR(517) input parameter for the fully qualified function name.
- A VARCHAR(128) input parameter for the specific name.
- A VARCHAR(70) output parameter for the message text.
- A structure (consisting of an INTEGER followed by a CHAR(n)) input and
output parameter for the scratchpad, if SCRATCH PAD was specified on the CREATE
FUNCTION statement.
- An INTEGER input parameter for the call type.
- A structure for the dbinfo structure, if DBINFO was specified on the CREATE
FUNCTION statement.
For more information about the parameters passed, see the include sqludf in the appropriate source file in library QSYSINC.
For example, for C, sqludf can be found in QSYSINC/H.
Note that the language of the external function determines how
the parameters are passed. For example, in C, any VARCHAR or CHAR parameters
are passed as NUL-terminated strings. For more information, see the SQL Programming book. For Java routines, see the IBM(R) Developer
Kit for Java.
- SPECIFIC specific-name
- Provides a unique name for the function. The name is implicitly or explicitly
qualified with a schema name. The name, including the schema name, must not
identify the specific name of another function or procedure that exists at
the current server. If unqualified, the implicit qualifier is the same as
the qualifier of the function name. If qualified, the qualifier must be the
same as the qualifier of the function name.
If specific name is not specified,
it is set to the function name. If a function or procedure with that specific
name already exists, a unique name is generated similar to the rules used
to generate unique table names.
- DETERMINISTIC or NOT DETERMINISTIC
- Specifies whether the function is deterministic.
- NOT DETERMINISTIC
- Specifies that the function will not always return the same result from
successive function invocations with identical input arguments. NOT DETERMINISTIC
should be specified if the function contains a reference to a special register,
a non-deterministic function, or a sequence.
- DETERMINISTIC
- Specifies that the function will always return the same result from
successive invocations with identical input arguments.
- CONTAINS SQL, READS SQL DATA, MODIFIES SQL DATA, or NO SQL
- Specifies whether the function can execute any SQL statements and, if
so, what type. The database manager verifies that the SQL issued by the function is
consistent with this specification. See Appendix B. Characteristics of SQL statements for a detailed
list of the SQL statements that can be executed under each data access indication.
- CONTAINS SQL
- The function does not execute SQL statements that read or modify data.
- NO SQL
- The function does not execute SQL statements.
- READS SQL DATA
- The function does not execute SQL statements that modify data.
- MODIFIES SQL DATA
- The function can execute any SQL statement except those statements that
are not supported in any function.
- RETURNS NULL ON NULL INPUT or CALLED ON
NULL INPUT
- Specifies whether the function is called if any of the input arguments
is null at execution time.
- RETURNS NULL ON NULL INPUT
- Specifies that the function is not invoked if any of the input arguments
is null. The result is the null value.
- CALLED ON NULL INPUT
- Specifies that the function is to be invoked, if any, or all, argument
values are null, making the function responsible for testing for null argument
values. The function can return a null or nonnull value.
- INHERIT SPECIAL REGISTERS
- Specifies that existing values of special registers are inherited upon
entry to the function.
- STATIC DISPATCH
- Specifies that the function is dispatched statically. All functions
are statically dispatched.
- DBINFO
- Specifies whether or not the function requires the database information
be passed.
- DBINFO
- Specifies that the database manager should pass a structure containing
status information to the function. Table 50 contains a description
of the DBINFO structure. Detailed information about the DBINFO structure can
be found in sqludf in the appropriate source file
in library QSYSINC. For example, for C, sqludf can be found in QSYSINC/H.
Table 50. DBINFO fields
Field |
Data Type |
Description |
Relational database |
VARCHAR(128) |
The name of the current server. |
Authorization ID |
VARCHAR(128) |
The run-time authorization ID. |
CCSID Information |
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
CHAR(8)
|
The CCSID information of the job. Three sets
of three CCSIDs are returned. The following information identifies the three
CCSIDs in each set:
- SBCS CCSID
- DBCS CCSID
- Mixed CCSID
Following the three sets of CCSIDs is an integer that indicates which
set of three sets of CCSIDs is applicable and eight bytes of reserved space.
If a CCSID is not explicitly specified for a parameter on the CREATE FUNCTION
statement, the input string is assumed to be encoded in the CCSID of the job
at the time the function is executed. If the CCSID of the input string is
not the same as the CCSID of the parameter, the input string passed to the
external function will be converted before calling the external program. |
Target column |
VARCHAR(128)
VARCHAR(128)
VARCHAR(128)
|
If a user-defined function is specified on
the right-hand side of a SET clause in an UPDATE statement, the following
information identifies the target column:
- Schema name
- Base table name
- Column name
If the user-defined function is not on the right-hand side of a SET clause
in an UPDATE statement, these fields are blank. |
Version and release |
CHAR(8) |
The version, release, and modification level
of the database manager. |
Platform |
INTEGER |
The server's platform type. |
Number of table function column list entries |
SMALLINT |
The number of non-zero entries in the table
function column list specified in the "Table function column
list" field below. |
Reserved |
CHAR(24) |
Reserved for future use. |
Table function column list |
Pointer (16 Bytes) |
This field is a pointer to an array of short
integers which is dynamically allocated by the database manager. Only the first n entries,
where n is specified in the "Number of table function column list entries"
field, are of interest, n may be equal to 0, and is less than or equal to
the number of result columns defined for the function in the RETURNS TABLE
clause. The values correspond to the ordinal numbers of the columns which
this statement needs from the table function. A value of 1 means the first
defined result column, 2 means the second defined result column, and so on.
The values may be in any order. Note that n could be equal to zero for a statement
that is similar to SELECT COUNT(*) FROM TABLE(TF(...)) AS QQ, where no actual
column values are needed by the query.
This array represents an opportunity
for optimization. The function need not return all values for all the result
columns of the table function. Only a subset of the values may be needed in
a particular context, and these are the columns identified (by number) in
the array. Since this optimization may complicate the function logic, the
function can choose to return every defined column. |
- NO DBINFO
- Specifies that the function does not require the database information
to be passed.
- EXTERNAL ACTION or NO EXTERNAL ACTION
- Specifies whether the function contains an external action.
- EXTERNAL ACTION
- The function performs some external action (outside the scope of the
function program). Thus, the function must be invoked with each successive
function invocation. EXTERNAL ACTION should be specified if the function contains
a reference to another function that has an external action.
- NO EXTERNAL ACTION
- The function does not perform an external action. It need not be called
with each successive function invocation.
- FENCED or NOT FENCED
- Specifies whether the external function runs in an environment that
is isolated from the database manager environment.
- FENCED
- The function will run in a separate thread.
FENCED functions cannot
keep SQL cursors open across individual calls to the function. However, the
cursors in one thread are independent of the cursors in any other threads
which reduces the possibility of cursor name conflicts.
- NOT FENCED
- The function may run in the same thread as the invoking SQL statement.
NOT FENCED functions can keep SQL cursors open across individual calls to
the function. Since cursors can be kept open, the cursor position will also
be preserved between calls to the function. However, cursor names may conflict
since the UDF is now running in the same thread as the invoking SQL statement
and other NOT FENCED UDFs.
NOT FENCED functions usually perform better
than FENCED functions.
- PROGRAM TYPE MAIN or PROGRAM TYPE MAIN
- This parameter is allowed for compatibility with other products. It
indicates whether the routine's external program is a program (*PGM) or
a procedure in a service program (*SRVPGM).
- PROGRAM TYPE MAIN
- Specifies that the routine executes as the main entry point in a program.
The external program must be a *PGM object.
- PROGRAM TYPE SUB
- Specifies that the procedure executes as a procedure in a service program.
The external program must be a *SRVPGM object.
- FINAL CALL
- Specifies whether the function requires a final call (and a separate
first call). For table functions, the call-type argument is ALWAYS present,
regardless of which FINAL CALL option is chosen. The call-type argument indicates
first call, open call, fetch call, close call, or final call.
- FINAL CALL
- Specifies that the function requires a final call (and a separate first
call). It also controls when the scratchpad is re-initialized. If NO FINAL
CALL is specified, then the database manager can only make three types of calls to the
table function: open, fetch and close. However, if FINAL CALL is specified,
then in addition to open, fetch and close, a first call and a final call can
be made to the table function.Specifies that a final call is made to the function.
To differentiate between final calls and other calls, the function receives
an additional argument that specifies the type of call.
The types of calls
are:
- First Call
- Specifies the first call to the function for this reference to the function
in this SQL statement.
- Open Call
- Specifies a call to open the table function result in this SQL statement.
- Fetch Call
- Specifies a call to fetch a row from the table function in this SQL
statement.
- Close Call
- Specifies a call to close the table function result in this SQL statement.
- Final Call
- Specifies the last call to the function to enable the function to free
resources. If an error occurs, the database manager attempts to make the final
call.
A final call occurs at these times:
- End of statement: When the cursor is closed for
cursor-oriented statements, or the execution of the statement has completed.
- End of transaction: When normal end of statement
processing does not occur. For example, the logic of an application, for some
reason, bypasses closing the cursor.
If a commit operation occurs while a cursor defined as WITH HOLD
is open, a final call is made when the cursor is closed or the application
ends.
Commitable operations should not be performed during a FINAL CALL,
because the FINAL CALL may occur during a close invoked as part of a COMMIT
operation.
- NO FINAL CALL
- Specifies that the function does not require a final call (and a separate
first call). However the open, fetch, and close calls are still made.
- DISALLOW PARALLEL
- Specifies that the function cannot be run in parallel. Table functions
cannot run in parallel.
- SCRATCHPAD
- Specifies whether the function requires a static memory area.
- SCRATCHPAD integer
- Specifies that the function requires a persistent memory area of length
integer. The integer can range from 1 to 16,000,000. If the memory area is
not specified, the size of the area is 100 bytes. If parameter style DB2SQL
is specified, a pointer is passed following the required parameters that points
to a static storage area. Only 1 memory area will be allocated for the function.
The scope of a scratchpad is the SQL statement. For each reference to the
function in an SQL statement, there is one scratchpad. For example, assuming
that function UDFX was defined with the SCRATCHPAD keyword, two scratchpads
are allocated for the two references to UDFX in the following SQL statement:
SELECT A.C1, B.C1
FROM TABLE(UDFX(:hv1)) AS A, TABLE(UDFX(:hv1)) AS B
- NO SCRATCHPAD
- Specifies that the function does not require a persistent memory area.
- EXTERNAL NAME external-program-name
- Specifies the program, service program, or java class that will be executed
when the function is invoked in an SQL statement. The name must identify a
program, service program, or java class that exists at the application server at the
time the function is invoked. If the naming option is *SYS and the name is
not qualified:
- The current path will be used to search for the program or service program
at the time the function is invoked.
- *LIBL will be used to search for the program or service program at the
time grants or revokes are performed on the function.
The validity of the name is checked at the application server. If the format
of the name is not correct, an error is returned.
If external-program-name
is not specified, the external program name is assumed to be the same as the
function name.
The program, service program, or java class need not
exist at the time the function is created, but it must exist at the time the
function is invoked.
A CONNECT, SET CONNECTION, RELEASE, DISCONNECT,
COMMIT, ROLLBACK and SET TRANSACTION statement is not allowed in the external
program of the function.
- CARDINALITY bigint
- Specifies an estimate of the expected number of rows to be
returned by the function for the database manager to use during optimization. bigint must be in the range from 0 to 9 223 372 036 854 775
807 inclusive. The database manager assumes a finite value if CARDINALITY
is not specified.
A table function that returns a row every time it is called
and never returns the end-of-table condition has infinite cardinality. A query
that invokes such a function and requires an eventual end-of-table condition
before it can return any data will not return unless interrupted. Table functions
that never return the end-of-table condition should not be used in queries
involving DISTINCT, GROUP BY, or ORDER BY.
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.