Funciones escalares Java definidas

por usuario
La funcin escalar Java devuelve un valor a la base de datos desde un
programa Java. Por ejemplo, se podra crear una funcin escalar que
devolviera la suma de dos nmeros.
Al igual que los procedimientos almacenados Java, las funciones escalares
Java utilizan uno de los dos estilos de parmetro, Java y DB2GENERAL.
Cuando escriba el cdigo de una funcin definida por usuario (UDF) Java, debe
tener presentes las restricciones que afectan a la la creacin de funciones
escalares Java.
Estilo de parmetro Java
El estilo de los parmetros Java es el especificado por el estndar SQLJ Part 1:
SQL Routines. Cuando escriba el cdigo fr una UDF Java, siga estos
convenios.
El mtodo Java debe ser pblico esttico.
El mtodo Java debe devolver un tipo compatible con SQL. El valor de retorno
es el resultado del mtodo.
Los parmetros del mtodo Java deben ser tipos compatibles con SQL.
El mtodo Java podra comprobar la presencia de un SQL NULL para los tipos
Java que permiten el valor nulo.
Por ejemplo, dada una UDF que se llama sample!test3 y devuelve INTEGER y
toma argumentos de tipo CHAR(5), BLOB(10K) y DATE, DB2 espera que la
implementacin Java de la UDF tenga esta signatura:
import com.ibm.db2.app.*;
public class sample {
public static int test3(String arg1, Blob arg2, Date arg3) { ... }
}

Los parmetros de un mtodo Java deben ser tipos compatibles con SQL. Por
ejemplo, si se declara que una UDF toma argumentos de los tipos SQL t1, t2 y
t3, y que devuelve el tipo t4, se la llama como a un mtodo Java con la
signatura Java que cabe esperar:
public static T4 nombre (T1 a, T2 b, T3 c) { .....}
donde:
nombre es el nombre del mtodo
Los tipos de T1 a T4 son los tipos Java que se corresponden con los tipos SQL
de t1 a t4.
a, b y c son nombres de variable arbitrarios para los argumentos de entrada.
La correlacin entre tipos SQL y tipos Java se encuentra en: Convenios de
pase de parmetros para procedimientos almacenados y funciones definidas
por usuario (UDF).
Los valores SQL NULL se representan mediante variables Java que no estn
inicializadas. Estas variables tiene un valor Java nulo si son tipos de objeto. Si
se pasa un SQL NULL a datos Java de tipo escalar (como int), se produce una
condicin de excepcin.
Para devolver un resultado desde una UDF Java al utilizar el estilo de
parmetros JAVA, basta con devolver el resultado del mtodo.
{ ....
return value;
}
 Al igual que los mdulos C utilizados en las UDF y en los procedimientos
almacenados, no puede utilizar las corrientes de E/S estndar Java (System.in,
System.out y System.err) en las UDF Java.
Estilo de los parmetros DB2GENERAL
El estilo de los parmetros DB2GENERAL se emplea en las funciones
definidas por usuario (UDF) Java. En este estilo de parmetro, el valor de
retorno se pasa como el ltimo parmetro de la funcin y debe establecerse
mediante un mtodo set de la clase com.ibm.db2.app.UDF.
Cuando escriba el cdigo de una UDF Java, hay que seguir estos convenios:
La clase, que incluye la UDF Java, debe ampliar (extend) la clase Java
com.ibm.db2.app.UDF o ser una subclase de ella.
En el estilo de los parmetros DB2GENERAL, el mtodo Java debe ser un
mtodo de instancia pblico vaco (void).
Los parmetros del mtodo Java deben ser tipos compatibles con SQL.
El mtodo Java podra comprobar la presencia de un valor SQL NULL
mediante el mtodo isNull.
En el caso del estilo de los parmetros DB2GENERAL, el mtodo Java debe
establecer explcitamente el parmetro de retorno utilizando el mtodo set().
Una clase que incluya una UDF Java debe ampliar la clase Java
com.ibm.db2.app.UDF. Una UDF Java que utilice el estilo de parmetro
DB2GENERAL debe ser un mtodo de instancia void de la clase Java. Por
ejemplo, en el caso de una UDF que se llame sample!test3 y devuelva
INTEGER y tome argumentos de tipo CHAR(5), BLOB(10K) y DATE, DB2
espera que la implementacin Java de la UDF tenga esta signatura:
import com.ibm.db2.app.*;
public class sample extends UDF {
public void test3(String arg1, Blob arg2, String arg3, int result)
{ ... }
}

