com.ibm.db.beans
Class DBParameterMetaData

java.lang.Object
  |
  +--com.ibm.db.beans.DBParameterMetaData
All Implemented Interfaces:
java.io.Serializable

public class DBParameterMetaData
extends java.lang.Object
implements java.io.Serializable

This class allows you to get and set meta-data about the parameters for a DBSelect, DBProcedureCall, or DBModify bean.

You must describe and set any parameters before actually executing a statement.

There is no public constructor for DBParameterMetaData. A DBStatement is created with a DBParameterMetaData, which you can get with getParameterMetaData().

Convenience methods are provided that allow you specify multiple characteristics at once for a parameter not previously described. (setParameter) Or you can just call individual methods to set one characteristic of a parameter at a time. You can use these same more granular methods to change a description you have previously provided. You can describe parameters in any order. The position of the parameter in the result set is determined by the index used to call the methods that describe it.

See Also:
Serialized Form

Method Summary
 void clear()
          Clears the descriptions of all parameters for this statement.
 java.lang.Class getParameterClass(int position)
          Gets the Java class to be used when getting or setting values for the parameter at the specified position.
 int getParameterCount()
          Gets the number of parameters in the SQL statement.
 int getParameterMode(int position)
          Gets the mode of the parameter at the specified position.
 java.lang.String getParameterName(int position)
          Gets the name of the parameter at the specified position.
 int getParameterNumber(java.lang.String name)
          Gets the number of a parameter based on its name.
 int getParameterScale(int position)
          Gets the number of digits to the right of the decimal point.
 int getParameterType(int position)
          Gets the SQL type of the parameter at the specified position.
 com.ibm.db.beans.DBStatement getStatement()
          Gets the DBStatement object that this object describes.
 void setParameter(int position, java.lang.String name, int mode, int sqlType, java.lang.Class aClass)
          Add the definition of a new parameter to this bean.
 void setParameterClass(int position, java.lang.Class aClass)
          Sets the Java class to be used when getting or setting values for this parameter.
 void setParameterMode(int position, int mode)
          Sets the mode of the parameter at the specified position.
 void setParameterName(int position, java.lang.String aName)
          Sets the name of the parameter at the specified position.
 void setParameterScale(int position, int scale)
          Sets the number of digits to the right of the decimal point for this parameter.
 void setParameterType(int position, int type)
          Sets the SQL type of the parameter at the specified position.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

clear

public void clear()
Clears the descriptions of all parameters for this statement.

See Also:
setParameter(int, java.lang.String, int, int, java.lang.Class)

getParameterClass

public java.lang.Class getParameterClass(int position)
                                  throws DBException
Gets the Java class to be used when getting or setting values for the parameter at the specified position. The position of the first parameter is 1.

Parameters:
position - the parameter number
Returns:
the Java class
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
See Also:
setParameterClass(int, java.lang.Class)

getParameterCount

public int getParameterCount()
Gets the number of parameters in the SQL statement. If information has been specified sparsely (for only some parameters) in this bean, the value returned is the number of the last parameter for which information has been specified.

Returns:
the number of parameters

getParameterMode

public int getParameterMode(int position)
                     throws DBException
Gets the mode of the parameter at the specified position. The position of the first parameter is 1. Modes are identified using constants defined in DatabaseMetaData, including: procedureColumnIn, procedureColumnInOut, procedureColumnOut, and procedureColumnResult.

Parameters:
position - the parameter number
Returns:
mode from java.sql.DatabaseMetaData
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position

getParameterName

public java.lang.String getParameterName(int position)
                                  throws DBException
Gets the name of the parameter at the specified position. The position of the first parameter is 1.

This bean allows you to specify names for parameters, and methods of DBSelect, DBModify, and DBProcedureCall can access parameters by these names. Each parameter name is guaranteed to be unique within this bean.

Your SQL statement can be written using '?' to represent a parameter, or using a host variable syntax like ':myParamName'.

