OracleParameter Class

OracleParameter()

This constructor instantiates a new instance of OracleParameter class.

Declaration

// C#
public OracleParameter();

Remarks

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType)

This constructor instantiates a new instance of OracleParameter class using the supplied parameter name and Oracle data type.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType oraType);

Parameters

• parameterName

  The parameter name.

• oraType

  The data type of the OracleParameter.

Remarks

Changing the DbType implicitly changes the OracleDbType.

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, object)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name and parameter value.

Declaration

// C#
public OracleParameter(string parameterName, object obj);

Parameters

• parameterName

  The parameter name.

• obj

  The value of the OracleParameter.

Remarks

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, ParameterDirection)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, and parameter direction.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType type,
   ParameterDirection direction);

Parameters

• parameterName

  The parameter name.

• type

  The data type of the OracleParameter.

• direction

  The direction of the OracleParameter.

Remarks

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, object, ParameterDirection)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, value, and direction.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType type, object obj, 
   ParameterDirection direction);

Parameters

• parameterName

  The parameter name.

• type

  The data type of the OracleParameter.

• obj

  The value of the OracleParameter.

• direction

  The ParameterDirection value.

Remarks

Changing the DbType implicitly changes the OracleDbType.

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, int)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, and size.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType type,
   int size);

Parameters

• parameterName

  The parameter name.

• type

  The data type of the OracleParameter.

• size

  The size of the OracleParameter value.

Remarks

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, int, string)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, size, and source column.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType type, int size, 
  string srcColumn);

Parameters

• parameterName

  The parameter name.

• type

  The data type of the OracleParameter.

• size

  The size of the OracleParameter value.

• srcColumn

  The name of the source column.

Remarks

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, int, ParameterDirection, bool, byte, byte, string, DataRowVersion, object)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, size, direction, null indicator, precision, scale, source column, source version and parameter value.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType oraType, 
   int size, ParameterDirection direction, bool isNullable, byte
   precision, byte scale,  string srcColumn, DataRowVersion srcVersion,
   object obj);

Parameters

• parameterName

  The parameter name.

• oraType

  The data type of the OracleParameter.

• size

  The size of the OracleParameter value.

• direction

  The ParameterDirection value.

• isNullable

  An indicator that specifies if the parameter value can be null.

• precision

  The precision of the parameter value.

• scale

  The scale of the parameter value.

• srcColumn

  The name of the source column.

• srcVersion

  The DataRowVersion value.

• obj

  The parameter value.

Exceptions

ArgumentException - The supplied value does not belong to the type of Value property in any of the OracleTypes.

Remarks

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

OracleParameter(string, OracleDbType, int, object, ParameterDirection)

This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, data type, size, value, and direction.

Declaration

// C#
public OracleParameter(string parameterName, OracleDbType type, int size, 
   object obj, ParameterDirection direction);

Parameters

• parameterName

  The parameter name.

• type

  The data type of the OracleParameter.

• size

  The size of the OracleParameter value.

• obj

  The value of the OracleParameter.

• direction

  The ParameterDirection value.

Remarks

Changing the DbType implicitly changes the OracleDbType.

Unless explicitly set in the constructor, all the properties have the default values.

Default Values:

• DbType - String

• ParameterDirection - Input

• isNullable - true

• offset - 0

• OracleDbType - Varchar2

• ParameterAlias - Empty string

• ParameterName - Empty string

• Precision - 0

• Size - 0

• SourceColumn - Empty string

• SourceVersion - Current

• ArrayBindStatus - Success

• Value - null

ArrayBindSize

This property specifies the maximum size, in bytes or characters, of the data for each array element transmitted to or from the database. This property is used for Array Bind or PL/SQL Associative Array execution.

Declaration

// C#
public int[] ArrayBindSize {get; set; }

Property Value

An array of int values specifying the size.

Remarks

Default = null.

This property is only used for variable size element types for an Array Bind or PL/SQL Associative Array. For fixed size element types, this property is ignored.

Each element in the ArrayBindSize corresponds to the bind size of an element in the Value property. Before execution, ArrayBindSize specifies the maximum size of each element to be bound in the Value property. After execution, it contains the size of each element returned in the Value property.