Los parmetros de un mtodo Java deben ser tipos SQL. Por ejemplo, si se
declara que una UDF toma argumentos de los tipos SQL t1, t2 y t3, y que
devuelve el tipo t4, se la llama como a un mtodo Java con la signatura Java
que cabe esperar:
public void nombre (T1 a, T2 b, T3 c, T4 d) { .....}

donde:
nombre es el nombre del mtodo
Los tipos de T1 a T4 son los tipos Java que se corresponden con los tipos SQL
de t1 a t4.
a, b y c son nombres de variable arbitrarios para los argumentos de entrada.
d es un nombre de variable arbitrario que representa el resultado de la UDF
que se calcula.
La correlacin entre tipos SQL y tipos Java se proporciona en: Convenios de
pase de parmetros para procedimientos almacenados y funciones definidas
por usuario (UDF).
Los valores SQL NULL se representan mediante variables Java que no estn
inicializadas. Estas variables tienen el valor cero si son tipos primitivos, y tienen
el valor nulo Java si son tipos de objeto, segn las reglas de Java. Para indicar
un valor SQL NULL que no sea un cero ordinario, puede llamarse al mtodo
isNull para un argumento de entrada:
{ ....
 if (isNull(1)) { /* el argumento n 1 era un SQL NULL */ }
else { /* no NULL */ }
}
En el ejemplo anterior, los nmeros de argumento empiezan por el uno. La
funcin isNull(), al igual que las dems funciones que siguen, se hereda de la
clase com.ibm.db2.app.UDF. Para devolver un resultado desde una UDF Java
cuando se utiliza el estilo de parmetro DB2GENERAL, emplee el mtodo set()
de la UDF, como se indica a continuacin:
{ ....
set(2, valor);
}
Donde 2 es el ndice de un argumento de salida y valor es un literal o variable
de un tipo compatible. El nmero de argumento es el ndice de la lista de
argumentos de la salida seleccionada. En el primer ejemplo de esta seccin, la
variable de resultado int tiene un ndice 4. Un argumento de salida que no se
establezca antes de que la UDF retorne tiene el valor NULL.
Al igual que los mdulos C utilizados en las UDF y en los procedimientos
almacenados, no puede utilizar las corrientes de E/S estndar Java (System.in,
System.out y System.err) en las UDF Java.
Por lo general, DB2 llama a una UDF muchas veces, una para cada fila de una
entrada o conjunto de resultados de una consulta. Si se especifica
SCRATCHPAD en la sentencia CREATE FUNCTION de la UDF, DB2 reconoce
que es necesaria alguna "continuidad" entre las sucesivas invocaciones de la
UDF y, por tanto, en el caso de las funciones de estilo de parmetro
DB2GENERAL, no se crea una instancia de la clase Java de implementacin
para cada llamada, sino que generalmente se crea una vez por cada referencia
a UDF y por cada sentencia. Sin embargo, si se especifica NO SCRATCHPAD
para una UDF, se crea una instancia pura por cada llamada a la UDF por
medio de una llamada al constructor de la clase.
Puede ser de utilidad tener un rea reutilizable para guardar informacin a lo
largo de las llamadas a una UDF. Las UDF Java pueden utilizar variables de
instancia o bien establecer que el rea reutilizable consiga continuidad entre las
llamadas. Las UDF Java acceden al rea reutilizable con los mtodos
getScratchPad y setScratchPad disponibles en com.ibm.db2.app.UDF. Al final
de una consulta, si especifica la opcin FINAL CALL en la sentencia CREATE
FUNCTION, se llama al mtodo public void close() del objeto (para las
funciones del estilo de parmetro DB2GENERAL). Si no define este mtodo,
una funcin de apndice toma el control y el evento se pasa por alto. La clase
com.ibm.db2.app.UDF contiene variables y mtodos tiles que pueden
utilizarse con una UDF del estilo de parmetro DB2GENERAL. En la tabla
siguiente se describen estas variables y mtodos.
Variables y mtodos Descripcin
public static final int En las UDF escalares, se trata de constantes para
SQLUDF_FIRST_CALL = -1; determinar si la llamada es una primera llamada o
public static final int una llamada normal. En las UDF de tabla, se trata
SQLUDF_NORMAL_CALL = de constantes para determinar si la llamada es una
0; primera llamada, una llamada abierta, una llamada
public static final int de extraccin, una llamada de cierre o una llamada
SQLUDF_TF_FIRST = -2; final.
 Variables y mtodos
