Java user-defined scalar functions

Parameter style Java

The Java parameter style is the style specified by the SQLJ Part 1: SQL Routines standard. When coding a Java UDF, use the following conventions.

• The Java method must be a public static method.
• The Java method must return an SQL compatible type. The return value is the result of the method.
• The parameters of the Java method must be SQL compatible types.
• The Java method may test for a SQL NULL for Java types that permit the null value.

For example, given a UDF called sample!test3 that returns INTEGER and takes arguments of type CHAR(5), BLOB(10K), and DATE, DB2^® expects the Java implementation of the UDF to have the following signature:

import com.ibm.db2.app.*;
public class sample {
   public static int test3(String arg1, Blob arg2, Date arg3) { ... }
}

The parameters of a Java method must be SQL compatible types. For example, if a UDF is declared as taking arguments of SQL types t1, t2, and t3, and returning type t4, it is called as a Java method with the expected Java signature:

   public static T4 name (T1 a, T2 b, T3 c)  { .....}

where:

• name is the method name
• T1 through T4 are the Java types that correspond to SQL types t1 through t4.
• a, b, and c are arbitrary variable names for the input arguments.

The correlation between SQL types and Java types is found in Parameter passing conventions for stored procedures and UDFs.

SQL NULL values are represented by Java variables that are not initialized. These variables have a Java null value if they are object types. If an SQL NULL is passed to a Java scalar data type, such as int, then an exception condition is raised.

To return a result from a Java UDF when using the JAVA parameter style, simply return the result from the method.

{ ....                                                       
  return value;                                             
}                

Like C modules used in UDFs and stored procedures, you cannot use the Java standard I/O streams (System.in, System.out, and System.err) in Java UDFs.

Parameter style DB2GENERAL

Parameter style DB2GENERAL is used by Java UDFs. In this parameter style, the return value is passed as the last parameter of the function and must be set using a set method of the com.ibm.db2.app.UDF class.

When coding a Java UDF, the following conventions must be followed:

• The class, which includes the Java UDF, must extend, or be a subclass of, the Java com.ibm.db2.app.UDF class.
• For the DB2GENERAL parameter style, the Java method must be a public void instance method.
• The parameters of the Java method must be SQL-compatible types.
• The Java method may test for an SQL NULL value using the isNull method.
• For the DB2GENERAL parameter style, the Java method must explicitly set the return parameter using the set() method.

A class that includes a Java UDF must extend the Java class, com.ibm.db2.app.UDF. A Java UDF that uses the DB2GENERAL parameter style must be a void instance method of the Java class. For example, for a UDF called sample!test3 that returns INTEGER and takes arguments of type CHAR(5), BLOB(10K), and DATE, DB2 expects the Java implementation of the UDF to have the following signature:

import com.ibm.db2.app.*;
public class sample extends UDF {
   public void test3(String arg1, Blob arg2, String arg3, int result) { ... }
}

The parameters of a Java method must be SQL types. For example, if a UDF is declared as taking arguments of SQL types t1, t2, and t3, returning type t4, it is called as a Java method with the expected Java signature:

public void name (T1 a, T2 b, T3 c, T4 d)  { .....}

where:

• name is the method name
• T1 through T4 are the Java types that correspond to SQL types t1 through t4.
• a, b, and c are arbitrary variable names for the input arguments.
• d is an arbitrary variable name that represents the UDF result being computed.

The correlation between SQL types and Java types is given in the section, Parameter passing conventions for stored procedures and UDFs.

SQL NULL values are represented by Java variables that are not initialized. These variables have a value of zero if they are primitive types, and Java null if they are object types, in accordance with Java rules. To tell an SQL NULL apart from an ordinary zero, the isNull method can be called for any input argument:

     { ....
       if (isNull(1)) { /* argument #1 was a SQL NULL */ }
       else           { /* not NULL */ }
     }

In the previous example, the argument numbers start at one. The isNull() function, like the other functions that follow, are inherited from the com.ibm.db2.app.UDF class. To return a result from a Java UDF when using the DB2GENERAL parameter style, use the set() method in the UDF, as follows:

     { ....
       set(2, value);
     }

Where 2 is the index of an output argument, and value is a literal or variable of a compatible type. The argument number is the index in the argument list of the selected output. In the first example in this section, the int result variable has an index of 4. An output argument that is not set before the UDF returns has a NULL value.

Like C modules used in UDFs and stored procedures, you cannot use the Java standard I/O streams (System.in, System.out, and System.err) in Java UDFs.

Typically, DB2 calls a UDF many times, once for each row of an input or result set in a query. If SCRATCHPAD is specified in the CREATE FUNCTION statement of the UDF, DB2 recognizes that some "continuity" is needed between successive invocations of the UDF, and therefore, for DB2GENERAL parameter style functions, the implementing Java class is not instantiated for each call, but generally speaking once per UDF reference per statement. If, however, NO SCRATCHPAD is specified for a UDF, then a clean instance is instantiated for each call to the UDF, by means of a call to the class constructor.

A scratchpad may be useful for saving information across calls to a UDF. Java UDFs can either use instance variables or set the scratchpad to achieve continuity between calls. Java UDFs access the scratchpad with the getScratchPad and setScratchPad methods available in com.ibm.db2.app.UDF. At the end of a query, if you specify the FINAL CALL option on the CREATE FUNCTION statement, the object's public void close() method is called (for DB2GENERAL parameter style functions). If you do not define this method, a stub function takes over and the event is ignored. The com.ibm.db2.app.UDF class contains useful variables and methods that you can use within a DB2GENERAL parameter style UDF. These variables and methods are explained in the following table.