For binding a PL/SQL Associative Array, whose elements are of a variable-length element type, as an InputOutput, Out, or ReturnValue parameter, this property must be set properly. The number of elements in ArrayBindSize must be equal to the value specified in the OracleParameter.Size property.

Example

// C#
 
using System;
using System.Data;
using Oracle.DataAccess.Client;
 
class ArrayBindSizeSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleParameter[] prm = new OracleParameter[3];
 
    // Create OracleParameter objects through OracleParameterCollection
    OracleCommand cmd = con.CreateCommand();
 
    cmd.CommandText = "select max(empno) from emp";
    int maxno = int.Parse(cmd.ExecuteScalar().ToString());
 
    // Set the ArrayBindCount for Array Binding
    cmd.ArrayBindCount = 2;
 
    prm[0] = cmd.Parameters.Add("paramEmpno", OracleDbType.Decimal, 
      new int[2] {maxno + 10, maxno + 11}, ParameterDirection.Input);
    prm[1] = cmd.Parameters.Add("paramEname", OracleDbType.Varchar2, 
      new string[2] {"Client1xxx", "Client2xxx"}, ParameterDirection.Input);
    prm[2] = cmd.Parameters.Add("paramDeptNo", OracleDbType.Decimal, 
      new int[2] {10, 10}, ParameterDirection.Input);
 
    // Set the ArrayBindSize for prm[1]
    // These sizes indicate the maximum size of the elements in Value property
    prm[1].ArrayBindSize = new int[2];
    prm[1].ArrayBindSize[0] = 7; // Set ename = "Client1"
    prm[1].ArrayBindSize[1] = 7; // Set ename = "Client2"
 
    cmd.CommandText = 
      "insert into emp(empno, ename, deptno) values(:1, :2, :3)";
 
    cmd.ExecuteNonQuery();
 
    Console.WriteLine("Record for employee id {0} has been inserted.", 
      maxno + 10);
    Console.WriteLine("Record for employee id {0} has been inserted.", 
      maxno + 11);
 
    prm[0].Dispose();
    prm[1].Dispose();
    prm[2].Dispose();
    cmd.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

ArrayBindStatus

This property specifies the input or output status of each element in the Value property before or after an Array Bind or PL/SQL Associative Array execution.

Declaration

// C#
public OracleParameterStatus[] ArrayBindStatus { get; set; }

Property Value

An array of OracleParameterStatus enumerated values.

Exceptions

ArgumentOutofRangeException - The Status value specified is invalid.

Remarks

Default = null.

ArrayBindStatus is used for Array Bind and PL/SQL Associative Array execution only.

Before execution, ArrayBindStatus indicates the bind status of each element in the Value property. After execution, it contains the execution status of each element in the Value property.

CollectionType

This property specifies whether or not the OracleParameter represents a collection, and if so, specifies the collection type.

Declaration

// C#
public OracleCollectionType CollectionType { get; set; }

Property Value

An OracleCollectionType enumerated value.

Exceptions

ArgumentException - The OracleCollectionType value specified is invalid.

Remarks

Default = OracleCollectionType.None. If OracleParameter is used to bind a PL/SQL Associative Array, then CollectionType must be set to OracleCollectionType.PLSQLAssociativeArray.

DbType

This property specifies the data type of the parameter using the Data.DbType enumeration type.

Declaration

// C#
public override DbType DbType {get; set; }

Property Value

A DbType enumerated value.

Implements

IDataParameter

Exceptions

ArgumentException - The DbType value specified is invalid.

Remarks

Default = DbType.String

DbType is the data type of each element in the array if the OracleParameter object is used for Array Bind or PL/SQL Associative Array Bind execution.

Due to the link between DbType and OracleDbType properties, if the DbType property is set, the OracleDbType property is inferred from DbType.

Direction

This property specifies whether the parameter is input-only, output-only, bi-directional, or a stored function return value parameter.

Declaration

// C#
public override ParameterDirection Direction { get; set; }

Property Value

A ParameterDirection enumerated value.

Implements

IDataParameter

Exceptions

ArgumentOutOfRangeException - The ParameterDirection value specified is invalid.