Parameters:
position - the parameter number
Returns:
parameter name
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
See Also:
setParameterName(int, java.lang.String)

getParameterNumber

public int getParameterNumber(java.lang.String name)
                       throws DBException
Gets the number of a parameter based on its name. The number of the first parameter is 1.

Parameters:
name - the name of the parameter
Returns:
the parameter number
Throws:
DBException - parameterNotDefined - if no parameter has been defined with this name
See Also:
getParameterName(int)

getParameterScale

public int getParameterScale(int position)
                      throws DBException
Gets the number of digits to the right of the decimal point. The index of the first column is 1. This value is only used for parameters whose SQL type is decimal.

Returns:
the parameter scale
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
SQLException - if a database access error occurs
See Also:
setParameterScale(int, int)

getParameterType

public int getParameterType(int position)
                     throws DBException
Gets the SQL type of the parameter at the specified position. The position of the first parameter is 1.

Parameters:
position - the parameter number
Returns:
SQL type from java.sql.Types
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
See Also:
Types, setParameterType(int, int)

getStatement

public com.ibm.db.beans.DBStatement getStatement()
Gets the DBStatement object that this object describes.

The statement property of this object is read-only. This object is created by the DBStatement it describes, and remains associated with that statement for its lifetime.

Returns:
DBStatement

setParameter

public void setParameter(int position,
                         java.lang.String name,
                         int mode,
                         int sqlType,
                         java.lang.Class aClass)
                  throws DBException
Add the definition of a new parameter to this bean. This is a convenience method that allows you specify multiple characteristics of the parameter at once rather than separately calling several other methods to set them.

When you call this method, there must be no parameter currently defined in the position you specify. The index of the first parameter is 1.

The characteristics you can specify are those you would specify via the methods setParameterName, setParameterMode, setParameterType, and setParameterClass.

Parameters:
position - the parameter number
name - the parameter name String, may be null
mode - the parameter mode
aClass - the java class to be used for parameter values
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
DBException - parameterAlreadyDefined - if a parameter is already defined at the specified position
DBException - duplicateParm - if a parameter with this name has already been defined
See Also:
setParameterName(int, java.lang.String), setParameterMode(int, int), setParameterType(int, int), setParameterClass(int, java.lang.Class)

setParameterClass

public void setParameterClass(int position,
                              java.lang.Class aClass)
                       throws DBException
Sets the Java class to be used when getting or setting values for this parameter. The index of the first parameter is 1.

Parameters:
position - the parameter number
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
See Also:
getParameterClass(int)

setParameterMode

public void setParameterMode(int position,
                             int mode)
                      throws DBException
Sets the mode of the parameter at the specified position. The position of the first parameter is 1.

Valid modes are those for which constants are defined in DatabaseMetaData, including: procedureColumnIn, procedureColumnInOut, procedureColumnOut, and procedureColumnResult.

Parameters:
position - the parameter number
mode - parameter mode
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
See Also:
getParameterMode(int), DatabaseMetaData

setParameterName

public void setParameterName(int position,
                             java.lang.String aName)
                      throws DBException
Sets the name of the parameter at the specified position. The position of the first parameter is 1.

Parameters:
position - the parameter number
aName - parameter name
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
DBException - duplicateParm - if a parameter with this name has already been defined
See Also:
getParameterName(int)

setParameterScale

public void setParameterScale(int position,
                              int scale)
                       throws DBException
Sets the number of digits to the right of the decimal point for this parameter. The position of the first parameter is 1.

Parameters:
position - the parameter number
scale - parameter scale
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
See Also:
getParameterScale(int), DatabaseMetaData

setParameterType

public void setParameterType(int position,
                             int type)
                      throws DBException
Sets the SQL type of the parameter at the specified position. The position of the first parameter is 1.

Parameters:
position - the parameter number
type - parameter SQL type
Throws:
DBException - invalidParameterNumber - if parameter number is invalid (less than 1)
See Also:
getParameterType(int)