All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class interbase.interclient.CallableStatement 

java.lang.Object
   |
   +----interbase.interclient.Statement
           |
           +----interbase.interclient.PreparedStatement
                   |
                   +----interbase.interclient.CallableStatement
public final class CallableStatement
extends PreparedStatement
implements CallableStatement

CallableStatement is used to execute SQL stored procedures.

JDBC provides a stored procedure SQL escape that allows stored procedures to be called in a standard way for all RDBMS's. This escape syntax has one form that includes a result parameter and one that does not. If used, the result parameter must be registered as an OUT parameter. The other parameters may be used for input, output or both. Parameters are refered to sequentially, by number. The first parameter is 1.

{?= call [,, ...]}
{call [,, ...]}

IN parameter values are set using the set methods inherited from PreparedStatement. The type of all OUT parameters must be registered prior to executing the stored procedure; their values are retrieved after execution via the get methods provided here.

A Callable statement may return a ResultSet or multiple ResultSets. Multiple ResultSets are handled using operations inherited from Statement.

A call's ResultSets and update counts should be processed prior to getting the values of output parameters.

InterBase does not distinguish between stored procedures which return result sets and those which return "out" parameters. InterBase embedded SQL (supported by the preprocessor gpre) allows for a syntax in which the singleton result set columns from a procedure call may be interpreted as out parameters if the procedure is called using "execute procedure PROC_CALL" rather than "select * from PROC_CALL". But the procedure definition itself is not distinguished as either a "select procedure" or an "executable procedure", it is up to the caller to choose.

Because of this dual semantics for a procedure call, we had to choose which behavior to bestow on the escape syntax {call PROC_CALL (...)}. In order to support InterBase procedures in their generality and to conform to JDBC standards, InterBase stored procedures return all outputs in a result set, never as OUT parameters. So effectively, a CallableStatement is executed in the same way as a PreparedStatement for InterBase.

The following example demonstrates how to prepare and execute an InterBase stored procedure call which returns multiple rows. 

 CallableStatement cs = c.prepareCall ("select * from PROC_CALL (?, ...)");
 ResultSet rs = cs.executeQuery ();
If a stored procedure call is known to return only a single row or no rows at all, then it should be prepared as follows 
 CallableStatement cs = c.prepareCall ("execute procedure PROC_CALL (?, ...)");
 cs.execute ();  // may or may not spawn a singleton result set
 ResultSet rs = cs.getResultSet ();
Finally, the generalized escape syntax 
 CallableStatement cs = c.prepareCall ("{call PROC_CALL (?, ...)}");
 cs.execute ();  // may or may not spawn a result set
 ResultSet rs = cs.getResultSet ();
is a standard notation which may be used for both kinds of procedures, that is, whether or not results are returned. If results are returned, they are returned as a result set.

See Also:
prepareCall, ResultSet

Method Index

o getBigDecimal(int, int)
Get the value of a NUMERIC parameter as a java.math.BigDecimal object.
o getBoolean(int)
Get the value of a BIT parameter as a Java boolean.
o getByte(int)
Get the value of a TINYINT parameter as a Java byte.
o getBytes(int)
Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[].
o getDate(int)
Get the value of a SQL DATE parameter as a java.sql.Date object.
o getDouble(int)
Get the value of a DOUBLE parameter as a Java double.
o getFloat(int)
Get the value of a FLOAT parameter as a Java float.
o getInt(int)
Get the value of an INTEGER parameter as a Java int.
o getLong(int)
Get the value of a BIGINT parameter as a Java long.
o getObject(int)
Get the value of a parameter as a Java object.
o getShort(int)
Get the value of a SMALLINT parameter as a Java short.
o getString(int)
Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.
o getTime(int)
Get the value of a SQL TIME parameter as a java.sql.Time object.
o getTimestamp(int)
Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.
o registerOutParameter(int, int)
Before executing a stored procedure call, you must explicitly call registerOutParameter to register the java.sql.Type of each out parameter.
o registerOutParameter(int, int, int)
Use this version of registerOutParameter for registering Numeric or Decimal out parameters.
o wasNull()
An OUT parameter may have the value of SQL NULL; wasNull reports whether the last value read has this special value.

Methods

o registerOutParameter 
  public void registerOutParameter(int parameterIndex,
                                   int sqlType) throws SQLException
Before executing a stored procedure call, you must explicitly call registerOutParameter to register the java.sql.Type of each out parameter.