Remarks

Default = ParameterDirection.Input

Possible values: Input, InputOutput, Output, and ReturnValue.

IsNullable

This property is not supported.

Declaration

// C#
public override bool IsNullable { get; set; }

Implements

IDataParameter

Property Value

This property is not supported.

Offset

This property specifies the offset to the Value property.

Declaration

// C#
public int Offset { get; set; }

Property Value

An int that specifies the offset.

Exceptions

ArgumentOutOfRangeException - The Offset value specified is invalid.

Remarks

Default = 0

For Array Bind and PL/SQL Associative Array Bind, Offset applies to every element in the Value property.

The Offset property is used for binary and string data types. The Offset property represents the number of bytes for binary types and the number of characters for strings. The count for strings does not include the terminating character if a null is referenced. The Offset property is used by parameters of the following types:

• OracleDbType.BFile

• OracleDbType.Blob

• OracleDbType.LongRaw

• OracleDbType.Raw

• OracleDbType.Char

• OracleDbType.Clob

• OracleDbType.NClob

• OracleDbType.NChar

• OracleDbType.NVarchar2

• OracleDbType.Varchar2

OracleDbType

This property specifies the Oracle data type.

Declaration

// C#
public OracleDbType OracleDbType { get; set; }

Property Value

An OracleDbType enumerated value.

Remarks

Default = OracleDbType.Varchar2

If the OracleParameter object is used for Array Bind or PL/SQL Associative Array Bind execution, OracleDbType is the data type of each element in the array.

The OracleDbType property and DbType property are linked. Therefore, setting the OracleDbType property changes the DbType property to a supporting DbType.

OracleDbTypeEx

This property specifies the Oracle data type to bind the parameter as, but returns a .NET type as output.

Declaration

// C#
public OracleDbType OracleDbTypeEx { get; set; }

Property Value

An OracleDbType enumerated value.

Remarks

This property is used by applications that need to bind a parameter value as an Oracle type, but need a .NET type back for output. This property should be used with an output or input/output parameter. For an input parameter, using OracleDbTypeEx has the same affect as using OracleDbType. The .NET type that is returned for the output is the .NET type that the Oracle type closely maps to.

ParameterName

This property specifies the name of the parameter.

Declaration

// C#
public override string ParameterName { get; set; }

Property Value

String

Implements

IDataParameter

Remarks

Default = null

Oracle supports ParameterName up to 30 characters.

Precision

This property specifies the maximum number of digits used to represent the Value property.

Declaration

// C#
Public byte Precision { get; set; }

Property Value

byte

Remarks

Default = 0

The Precision property is used by parameters of type OracleDbType.Decimal.

Oracle supports Precision range from 0 to 38.

For Array Bind and PL/SQL Associative Array Bind, Precision applies to each element in the Value property.

Scale

This property specifies the number of decimal places to which Value property is resolved.

Declaration

// C#
public byte Scale { get; set; }

Property Value

byte

Remarks

Default = 0.

Scale is used by parameters of type OracleDbType.Decimal.

Oracle supports Scale between -84 and 127.

For Array Bind and PL/SQL Associative Array Bind, Scale applies to each element in the Value property.

Size

This property specifies the maximum size, in bytes or characters, of the data transmitted to or from the database.

Declaration

// C#
public override int Size { get; set;}

Property Value

int

Exceptions

ArgumentOutOfRangeException - The Size value specified is invalid.

InvalidOperationException - The Size = 0 when the OracleParameter object is used to bind a PL/SQL Associative Array.

Remarks

For PL/SQL Associative Array Bind, Size specifies the maximum number of elements in PL/SQL Associative Array.

If Size is not explicitly set, it is inferred from the actual size of the specified parameter value when binding only for input parameters. Output parameters must have their size defined explicitly.

The default value is 0.

Before execution, this property specifies the maximum size to be bound in the Value property. After execution, it contains the size of the type in the Value property.

Size is used for parameters of the following types:

• OracleDbType.Blob

• OracleDbType.Char

• OracleDbType.Clob

• OracleDbType.LongRaw

• OracleDbType.NChar

• OracleDbType.NClob