public static final int
SQLUDF_TF_OPEN = -1;
public static final int
SQLUDF_TF_FETCH = 0;
public static final int
SQLUDF_TF_CLOSE = 1;
public static final int
SQLUDF_TF_FINAL = 2;
public Connection
getConnection();
public void close();
public boolean isNull(int i)
public void set(int i, short s);
public void set(int i, int j);
public void set(int i, long j);
public void set(int i, double d);
public void set(int i, float f);
public void set(int i,
BigDecimal bigDecimal);
public void set(int i, String
string);
public void set(int i, Blob blob);
public void set(int i, Clob clob);
public boolean needToSet(int i);
public void setSQLstate(String
string);
Descripcin
El mtodo contiene el handle de conexin JDBC
para esta llamada de procedimiento almacenado y
devuelve un objeto JDBC que representa la
conexin de la aplicacin que efecta la llamada
con la base de datos. Es anlogo al resultado de una
llamada a SQLConnect() nula de un procedimiento
almacenado C.
La base de datos llama a este mtodo al final de una
evaluacin de UDF, si la UDF se ha creado con la
opcin FINAL CALL. Es anlogo a la llamada final
de una UDF C. Si una clase Java UDF no
implementa este mtodo, el evento se ignora.
Este mtodo comprueba si un argumento de entrada
con el ndice dado es SQL NULL.
Estos mtodos establecen un argumento de salida en
el valor dado. Se lanza una excepcin si se produce
alguna anomala, incluyendo las siguientes:
La llamada de UDF no progresa
El ndice no hace referencia a un argumento de
salida vlido
El tipo de datos no coincide
La longitud de los datos no coincide
Se produce un error de conversin de pgina de
cdigos
Puede llamarse a este mtodo desde una UDF para
establecer el SQLSTATE que debe devolverse
desde esta llamada. Si la serie no es aceptable como
SQLSTATE, se lanza una excepcin. El usuario
puede establecer SQLSTATE en el programa
externo para que devuelva un error o un aviso desde
la funcin. En este caso, SQLSTATE debe contener
uno de los siguientes elementos:
'00000' para indicar el xito
'01Hxx', donde xx son dos dgitos o letras
maysculas cualesquiera, para indicar un aviso
 Variables y mtodos
public void
setSQLmessage(String string);
public String
getFunctionName();
public String
getSpecificName();
public byte[] getDBinfo();
public String getDBname();
public String getDBauthid();
public String getDBver_rel();
public String getDBplatform();
public String getDBapplid();
public String getDBapplid();
public String getDBtbschema();
public String getDBtbname();
public String getDBcolname();
Descripcin
'38yxx', donde y es una letra mayscula entre 'I' y 'Z'
y xx son dos dgitos o letras maysculas
cualesquiera, para indicar un error
Este mtodo es parecido al mtodo setSQLstate.
Establece el resultado del mensaje SQL. Si la serie
no es aceptable (por ejemplo, es superior a los 70
caracteres), se lanza una excepcin.
Este mtodo devuelve el nombre de la UDF de
proceso.
Este mtodo devuelve el nombre especfico de la
UDF de proceso.
Este mtodo devuelve una estructura DBINFO sin
procesar para la UDF de proceso, como matriz de
bytes. La UDF debe haberse registrado (mediante
CREATE FUNCTION) con la opcin DBINFO.
Estos mtodos devuelven el valor del campo
adecuado de la estructura DBINFO de la UDF de
proceso. La UDF debe haberse registrado (mediante
CREATE FUNCTION) con la opcin DBINFO.
Los mtodos getDBtbschema(), getDBtbname() y
getDBcolname() solo devuelven informacin que
tenga sentido si se ha especificado una funcin
definida por usuario a la derecha de una clusula
SET en una sentencia UPDATE.