Note: When reading the value of an out parameter, you must use the getXXX method whose Java type XXX corresponds to the parameter's registered SQL type.

Parameters:
parameterIndex - the first parameter is 1, the second is 2,...
sqlType - SQL type code defined by java.sql.Types; for parameters of type Numeric or Decimal use the version of registerOutParameter that accepts a scale value
Throws: SQLException
Out parameters not supported.
See Also:
Types
o registerOutParameter 
  public void registerOutParameter(int parameterIndex,
                                   int sqlType,
                                   int scale) throws SQLException
Use this version of registerOutParameter for registering Numeric or Decimal out parameters.

Note: When reading the value of an out parameter, you must use the getXXX method whose Java type XXX corresponds to the parameter's registered SQL type.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
sqlType - use either java.sql.Type.NUMERIC or java.sql.Type.DECIMAL
scale - a value greater than or equal to zero representing the desired number of digits to the right of the decimal point
Throws: SQLException
Out parameters not supported.
See Also:
Types
o wasNull 
  public boolean wasNull() throws SQLException
An OUT parameter may have the value of SQL NULL; wasNull reports whether the last value read has this special value.

Note: You must first call getXXX on a parameter to read its value and then call wasNull() to see if the value was SQL NULL.

Returns:
true if the last parameter read was SQL NULL.
Throws: SQLException
Out parameters not supported.
o getString 
  public String getString(int parameterIndex) throws SQLException
Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is null
Throws: SQLException
Out parameters not supported.
o getBoolean 
  public boolean getBoolean(int parameterIndex) throws SQLException
Get the value of a BIT parameter as a Java boolean.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is false.
Throws: SQLException
Out parameters not supported.
o getByte 
  public byte getByte(int parameterIndex) throws SQLException
Get the value of a TINYINT parameter as a Java byte.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getShort 
  public short getShort(int parameterIndex) throws SQLException
Get the value of a SMALLINT parameter as a Java short.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getInt 
  public int getInt(int parameterIndex) throws SQLException
Get the value of an INTEGER parameter as a Java int.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getLong 
  public long getLong(int parameterIndex) throws SQLException
Get the value of a BIGINT parameter as a Java long.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getFloat 
  public float getFloat(int parameterIndex) throws SQLException
Get the value of a FLOAT parameter as a Java float.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getDouble 
  public double getDouble(int parameterIndex) throws SQLException
Get the value of a DOUBLE parameter as a Java double.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is 0.
Throws: SQLException
Out parameters not supported.
o getBigDecimal 
  public BigDecimal getBigDecimal(int parameterIndex,
                                  int scale) throws SQLException
Get the value of a NUMERIC parameter as a java.math.BigDecimal object.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
scale - a value greater than or equal to zero representing the desired number of digits to the right of the decimal point.
Returns:
the parameter value; if the value is SQL NULL, the result is null.
Throws: SQLException
Out parameters not supported.
o getBytes 
  public byte[] getBytes(int parameterIndex) throws SQLException
Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[].

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is null.
Throws: SQLException
Out parameters not supported.
o getDate 
  public Date getDate(int parameterIndex) throws SQLException
Get the value of a SQL DATE parameter as a java.sql.Date object.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is null.
Throws: SQLException
Out parameters not supported.
o getTime 
  public Time getTime(int parameterIndex) throws SQLException
Get the value of a SQL TIME parameter as a java.sql.Time object.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is null
Throws: SQLException
Out parameters not supported.
o getTimestamp 
  public Timestamp getTimestamp(int parameterIndex) throws SQLException
Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
Returns:
the parameter value; if the value is SQL NULL, the result is null
Throws: SQLException
Out parameters not supported.
o getObject 
  public Object getObject(int parameterIndex) throws SQLException
Get the value of a parameter as a Java object.

This method returns a Java object whose type coresponds to the SQL type that was registered for this parameter using registerOutParameter.

Note that this method may be used to read datatabase-specific, abstract data types. This is done by specifying a targetSqlType of java.sql.types.OTHER, which allows the driver to return a database-specific Java type.

Parameters:
parameterIndex - The first parameter is 1, the second is 2, ...
Returns:
A java.lang.Object holding the OUT parameter value.
Throws: SQLException
Out parameters not supported.
See Also:
Types 
All Packages  Class Hierarchy  This Package  Previous  Next  Index