Routines (alphabetical) > Object Classes > Miscellaneous Object Classes > IDLdbRecordset

# IDLdbRecordset

The IDLdbRecordset object contains a database table or the results from an SQL query.

## Superclasses

None

## Creation

To create a recordset object, a valid database object is required. Use the following IDL DataMinercommand to create a new recordset object:

RSObj = OBJ_NEW('IDLdbRecordset', DBobj, [, N_BUFFERS=integer] [, SQL=string | TABLE=string])

where DBobj is the object reference of the database object and either the SQL or the TABLE property must be specified.

### N_BUFFERS

Set this keyword equal to the number of records to store per database read request in a rapid access memory location. When a IDLdbRecordset object requests records from the datasource it is associated with, the desired records are retrieved from the datasource and cached in the recordset object. The operation to request and transfer the desired records from the datasource can be fairly time consuming, which can impact performance of record access when a large number of records are being requested. Setting this to the optimal number of records can greatly increase IDLdbRecordset::MoveCursor performance and, thus, the overall speed of IDL DataMiner. A higher value is particularly useful, if you are looping through large IDLdbRecordset's with MoveCursor(/NEXT) or MoveCursor(/PREVIOUS) calls. A relatively low value might be called for, if your incremental Dataminer calls are searching for records that are widely dispersed in the target table. The default value is 10 records.

Transferring records from the datasource to the recordset object in a block can drastically increase performance, especially when accessing records in a sequential order. The N_BUFFERS keyword gives the user the ability to modify the size of the block of records the dataminer will transfer from the data sources when a request is being made by the recordset. Increasing the block/buffer size can dramatically increase record access time. You may need to experiment with different values to find the most efficient setting for your application.

### SQL

A string that contains a valid SQL statement that selects records from the database. This SQL statement can be a Stored Procedure call that provides a return value.

Note: If the SQL keyword uses SQL statement syntax unrecognized by the DBMS or the ODBC driver, IDL throws an error that stops execution of the program if not caught and handled by the Dataminer programmer.

Note: If the SQL keyword uses an SQL statement that has acceptable syntax, but returns NULL data (because it has filtered out everything in the table it is referencing), then NO ERROR is thrown. The object returned is a valid IDL object. To determine the object returned was actually an “empty” recordset, you must test the recordset with a subsequent call of:
`result = RSObj->MoveCursor(/FIRST)`
if `result eq 0` (or `result ne 1`), then the recordset returned by OBJ_NEW was an empty (or NULL) recordset.

### TABLE

A string that contains the name of a table in the database. This table must be contained in the database referred to by RSObj.

Note: If the TABLE keyword references a table that does not exist, then IDL throws an error that stops execution of the program if not caught and handled by the Dataminer programmer.

## Properties

Objects of this class have the following properties. See IDLdbRecordset Properties for details on individual properties.

- CAN_MOVE_ABSOLUTE
- CAN_MOVE_FIRST
- CAN_MOVE_LAST
- CAN_MOVE_NEXT
- CAN_MOVE_PRIOR
- CAN_MOVE_RELATIVE
- FIELD_INFO
- GET_DATABASE
- IS_READONLY
- N_BUFFERS
- RECORDSET_SOURCE

## IDLdbRecordset Properties

IDLdbRecordset objects have the following properties in addition to properties inherited from any superclasses. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLdbRecordset::GetProperty. There are no Init or SetProperty methods for the IDLdbRecordset object.

### CAN_MOVE_ABSOLUTE

If True, the cursor for the recordset can move to an absolute record number.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### CAN_MOVE_FIRST

If True, the cursor for the recordset can move to the first record.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### CAN_MOVE_LAST

If True, the cursor for the recordset can move to the last record.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### CAN_MOVE_NEXT

If True, the cursor for the recordset can move to the next record.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### CAN_MOVE_PRIOR

If True, the cursor for the recordset can move to the previous record.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### CAN_MOVE_RELATIVE

If True, the cursor for the recordset can move to a record number relative to the current record number.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### FIELD_INFO

An array of field informational structures, one for each field in the result set. Field information is only available if the current recordset was generated from a table (that is, if the TABLE property was set when creating the recordset object). Information structures have the following fields (see the ODBC Manual for more information):

- TABLE_QUALIFIER: The table qualifier.
- TABLE_OWNER: The name of the table owner.
- TABLE_NAME: The name of the table.
- FIELD_NAME: The name of the field.
- TYPE_NAME: The datasource type name.
- PRECISION: Precision of the field.
- LENGTH: Length in bytes of the data.
- SCALE: The scale of the field.
- IS_NULLABLE: The field can contain null values.
- IS_AUTOINCREMENT: The field is an autoincrement field.
- IS_CASE_SENSITIVE: The value of the field is case sensitive.
- IS_UPDATABLE: The field can be updated.
- IDL_TYPE: The IDL DataMiner type to which the field is mapped.

If a field is returned empty, this indicates that the driver doesn’t support the query for that particular information.

Property Type | Array of structures
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### GET_DATABASE

An object reference to the database object used when the current recordset object was created.

Property Type | Object reference
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### IS_READONLY

If True, the table is read-only.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### N_BUFFERS

The number of buffers allocated for the recordset.

Property Type | Integer
Name String | not displayed
Get: Yes | Set: No | Init: Yes | Registered: No

### RECORDSET_SOURCE

A string containing either the table name or SQL statement used to create the recordset.

Property Type | String
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

## Methods

- IDLdbRecordset::AddRecord
- IDLdbRecordset::Cleanup
- IDLdbRecordset::CurrentRecord
- IDLdbRecordset::DeleteRecord
- IDLdbRecordset::GetField
- IDLdbRecordset::GetProperty
- IDLdbRecordset::GetRecord
- IDLdbRecordset::Init
- IDLdbRecordset::MoveCursor
- IDLdbRecordset::NFields
- IDLdbRecordset::SetField

## Version History

5.0 | Introduced