• OracleDbType.NVarchar2

• OracleDbType.Raw

• OracleDbType.Varchar2

The value of Size is handled as follows:

• Fixed length data types: ignored

• Variable length data types: describes the maximum amount of data transmitted to or from the database. For character data, Size is in number of characters and for binary data, it is in number of bytes.

If the Size is not explicitly set, it is inferred from the actual size of the specified parameter value when binding.

If the OracleParameter object is used to bind a PL/SQL Associative Array, Size specifies the maximum number of elements in the PL/SQL Associative Array. Before the execution, this property specifies the maximum number of elements in the PL/SQL Associative Array. After the execution, it specifies the current number of elements returned in the PL/SQL Associative Array. For Output and InputOutput parameters and return values, Size specifies the maximum number of elements in the PL/SQL Associative Array.

ODP.NET does not support binding an empty PL/SQL Associative Array. Therefore, Size cannot be set to 0 when the OracleParameter object is used to bind a PL/SQL Associative Array.

SourceColumn

This property specifies the name of the DataTable Column of the DataSet.

Declaration

// C#
public override string SourceColumn { get; set; }

Property Value

A string.

Implements

IDataParameter

Remarks

Default = empty string

SourceColumnNullMapping

This property specifies a value which indicates whether the source column is nullable.

Declaration

// C#
public bool SourceColumnNullMapping { get; set; }

Property Value

Returns true if the source column can be nullified; otherwise, returns false.

Remarks

The default value is false.

SourceVersion

This property specifies the DataRowVersion value to use when loading the Value property of the parameter.

Declaration

// C#
public override DataRowVersion SourceVersion { get; set; }

Property Value

DataRowVersion

Implements

IDataParameter

Exceptions

ArgumentOutOfRangeException - The DataRowVersion value specified is invalid.

Remarks

Default = DataRowVersion.Current

SourceVersion is used by the OracleDataAdapter.UpdateCommand() during the OracleDataAdapter.Update to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the OracleDataAdapter.InsertCommand() and the OracleDataAdapter.DeleteCommand().

Status

This property indicates the status of the execution related to the data in the Value property.

Declaration

// C#
public OracleParameterStatus Status { get; set; }

Property Value

An OracleParameterStatus enumerated value.

Exceptions

ArgumentOutOfRangeException - The Status value specified is invalid.

Remarks

Default = OracleParameterStatus.Success

Before execution, this property indicates the bind status related to the Value property. After execution, it returns the status of the execution.

Status indicates if:

• A NULL is fetched from a column.

• Truncation has occurred during the fetch; then Value was not big enough to hold the data.

• A NULL is to be inserted into a database column; then Value is ignored, and a NULL is inserted into a database column.

  This property is ignored for Array Bind and PL/SQL Associative Array Bind. Instead, ArrayBindStatus property is used.

UdtTypeName

This property specifies the Oracle user-defined type name if the parameter is a user-defined data type.

Declaration

// C#
public string UdtTypeName {get; set;}

Property Value

Name of the Oracle UDT.

Remarks

The UdtTypeName property corresponds to the user-defined type name of the parameter. This property must always be specified if the parameter is a user-defined type. Note that when a custom object is provided as an input parameter value, it is converted to the Oracle UDT that is specified by the custom type mapping on the connection used to execute the command.The Oracle UDT specified by the custom type mapping and by the OracleParamter.UdtTypeName property differs if the application binds a custom object that represents a subtype of the parameter type.

Value

This property specifies the value of the Parameter.

Declaration

// C#
public override object Value { get; set; }

Property Value

An object.

Implements

IDataParameter

Exceptions

ArgumentException - The Value property specified is invalid.

InvalidArgumentException- The Value property specified is invalid.

Remarks

Default = null

If the OracleParameter object is used for Array Bind or PL/SQL Associative Array, Value is an array of parameter values.

The Value property can be overwritten by OracleDataAdapter.Update().

The provider attempts to convert any type of value if it supports the IConvertible interface. Conversion errors occur if the specified type is not compatible with the value.

