|
|
The DataReader object is used to read data that has been retrieved from a database. While the Command and DataAdapter objects are used to issue database commands, the DataReader object is used to read retrieved data values. Once the values are inside this object, several other tasks can be achieved, such as:
Populating a DataSet with retrieved data
Populating a data binding control on a Windows Form or Web Form
Assigning database values to client variables
The DataReader object should be the main interface between client objects and MTOs (Middle Tier Objects) because this object is equipped with some highly optimized functionality for data reading. The following section is a complete reference to the members of the DataReader object.
Type: Integer
Default: 0
Description: This property obtains a valid count of the number of nesting rows for the current row.
Type: Integer
Attribute: Read-only
Default: –1
Description: This property obtains the number of columns present in the current row that is being read.
Type: Boolean
Attribute: Read-only
Default: Null
Description: This property indicates whether the DataReader is closed or opened. It is used mostly to test the availability of data inside the object before issuing instructions to read the data.
Type: The native type of the item
Attribute: Read-only
Default: Null
Description: This property returns the value of the column specified by column_name or column_ordinal of the current row.
Type: Integer
Attribute: Read-only
Default: 0
Description: This property indicates how many records were affected by the execution of an SQL statement or changed on the client. The property returns 0 if there were no affected records or the SQL statement failed. –1 is returned for all SELECT statements.
System.Runtime.Remoting.ObjRef: The returned object contains all the required information to generate a proxy that can communicate with another object residing remotely.
Call this method when you need to reference a valid object that contains all the required information to generate a proxy for the DataReader that will allow it to communicate with another object residing remotely. This method is used if you want the DataReader to communicate with remote objects.
This method will always return False if you pass an object that is not of the same type as the DataReader object. It is useful when you need to test whether two DataReader objects are holding exactly the same values from the same source.
If the column’s type is not Boolean, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the column’s type is not byte, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
i: Integer; an index of the column. The DataReader contains a zero-based column array.
dataIndex: Long; the index within the column from which the method will start reading Byte values into the buffer
buffer(): Byte; an array of type Byte that will hold the stream of byte values to be read
bufferIndex: Integer; the ordinal inside the buffer into which the first Byte value will be read
length: Integer; the maximum number of byte values to copy into the buffer
Char: The value of the specified column at the current row as a Char (single character) value.
If the column’s type is not Char, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
i: Integer; an index of the column. The DataReader contains a zero-based column array.
dataIndex: Long; the index within the column from which the method will start reading Byte values into the buffer
buffer(): Char; an array of type Byte that will hold the stream of Byte values to be read
bufferIndex: Integer; the ordinal inside the buffer into which the first Byte value will be read
length: Integer; the maximum number of Byte values to copy into the buffer
This method obtains the name of the type of column specified by the i parameter. It throws an IndexOutOfRangeException exception if the value specified by i was less than zero or greater than the FieldCount property of the DataReader object.
If the column’s type is not DateTime, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
If the column’s type is not Decimal, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
System.Double: The value of the specified column at the current row as a System.Double object
If the column’s type is not Double, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
This method is used to obtain a valid System.Type value that matches the data type of the field in the database.
System.Single: The value of the specified column at the current row as a System.Single object
If the column’s type is not Single, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
System.Guid: The value of the specified column at the current row as a System.Guid object representing a globally unique identifier value
If the column’s type is not Guid, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
System.Int16: The value of the specified column at the current row as a System.Int16 object (a 16-bit signed integer value)
If the column’s type is not Int16, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
System.Int32: The value of the specified column at the current row as a System.Int32 object (a 32-bit signed integer value)
If the column’s type is not Int32, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
SystemInt64: The value of the specified column at the current row as a System.Int64 object (a 64-bit signed integer value)
If the column’s type is not Int64, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
The GetName() method returns the name of the DataSet component and is useful when you want to refer to a DataSet by its name rather than using a reference variable.
If the name specified is not a valid column name, the method throws an IndexOutOfRangeException exception.
System.Data.DataTable: A DataTable object containing the schema information for the columns of the DataReader
If the column’s type is not Int64, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
If the column’s type is not TimeSpan, the method does not attempt a conversion and throws an InvalidCastException exception. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
System.Object: The value of the specified column at the current row as a System.Object object
If the i parameter is greater than the FieldCount property or less than zero, the method throws an IndexOutOfRangeException exception.
values(): Object; an array of type Object that will hold the stream of Object values to be read
This method is used to obtain a stream of Object values from a column in the DataReader. Be careful to test for a null value using the IsDBNull() method before attempting to read using this method.
Boolean: A Boolean value indicating whether the value at the specified column in the current row is equal to a System.DBNull object. It’s True if the value is null and False otherwise.
Boolean: A Boolean value indicating whether there are any result sets from the current position.
Use this method when dealing with a batch of SQL statements that returned multiple sets of results. If this method returns True, there is a result set, and the method moves the DataReader object to its position.
Boolean: A Boolean value indicating whether there are any rows in the DataReader. If this value is True, the DataReader has more rows and the position is shifted to the next row.
Use this method to test whether there are any rows inside the DataReader object, and move to the next row. The default location of the DataReader is prior to the first row, so you will have to call this method before you attempt any read operation on the DataReader.
| Note |
.NET data providers such as the SQL Server .NET Data Provider provide several optimized methods that are equipped with functionality to read data of the types specific to that particular provider. |
|
|