DB2GENERAL Java class: COM.ibm.db2.app.UDF

public class user-UDF-class extends COM.ibm.db2.app.UDF{ ... }

You can call methods of the COM.ibm.db2.app.UDF interface only in the context of the currently executing UDF. For example, you cannot use operations on LOB arguments, result or status-setting calls, and so on, after a UDF returns from execution. A Java exception is thrown if this rule is violated.

Argument-related calls use a column index to identify the column being set. The column indexes start at 1 for the first argument. Output arguments are numbered higher than the input arguments. For example, a scalar UDF with three inputs uses index 4 for the output.

Any exception returned from the UDF is caught by the database and returned to the caller with SQLCODE -4302, SQLSTATE 38501.

public UDF() [default constructor]

This constructor is called by the database at the beginning of a series of UDF calls. It precedes the first call to the UDF.

public void close()

This function is called by the database at the end of a UDF evaluation, if the UDF was created with the FINAL CALL option. It is analogous to the final call for a C UDF. For table functions, close() is called after the CLOSE call to the UDF method (if NO FINAL CALL is coded or defaulted), or after the FINAL call (if FINAL CALL is coded). If a Java UDF class does not implement this function, a no-operation stub handles and ignores this event.

public int getCallType() throws Exception

public boolean isNull(int) throws Exception

This function tests whether an input argument with the given index is an SQL NULL.

public boolean needToSet(int) throws Exception

This function tests whether an output argument with the given index must be set. This can be false for a table UDF declared with DBINFO, if that column is not used by the UDF caller.

public void set(int, short) throws Exception
public void set(int, int) throws Exception
public void set(int, double) throws Exception
public void set(int, float) throws Exception
public void set(int, java.math.BigDecimal) throws Exception
public void set(int, String) throws Exception
public void set(int, COM.ibm.db2.app.Blob) throws Exception
public void set(int, COM.ibm.db2.app.Clob) throws Exception

This function sets the output argument with the given index to the given value. The index must refer to a valid output argument, the data type must match, and the value must have an acceptable length and contents. Strings with Unicode characters must be representable in the database code page. Errors result in an exception being thrown.

public void setSQLstate(String) throws Exception

This function can be called from a UDF to set the SQLSTATE to be returned from this call. A table UDF can call this function with "02000" to signal the end-of-table condition. If the string is not acceptable as an SQLSTATE, an exception is thrown.

public void setSQLmessage(String) throws Exception

This function is like the setSQLstate function. It sets the SQL message result. If the string is not acceptable (for example, longer than 70 characters), an exception is thrown.

public String getFunctionName() throws Exception

This function returns the name of the executing UDF.

public String getSpecificName() throws Exception

This function returns the specific name of the executing UDF.

public byte[] getDBinfo() throws Exception

This function returns a raw, unprocessed DBINFO structure for the executing UDF, as a byte array. You must first declare it with the DBINFO option.

public String getDBname() throws Exception
public String getDBauthid() throws Exception
public String getDBtbschema() throws Exception
public String getDBtbname() throws Exception
public String getDBcolname() throws Exception
public String getDBver_rel() throws Exception
public String getDBplatform() throws Exception
public String getDBapplid() throws Exception

These functions return the value of the appropriate field from the DBINFO structure of the executing UDF.

public int getDBprocid() throws Exception

This function returns the routine ID of the procedure which directly or indirectly called this routine. The routine ID matches the ROUTINEID column in SYSCAT.ROUTINES which can be used to retrieve the name of the calling procedure. If the executing routine is called from an application, getDBprocid() returns 0.

public int[] getDBcodepg() throws Exception

This function returns the SBCS, DBCS, and composite code page numbers for the database, from the DBINFO structure. The returned integer array has the following numbers as its first three elements.

public byte[] getScratchpad() throws Exception

This function returns a copy of the scratchpad of the currently executing UDF. You must first declare the UDF with the SCRATCHPAD option.

public void setScratchpad(byte[]) throws Exception

This function overwrites the scratchpad of the currently executing UDF with the contents of the given byte array. You must first declare the UDF with the SCRATCHPAD option. The byte array must have the same size as getScratchpad() returns.

The COM.ibm.db2.app.UDF class contains the following methods for facilitating the execution of Java UDFs in a partitioned database environment:

public int[] getDBPartitions() throws Exception

This function returns a list of all the partitions included in the table function.

public int getCurrentDBPartitionNum() throws Exception

This function returns the partition number of the node on which the table function is currently executing.

The COM.ibm.db2.app.UDF class contains the following methods for getting information required to create external generic table functions:

public int getNumColumns() throws Exception

For table UDFs, this function returns the number of output columns. For other UDFs, this function returns "1".

public int getColumnType(int position) throws Exception 

This function returns the data type of the specified output column.