When sending a null parameter value to the database, the user must specify DBNull, not null. The null value in the system is an empty object that has no value. DBNull is used to represent null values. The user can also specify a null value by setting Status to OracleParameterStatus.NullValue. In this case, the provider sends a null value to the database.

If neither OracleDbType nor DbType are set, their values can be inferred by Value. Please see the following for related information:

• Tables in section "Inference of DbType and OracleDbType from Value"

• "ArrayBindCount"

• "ArrayBindSize"

• "ArrayBindStatus"

• "OracleDbType Enumeration"

For input parameters the value is:

• Bound to the OracleCommand that is sent to the database.

• Converted to the data type specified in OracleDbType or DbType when the provider sends the data to the database.

For output parameters the value is:

• Set on completion of the OracleCommand (true for return value parameters also).

• Set to the data from the database, to the data type specified in OracleDbType or DbType.

When array binding is used with:

• Input parameter - Value should be set to an array of values. OracleCommand.ArrayBindCount should be set to a value that is greater than zero to indicate the number of elements to be bound.

  The number of elements in the array should be equal to the OracleCommand.ArrayBindCount property; otherwise, their minimum value is used to bind the elements in the array.

• Output parameter - OracleCommand.ArrayBindCount should be set to a value that is greater than zero to indicate the number of elements to be retrieved (for SELECT statements).

When PL/SQL Associative Array binding is used with:

• Input parameter – Value should be set to an array of values. CollectionType should be set to OracleCollection.PLSQLAssociativeArray.Size should be set to specify the possible maximum number of array elements in the PL/SQL Associative Array. If Size is smaller than the number of elements in Value, then Size specifies the number of elements in the Value property to be bound.

• Output parameter - CollectionType should be set to OracleCollection.PLSQLAssociativeArray. Size should be set to specify the maximum number of array elements in PL/SQL Associative Array.

Each parameter should have a value. To bind a parameter with a null value, set Value to DBNull.Value, or set Status to OracleParameterStatus. NullInsert.

Clone

This method creates a shallow copy of an OracleParameter object.

Declaration

// C#
public object Clone();

Return Value

An OracleParameter object.

Implements

ICloneable

Remarks

The cloned object has the same property values as that of the object being cloned.

Example

// C#
 
using System;
using System.Data;
using Oracle.DataAccess.Client; 
 
class CloneSample
{
  static void Main()
  {  
    OracleParameter prm1 = new OracleParameter();
 
    // Prints "prm1.ParameterName = "
    Console.WriteLine("prm1.ParameterName = " + prm1.ParameterName);
 
    // Set the ParameterName before cloning
    prm1.ParameterName = "MyParam";
 
    // Clone the OracleParameter
    OracleParameter prm2 = (OracleParameter) prm1.Clone();
 
    // Prints "prm2.ParameterName = MyParam"
    Console.WriteLine("prm2.ParameterName = " + prm2.ParameterName);
 
    prm1.Dispose();
    prm2.Dispose();
  }
}

Dispose

This method releases resources allocated for an OracleParameter object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

ResetDbType

This method resets the type associated with the parameter so that it can infer its type from the value passed in the parameter.

Declaration

// C#
public override void ResetDbType();

Remarks

If an application does not set the DbType or OracleDbType properties of an OracleParameter object, then these values are inferred from the value set by the application to that OracleParameter object. Calling ResetDbType method resets these properties so that OracleParameter can again infer its type from the value passed into the OracleParameter. Calling this method affects both the DbType and OracleDbType properties of the OracleParameter object.

ResetOracleDbType

This method resets the type associated with the parameter so that it can infer its type from the value passed in the parameter.

Declaration

// C#
public override void ResetOracleDbType();

Remarks

If an application does not set the DbType or OracleDbType properties of an OracleParameter object, then these values are inferred from the value set by the application to that OracleParameter object. Calling the ResetOracleDbType method resets these properties so that OracleParameter can again infer its type from the value passed into the OracleParameter. Calling this method affects both the DbType and OracleDbType properties of the OracleParameter object.

ToString

Overrides Object

This method returns the string representation of the current instance.

Declaration

// C#
public override string ToString();

Return Value

Returns the OracleParameter value in a string representation.

Remarks

If the current instance has a null value, the returned string is null.