Parameter style DB2SQL

With the DB2SQL parameter style, the same parameters and same order of parameters are passed into the external program or service program as are passed in for parameter style SQL. However, DB2SQL allows additional optional parameters to be passed along as well.

If more than one of the optional parameters below is specified in the UDF definition, they are passed to the UDF in the order defined below. Refer to parameter style SQL for the common parameters. This parameter style can be used for both scalar and table UDFs.

For scalar functions:


>>-+------------------+--SQL-result--+----------------------+--->
   | .--------------. |              | .------------------. |   
   | V              | |              | V                  | |   
   '---SQL-argument-+-'              '---SQL-argument-ind-+-'   

>--SQL-result-ind--SQL-state--function-name--specific-name------>

>--diagnostic-message--+------------+--+-----------+------------>
                       '-scratchpad-'  '-call-type-'   

>--+--------+--------------------------------------------------><
   '-dbinfo-'

For table functions:


                         .------------.   
                         V            |   
>>-+------------------+----SQL-result-+------------------------->
   | .--------------. |                   
   | V              | |                   
   '---SQL-argument-+-'                   

                             .----------------.              
                             V                |              
>--+----------------------+----SQL-result-ind-+--SQL-state------>
   | .------------------. |                                  
   | V                  | |                                  
   '---SQL-argument-ind-+-'                                  

>--function-name--specific-name--diagnostic-message------------->

>--+------------+--call-type--+--------+-----------------------><
   '-scratchpad-'             '-dbinfo-'

scratchpad

This argument is set by DB2^® before calling the UDF. It is only present if the CREATE FUNCTION statement for the UDF specified the SCRATCHPAD keyword. This argument is a structure with the following elements:

An INTEGER containing the length of the scratchpad.
The actual scratchpad, initialized to all binary 0's by DB2 before the first call to the UDF.

The scratchpad can be used by the UDF either as working storage or as persistent storage, since it is maintained across UDF invocations.

For table functions, the scratchpad is initialized as above before the FIRST call to the UDF if FINAL CALL is specified on the CREATE FUNCTION. After this call, the scratchpad content is totally under control of the table function. DB2 does not examine or change the content of the scratchpad thereafter. The scratchpad is passed to the function on each invocation. The function can be re-entrant, and DB2 preserves its state information in the scratchpad.

If NO FINAL CALL was specified or defaulted for a table function, then the scratchpad is initialized as above for each OPEN call, and the scratchpad content is completely under control of the table function between OPEN calls. This can be very important for a table function used in a join or subquery. If it is necessary to maintain the content of the scratchpad across OPEN calls, then FINAL CALL must be specified in your CREATE FUNCTION statement. With FINAL CALL specified, in addition to the normal OPEN, FETCH, and CLOSE calls, the table function will also receive FIRST and FINAL calls, for the purpose of scratchpad maintenance and resource release.

call-type

This argument is set by DB2 before calling the UDF. For scalar functions, it is only present if the CREATE FUNCTION statement for the UDF specified the FINAL CALL keyword. However, for table functions it is always present. It follows the scratchpad argument; or the diagnostic-message argument if the scratchpad argument is not present. This argument takes the form of an INTEGER value.

For scalar functions:

-1: This is the first call to the UDF for this statement. A first call is a normal call in that all SQL argument values are passed.
0: This is a normal call. (All the normal input argument values are passed).
1: This is a final call. No SQL-argument or SQL-argument-ind values are passed. A UDF should not return any answer using the SQL-result, SQL-result-ind arguments, SQL-state, or diagnostic-message arguments. These arguments are ignored by the system when returned from the UDF.

For table functions:

-2: This is the first call to the UDF for this statement. A first call is a normal call in that all SQL argument values are passed.
-1: This is the open call to the UDF for this statement. The scratchpad is initialized if NO FINAL CALL is specified, but not necessarily otherwise. All SQL argument values are passed.
0: This is a fetch call. DB2 expects the table function to return either a row comprising the set of return values, or an end-of-table condition indicated by SQLSTATE value '02000'.
1: This is a close call. This call balances the OPEN call, and can be used to perform any external CLOSE processing and resource release.
2: This is a final call. No SQL-argument or SQL-argument-ind values are passed. A UDF should not return any answer using the SQL-result, SQL-result-ind arguments, SQL-state, or diagnostic-message arguments. These arguments are ignored by the system when returned from the UDF.

dbinfo

This argument is set by DB2 before calling the UDF. It is only present if the CREATE FUNCTION statement for the UDF specifies the DBINFO keyword. The argument is a structure whose definition is contained in the sqludf include.