ProcedureReference

The ProcedureReference interface provides a way to invoke a procedure and fetch its output values. It also provides metadata information for the procedure parameters.

public interface ProcedureReference

ProcedureReference is a parent interface for the CustomProcedure interface. It is also used as the return type when looking up a procedure from the query engine.

The type of each Java object must be the default Java object type corresponding to the input or output parameter’s SQL type, following the mapping for built-in types specified in the JDBC specification (per the getObject method on java.sql.ResultSet).

Method Summary
void	cancel
void	close
int	getNumAffectedRows
Object	getOutputValue
Object[]	getOutputValues
ParameterInfo[]	getParameterInfo
void	invoke

Method Detail

cancel

void cancel()

This method cancels the procedure reference and any underlying cursors and statements.

 

close

public void close()

The implementation of this method should close all open cursors and all independent transactions that this method has created.

This method is called when a procedure reference is no longer needed. It is possible to call this method concurrently with any other call such as invoke or getOutputValues, but when called concurrently with another call, this method should cause a CustomProcedureException.

 

getNumAffectedRows

public int getNumAffectedRows()

This method retrieves the number of rows that were inserted, updated, or deleted during the execution of a procedure.

Returns

A return value of -1 indicates that the number of affected rows is unknown.

Throws

This method throws CustomProcedureException, or SQLException if an error occurs when getting the number of affected rows.

 

getOutputValue

public Object[] getOutputValue (int index)

This method retrieves the output value at the given index.

Returns

This method returns a procedure’s output value at a given index. An output cursor can be returned as either CustomCursor, or java.sql.ResultSet. The returned objects should comply with the Java-to-SQL typing conventions listed in Types.

This method should not return NULL.

Throws

This method throws CustomProcedureException, or SQLException if an error occurs when getting the output value. This method throws ArrayIndexOutOfBoundsException if the index value is out of bounds.

 

getOutputValues

public Object[] getOutputValues()

This method retrieves output values.

Returns

This method returns a procedure’s output values as either CustomCursor or java.sql.ResultSet. The returned objects should comply with the Java-to-SQL typing conventions listed in Types.

This method should not return NULL.

Throws

This method throws CustomProcedureException, or SQLException if an error occurs when getting the output values.

 

Types

The getOutputValues, method of the ProcedureReference, interface retrieves the output values in a procedure. The returned objects should comply with the Java-to-SQL typing conventions as defined in this section.

The type of each Java object must be the default Java object type corresponding to the input or output parameter’s TDV JDBC data type, following the mapping for built-in types specified in the JDBC specification (per the getObject method on java.sql.ResultSet).

The following table maps the Java object types to TDV JDBC data types.

Java Object Type	TDV JDBC Data Type
byte[]	BINARY, VARBINARY, or LONGVARBINARY
java.lang.Boolean	BIT or BOOLEAN
java.lang.Double	DOUBLE
java.lang.Float	REAL or FLOAT
java.lang.Integer	INTEGER, SMALLINT, or TINYINT
java.lang.Long	BIGINT
java.lang.String	CHAR, VARCHAR, or LONGVARCHAR
java.math.BigDecimal	NUMERIC or DECIMAL
java.sql.Blob	BLOB
java.sql.Clob	CLOB
java.sql.Date	DATE
java.sql.Time	TIME
java.sql.TimeStamp	TIMESTAMP

Special Types and Value

If the input or output parameter type is XML_STRING, the Java object type should be java.lang.String.

If the parameter type is TYPED_CURSOR or GENERIC_CURSOR, the Java object type is always java.sql.ResultSet for input parameters, and can be either CustomCursor, or java.sql.ResultSet for output parameters.

If the value is a SQL NULL, the procedure returns a Java NULL.

Hierarchical Data

This interface is primarily designed around tabular data. A stored procedure that has hierarchical input or output should accept or return one or more scalar parameters that contain XML string data. For methods that use java.sql.Types, the constant XML_STRING, should be used for hierarchical XML data.

Cursors

The types TYPED_CURSOR, and GENERIC_CURSOR, are used to pass in and out cursor values. A typed cursor has a schema. A generic cursor’s schema is resolved at run time. Procedures with generic cursor outputs cannot be used in SQL.

getParameterInfo

public ParameterInfo[] getParameterInfo()

This method is called during introspection to get the description of the procedure’s input and output parameters. This method should not return NULL.

Returns

This method returns the description of the procedure’s input and output parameters.

 

invoke

public void invoke(Object[] inputValues)

This method is called to invoke a procedure. It is called only once per procedure instance.

Parameter

inputValues—Values for the input parameters. Must not be NULL.

Throws

This method throws CustomProcedureException, or SQLException if an error occurs during invocation.