The AbsolutePage property returns or sets a value that indicates the current page in the recordset.

Long

By setting the AbsolutePage property, you are instructing ADO to move the record pointer to the first record within the page that you specified. The AbsolutePage property can be set from 1 to the number returned by the PageCount property, which is the total number of logical pages. The size of each page is determined by the PageSize property.

By reading the AbsolutePage property, you can determine in which logical page the record pointer is located. The AbsolutePage property can return a Long value indicating the current page or a PositionEnum value.

If when reading the AbsolutePage property, the record pointer is pointing to the BOF marker, then the value adPosBOF (-2) is returned. If the record pointer is at the EOF marker, then the adPosEOF (-3) value is returned. If the recordset is empty, if the record pointer's position is unknown or if the data provider does not support the AbsolutePage property, then the value adPosUnknown (-1) is returned.

The AbsolutePage property is 1-based, meaning that a value of 1 indicates the first page in the recordset.

Not all providers support the AbsolutePage property.

CursorOptionEnum Enumeration, PositionEnum Enumeration, Recordset.Count Property, Recordset.Filter Property, Recordset.PageSize Property, Recordset.Supports Method

The AbsolutePosition property returns or sets a value that indicates the current record position within the recordset.

Long

By setting the AbsolutePosition property, you are instructing ADO to move to the record with the ordinal position that you specified. The AbsolutePosition property can be set from 1 to the number returned by the RecordCount property, which is the total number of records in the recordset.

When you set the AbsolutePosition property, ADO reloads the cache with a new set of records, the first one of which is the record that you specify. The number of records that are loaded in the cache is determined by the CacheSize property.

By reading the AbsolutePosition property, you can determine at which ordinal position the record pointer is located by the Long or the PositionEnum value.

If, when reading the AbsolutePosition property, the record pointer is pointing to the BOF marker, then the value adPosBOF (-2) is returned. If the record pointer is at the EOF marker, then the adPosEOF (-3) value is returned. If the recordset is empty, if the record pointer's position is unknown, or if the data provider does not support the AbsolutePosition property, then the value adPosUnknown (-1) is returned.

It is important to note that the AbsolutePosition can change in the event that a previous record is deleted or even if the recordset is required. I recommend using bookmarks to keep track of records by position.

The AbsolutePosition property is 1-based, meaning that the value 1 indicates the first record in the recordset.

Not all providers support the AbsolutePosition property.

CursorOptionEnum Enumeration, PositionEnum Enumeration, Recordset.CacheSize Property, Recordset.RecordCount Property, Recordset.Supports Method

The ActiveCommand property returns the Command object that was used to populate a Recordset object.

Variant (containing a Command object)

The read-only ActiveCommand property is used to return the Command object that was used to populate a Recordset object.

If a Command object was not used to populate a Recordset object, a reference to a Null object is returned.

The ActiveConnection property specifies the Connection object for the current Recordset object.

String or a Variant (containing the current Connection object)

The ActiveConnection property can be read to return either a String or a reference to a Connection object. The ActiveConnection property cannot be read if the Recordset object is open or if the Recordset object was created with a Command object (its Source property set to a Command object). At any other time, the ActiveConnection property can be set to either a String or a reference to a Connection object. If a String value is used, then it should be a valid connection string that could be passed to the ConnectionString property of a Connection object. You must set the ActiveConnection property before you attempt to open a Recordset object. Before it is set, the default value for the ActiveConnection property is a Null object reference.

If you specify the ActiveConnection as a parameter to the Open method of the Recordset object, the ActiveConnection property will access the same value. If you opened a Recordset object with a Command object as the Source property value, the Recordset object's ActiveConnection property will access the Command object's ActiveConnection property value.

Conection.ConnectionString Property, Recordset.Open Method, Recordset.Source Property

The AddNew method creates a new record within the current Recordset object that is set to the value that you specify.

Fields

As the optional first parameter to the AddNew method, supply either a Variant or a Variant array. This object represents the name of the field or an array of fields, respectively, for which you wish to initialize values. If this parameter is a Variant array, then the next parameter, Values, must also be a Variant array of the same dimension.

Values

The optional second parameter works in correspondence with the first parameter, Fields. This parameter is also either a Variant or a Variant array that specifies the values of the fields that you included in your first parameter. It is important to remember that if this parameter contains a Variant array, then the Fields parameter must also be an array of the same dimension. In addition, each ordinal position of both arrays must match the proper fields to the correct values.

The AddNew method is a member method of the Recordset object. Its purpose is to add a new record to the recordset specified by the Recordset object. With the AddNew method, you may choose to include either a single field name and initialization value or a list of fields, in the form of a Variant array, along with a corresponding Variant array of values, which match these fields.

After calling the AddNew method, you can call either the Update method or the AddNew method again to add the current record to the Recordset object. If you call the AddNew method before calling the Update method, then ADO automatically calls the Update method and proceeds with the AddNew method call. Simply adding the record to the Recordset object does not guarantee that your new record is in your data source. This case depends on the updating mode of your Recordset object.

If the Recordset object is set for immediate update mode and you do not include parameters with the AddNew call, then your changes are made immediately after the following Update or AddNew method call. If you call AddNew with parameters, the values are cached locally until the next Update is called. During the period between the AddNew and Update method calls, the EditMode property is set to adEditAdd and is not reset to adEditNone until the update is completed, either by calling the Update method or AddNew once again.

If the Recordset object is set for batch update mode, your changes are made only when the UpdateBatch method of the Recordset object is called. In this mode, the changes are cached locally if the AddNew method does not include parameters. This also sets the EditMode property to adEditAdd. The changes are sent to the provider -- but still not posted to the data source -- when the Update method is called, in turn setting the EditMode property to adEditNone. On the other hand, if you call the AddNew method with parameters, the changes are immediately sent to the provider to be posted with the next UpdateBatch method call.

If your Recordset object supports bookmarks, your new record will be added to the end of your recordset and can be accessed at any time. If your Recordset object does not support bookmarks, there is a good chance that you may not be able to access the record once you move away from it, so never rely on it being there. Instead, use the Requery method of the Recordset object to enable your application to find the field.

EditModeEnum Enumeration, Recordset.EditMode Property, Recordset.Requery Method, Recordset.Update Method, Recordset.UpdateBatch Method

The BOF property indicates that the record pointer is located before the first record in the recordset. The EOF property indicates that the record pointer is located directly after the last record in the recordset.

Boolean

The BOF and EOF properties are both read-only.

If both the BOF and EOF properties are True, then the current recordset is empty. Using any Move method (Move, MovePrevious, MoveFirst, MoveNext, or MovePrevious) generates an error.

If both the BOF and EOF properties are False, then the record pointer can be pointing to any record within the recordset. If this is the case, you can use any of the Move methods without generating an error.

If the BOF property is True and the EOF property is False, then the record pointer is pointing to the position directly before the first record within the recordset. When this happens, you cannot use the MovePrevious method or the Move method with a negative number without generating an error.

If the EOF property is True and the BOF property is False, then the record pointer is pointing to the position directly after the last record within the recordset. When this happens, you cannot use the MoveFirst method or the Move method with a positive number without generating an error.

If you delete the last record in the recordset, the BOF and EOF properties will remain set to False until you move the record pointer.

If either a call to MoveFirst or a call to MoveLast results in not being able to find a record, both the EOF and BOF properties will be set to True.

If MovePrevious or Move -- with a value of less than zero -- cannot find a record, the BOF property is set to True.

If MoveNext or Move -- with a value of greater than zero -- cannot find a record, the EOF property is set to True.

Recordset.Move Method, Recordset.MoveFirst Method, Recordset.MoveLast Method, Recordset.MoveNext Method, Recordset.MovePrevious Method, Recordset.Open Method

The Bookmark property returns a unique identifier for the current record within a recordset. By setting the Bookmark property to a previously read value, the record pointer can be repositioned to the original record.

Variant

The Bookmark property is available only through recordsets that support bookmarks. Bookmarks are used to record the position of the current record and later to set the current record back to the specified bookmark.

Bookmarks can be used interchangeably within Recordset objects that are clones of each other, but not with other Recordset objects, even if they were created from the same source.

The return value of the Bookmark property is not readable and shouldn't be used in comparisons because two bookmarks of the same record may not be the same.

Not all recordsets support the Bookmark property.

CursorOptionEnum Enumeration, Recordset.Supports Method

The CacheSize property indicates the number or records that are cached by ADO locally in system memory.

Long

The CacheSize property sets or reads the number of records that are kept in local memory at one time by ADO. The value of CacheSize must be at least 1, otherwise an error will occur. The default value of the CacheSize property is 1.

When a recordset is first opened, the number of records specified by the CacheSize property is gathered. After the record pointer moves beyond this number, another set of records is returned, the first being the next record in the recordset. If fewer records are available, the CacheSize requests only those records that are gathered.

The CacheSize property can be changed throughout the life of a recordset; however, the number of records retrieved into the cache does not change until the record pointer is moved outside the current cache.

The values within the cache do not reflect changes made by other users. To accomplish this, use the Resync method.

Recordset.Resync Method

The Cancel method cancels an asynchronous operation for the Recordset object.

The Cancel method can be called to cancel an asynchronous operation of the Recordset object invoked by the Open method.

Recordset.Open Method

The CancelBatch method cancels the currently pending batch update for the current Recordset object.

AffectRecords (AffectEnum)

Optional. Enumerator with the value of adAffectCurrent, adAffectGroup, or adAffectAll.

If the value of AffectRecords is adAffectCurrent, the CancelBatch method call affects only the pending updates for the current record of the recordset.

If the value of AffectRecords is adAffectGroup, the CancelBatch method call affects only the pending records that are dictated through the Filter property of the current Recordset object. This property must be already set for the CancelBatch method to be called with the adAffectGroup parameter.

If the value of AffectRecords is adAffectAll, all records pending updates within the current Recordset object (including those hidden by the Filter property) are affected by the CancelBatch method.

With the CancelBatch method, you can cancel any or all pending updates in the current Recordset object from batch update mode; however, in immediate update mode, calling this method will generate an error.

The CancelUpdate method is called when the CancelBatch method is called, thus removing any updates or new records that were added within the batch. For this reason, the current record position may be invalid, and it is suggested that you move to a reliable record position, either by a valid bookmark or by using a method such as MoveFirst.

If a runtime error occurs during the call to the CancelBatch method, then there are conflicts with all of the records that were requested from the current recordset. In addition, if only one or a few records are in conflict, then the Errors collection is populated, but a runtime error does not occur.

Not all providers support the CancelBatch property.

CursorOptionEnum Enumeration, Recordset.CancelUpdate Method, Recordset.Filter Property, AffectEnum Enumeration, Recordset.Supports Method

The CancelUpdate method cancels any changes to the current batch update made since the last AddNew or Update method calls.

The CancelUpdate method of the Recordset object cancels any changes that were made to a record since a call to the Update method of that Recordset. In addition, the CancelUpdate method cancels the creation of a new record by the AddNew method.

The CancelUpdate method must be called before the Update method for the current record. The only other way to cancel the changes to a record is by using transaction management through the BeginTrans and RollbackTrans methods of the Recordset object.

Recordset.AddNew Method, Recordset.Update Method

The Clone method of the Recordset object returns a clone of the current Recordset.

Recordset object

The Clone method of the Recordset object creates an exact multiple copy of the original Recordset object. Use this method when you want to access more than one record at a time within the same recordset. This is more efficient than creating another new Recordset object for the same recordset.

When a clone is created, the clone's record position will be set to the first record in the recordset.

Only recordsets that support bookmarks can be cloned. Bookmarks from one recordset are valid for clones of that recordset, and vice versa. Closing a clone does not close the original recordset, and vice versa.

LockTypeEnum Enumeration

The Close method closes a Recordset object.

The Close method closes either a Connection or a Recordset object. When you invoke this method on either object, all dependant objects of your connection or recordset are also closed. You would use the Close method to free system resources although the resource still remains in memory. After closing a Connection or Recordset object, you can still open it again. To completely remove the object from memory, set it to Nothing.

When calling the Close method of the Connection object, all associated Recordset objects will be closed, but the associated Command object will persist, thus setting the ActiveConnection property to Nothing and clearning the Parameters collection of the Command object. You can still use the Open method to connect to a data source.

If you close a Connection object that has any associated open Recordset objects, any pending changes of the Recordset objects will be rolled back. By calling the Close method of the Connection object while a transaction is in progress, you generate an error. If a Connection object falls out of scope while a transaction is in progress, the transaction is automatically rolled back.

When you use the Close method on the Recordset object, that object releases any exclusive access you may have to the data and releases any associated data. You can still use the Open method of that Recordset object later, after the Close method.

If your data source is in immediate update mode and the Close method is called while editing, an error occurs. To avoid this error, call either the Update method or the CancelUpdate method. If you are in batch update mode, the data since the last UpdateBatch will be lost.

If you have cloned a Recordset object whose Close method you called, the cloned Recordset object will not be closed, and vice versa.

Recordset.ActiveConnection Property, Recordset.CancelUpdate Method, Recordset.Open Method, Recordset.Update Method

The CompareBookmarks method determines the position of two bookmarks in a recordset relative to one another.

Bookmark1 (Variant)

A bookmark of the first row to be compared.

Bookmark2 (Variant)

A bookmark of the second row to be compared.

CompareEnum

The CompareBookmark method returns a value that indicates which of the two passed bookmarks come first in ordinal position. Bookmarks are unique to rows within the same Recordset and clones of a Recordset object. Comparing bookmarks from two different Recordsets (not created by cloning another) will not return reliable results.

Obtain the current row's bookmark by reading the Bookmark property.

CompareEnum Enumeration, Recordset.Bookmark Property, Recordset.Clone Method

The CursorLocation property indicates the location of the cursor service.

CursorLocationEnum (Long)

The value of the CursorLocation property can be set to one of the valid CursorLocationEnum values listed in Appendix E.

The value of the CursorLocation property is read- and write-enabled for closed Recordset objects and read-only for open Recordset objects.

A recordset returned from an Execute method inherits the value for the CursorLocation from the original object. Recordset objects automatically inherit this value from the Connection object that established it.

Command.Object Method, Connection.Execute Method, CursorLocationEnum Enumeration, Recordset.Open Method

The CursorType property indicates the type of cursor to be used for the current recordset.

CursorTypeEnum (Long)

The CursorType property indicates the type of cursor that should be used when the Recordset object is opened. The value of this property is read- and write-enabled when the Recordset object is closed and read-only when it is opened. The value of the CursorType property can be one of the CursorType enumerations listed in Appendix E.

If the current data provider does not support the selected cursor type, the value of the CursorType property changes when the Recordset object is opened. This value can be read by the application if need be. In this case, once the Recordset object is closed, the original selected value will be returned to the CursorType property.

You can use the Supports method of the Recordset object to see what functionality is supported by the chosen cursor type. (See Chapter 5 for more information on cursor types.)

The Dynamic cursor supports the adMovePrevious functionality as described by the Supports method. The Forward Only cursor does not support any of the functionality that the Supports method indicates. The Keyset cursor and the Static cursor support adBookmark, adHoldRecords, adMovePrevious, and adResync functionality as described by the Supports method.

The Forward Only cursor type does not support bookmarks, because you do not have the functionality to move back to a bookmarked record. The Keyset and Static cursor records support bookmarks through ADO, and the Dynamic cursor supports bookmarks through the data provider (if it supports them).

If the CursorLocation property has been set to adUseClient, only the adOpenStatic CursorType value can be used.

Connection.CursorLocation Property, CursorTypeEnum Enumeration, Recordset.CursorLocation Property, Recordset.Open Method, Recordset.Supports Method

The DataMember property indicates the object, within the data source specified by the Data Source property, that the Recordset object should be created with.

The DataMember and DataSource properties are always used together.

The DataSource property indicates the data source in which the object specified by DataMember resides.

The DataMember property indicates which object within the data source should be used to create the Recordset object.

The Recordset must be closed when the DataMember property is being set. In addition, an error will be raised if the DataSource property is set before the DataMember property.

The Delete method deletes specified records within the recordset.

AffectRecords (Affect Enum)

Optional. Indicates either the value of adAffectCurrent or adAffectGroup.

If the value of AffectRecords is adAffectCurrent, the CancelBatch method call affects only the pending updates for the current record of the recordset.

If the value of AffectRecords is adAffectGroup, the CancelBatch method call affects only the pending records that are dictated through the Filter property of the current Recordset object. This property must be already set for the CancelBatch method to be called with the adAffectGroup parameter.

The Delete method removes a record or a group of records when used with the Recordset object. The Delete method removes a specified Parameter object from the Parameters collection when used with it.

When using the Delete method with the Recordset object, records that are to be deleted are actually marked for deletion. If the particular recordset does not allow deletion, an error occurs. In immediate update mode, the deletion occurs immediately. However, in batch update mode, the records are marked deleted and are cached until the UpdateBatch method is called. You can view the deleted records by using the Filter property.

After you delete a record, the current record position is still on that record. Once you move from that record position, the records are no longer accessible, and attempting to read a deleted record results in an error. If you are using transaction management with BeginTrans, you can cancel the deletion of records with the RollbackTrans method. In addition, in batch update mode, you can cancel deletion by using the CancelBatch method.

If you attempt to delete a record that has already been deleted by another user, a runtime error does not occur; instead, the Errors collection is populated with warnings. A runtime error occurs only if all of the requested records to be deleted have a conflict for some reason. You can use the Filter property with the adFilterAffectedRecords value and the Status property to locate any records with conflicts.

The Delete method is valid only for the Parameters collection of the Command object. Specify the name of the parameter to be deleted from the collection in the form of a String.

Not all providers support the Delete method.

AffectEnum Enumeration, Connection.RollbackTrans Method, CursorOptionEnum Enumeration, Recordset.CancelBatch Method, Recordset.Filter Property, Recordset.Status Property, Recordset.Supports Method

The EditMode property indicates the current editing status for a given record.

EditModeEnum (Long)

Use the EditMode property to determine whether the current record is being edited when an editing process has been interrupted. With this information, you can determine whether you need to call the Update method or the CancelUpdate method.

The value of the EditMode property can be one of the EditModeEnum enumerations listed in Appendix E.

EditModeEnum Enumeration, Recordset.AddNew Method, Recordset.CancelUpdate Method, Recordset.Update Method

The EndOfRecordset event is called when an attempt to move the record pointer past the end of the recordset has occurred.

fMoreData

A VARIANT_BOOL value that can be set to True if more data was added by the application to invalidate the current event. In other words, when this event is fired, it is an indication that the record pointer has gone outside the recordset. At this time, you can append more records to the recordset and set this fMoreData parameter to True, so that the operation can be attempted again.

adStatus

An EventStatusEnum value indicating the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

The Recordset object that fired this event.

EventStatusEnum Enumeration, Recordset.MoveNext Method

See Recordset.BOF Property.

The FetchComplete event is called when a long asynchronous operation (fetch) has completed and all of the records have been returned.

pError

An Error object containing details about an error that occurred if the adStatus parameter is set to adStatusErrorsOccurred.

adStatus

An EventStatusEnum value indicating the status of the current operation. If the adStatus parameter is set to adStatusOK the operation was successful. If the adStatus parameter is set to adStatusErrorsOccurred, the operation failed and the pError object contains the details regarding the error. By setting the adStatus parameter to adStatusUnwantedEvent, this event will not be called again.

pRecordset

The Recordset object that fired this event.

EventStatusEnum Enumeration

The FetchProgress event is called during a long asynchronous operation (fetch) to report the progress of the fetch.

Progress

A Long value that indicates the number of records that have been retrieved so far by the operation.

MaxProgress

A Long value that indicates the maximum number of records that are expected to be retrieved.

adStatus

An EventStatusEnum value indicating the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

The Recordset object that fired this event.

EventStatusEnum Enumeration, Recordset.FetchProgress Event

The FetchChangeComplete event is called after an operation changes one or more Field object values.

cFields (Long)

Indicates the number of Field objects within the Fields parameter.

Fields (Variant array)

Contains the Field objects that are waiting to be changed.

pError (Error)

Contains details about an error that occurred if the adStatus parameter is set to adStatusErrorsOccurred.

adStatus (EventStatusEnum)

Indicates the status of the current operation. If the adStatus parameter is set to adStatusOK, the operation was successful. If the adStatus parameter is set to adStatusErrorsOccurred, the operation failed, and the pError object contains the details regarding the error. If the adStatus parameter is set to adStatusCancel, then the operation has been canceled before completion by the application. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

Represents the Recordset object that fired this event.

EventStatusEnum Enumeration, Recordset.WillChangeField Event, Recordset.Value, Recordset.Update

The Field collection contains multiple Field objects for the current Recordset object, one for each column in the Recordset object.

Fields (Collection object)

The Fields collection of a Recordset object can be populated before opening a Recordset object by calling the Refresh method of the Fields collection.

Field objects can be added to the collection either by calling the Field.Append method or by referencing by name a Field object that is not already part of the collection. Calling the Field.Update method will add the field to the collection, if possible, within the data source. Until this moment, the Field.Status property will return adFieldPendingInsert.

Field.Append Method, Field.Refresh Method, Field.Update Method

The Filter property filters a selection of records within the current Recordset object.

Variant

When you set the Filter property, the cursor type is changed to the current filtered recordset. In this case, the AbsolutePosition, AbsolutePage, RecordCount, and PageCount properties are affected, since the current record is changed to the first record that meets the requirements dictated by the Filter property.

The Filter property can have one of three types of values:

• A set of clauses that are connected with the AND or OR keywords.

• An array of bookmark values.

• A FilterGroupEnum enumeration value.

Clauses are similar to WHERE clauses in SQL statements. They consist of a field name, an operator, and a value. Multiple clauses can be grouped and joined together with the AND and OR keywords. The field name in a clause has to be a valid field name within the current recordset and if it contains spaces, it has to be placed in brackets ([First Name]). The operator within a clause can be any of the following: <, >, <=, >=, <>, =, or LIKE. The value within a clause is similar to the data within the field specified. Numbers can use decimal points, dollar signs, and scientific notation. Dates are surrounded by pound signs (#) (#06/20/1973#) and strings are surrounded by single quotes ('Jason T. Roff').

If you are using the LIKE keyword as an operator, only the asterisk (*) and percent sign (%) can be used as wildcards, as long as one of the two is at the end of the value (Jason* or *as*).

When setting the Filter property to an array of bookmarks, the bookmarks must be unique -- pointing to different records -- within the associated recordset.

When setting the Filter to a FilterGroupEnum enumeration value, choose from one of the constants listed in Table E-25.

The Filter property can fail because of a record that has been deleted by another user. In this case, a runtime error does not occur. Instead, the Errors collection is populated with warnings. A runtime error occurs only if all of the requested records to be filtered have a conflict for some reason. You can use the Status property to locate any records with conflicts.

AffectEnum Enumeration, FilterGroupEnum Enumeration, Recordset.AbsolutePage Property, Recordset.AbsolutePosition Property, Recordset.CancelBatch Method, Recordset.Delete Property, Recordset.PageCount Property, Recordset.RecordCount Property, Recordset.Resync Method, Recordset.UpdateBatch Method

The Find method moves the record pointer to a row within the current recordset that matches the single-column search criteria specified.

Criteria (String)

Specifies a single-column search criteria in the form of 'Column Operator Value'. The Column portion is a name of a column in the Recordset object. The Operator can be >, <, =, >=, <=, <>, or LIKE. The value can be written as a string, floating point number, or date. Strings are deliminated with single strings or number signs (#) and dates are deliminated with number signs (#). When using the LIKE operator, asterisks (*) can be used at the end or both the beginning and the end of the value ('*jr*', 'jr*'). If the asterisks is used at the beginning only, an error will occur.

SkipRows (Long)

Optional. Indicates how many rows to skip before searching the recordset for a match to the Criteria argument. The default is 0, meaning the search will begin on the current row.

SearchDirection (SearchDirectionEnum)

Optional. Indicates whether to search forward or backward through the recordset. If a match is not found and a forward search is being done, the record pointer will point to the EOF marker. If a backward search is done and a match is not found, the record pointer will point to the BOF marker. By default, a forward search is done.

Start (Variant)

Optional. Specifies a starting position for the search in the form of a bookmark. The default value for this argument is the current row.

If a current record is not set prior to calling the Find method, an error will occur. It is good practice to call the MoveFirst method prior to the Find method.

The Find method works only with single-column search critierias.

Not all providers support Bookmarks and, therefore, cannot search backwards. Use the Supports method to determine whether your current data provider can support the Find operation that you want to use.

CursorOptionEnum Enumeration, Recordset.MoveFirst Method, Recordset.Supports Method, SearchDirectionEnum Enumeration

The GetRows method of the Recordset object returns multiple records from an open Recordset object in the form of an array.

Rows (Long)

Optional. Indicates the number of records to retrieve. The default value for this argument is adGetRowsRest (value of -1).

Start (String or Variant)

Optional. Evaluates to a bookmark where the GetRows method should begin.

Fields (Variant)

Optional. Specifies which fields should be returned for each record by the GetRows method. Represents a single field name, a single field-ordinal number, an array of field names, or an array of field-ordinal numbers.

The GetRows method of the Recordset object returns multiple records from the same Recordset object into a two-dimensional array. The records are returned in the form of a Variant array that is automatically dimensioned by ADO. The first subscript is the field; the second is the record number. The data returned is read-only.

You can specify the number of records to be returned through the first argument. If this value is larger than the number of records, only the remaining records are returned.

If the selected Recordset object supports bookmarks, you can specify the starting location by passing the value of the record's Bookmark property.

After the call to GetRows, the record pointer is set to the next unread record, unless there is no more records, in which case the EOF property is set to True.

The last argument, Fields, can represent a single field or a group of fields to be returned by the GetRows method. This is done with a field name, a field-ordinal position, an array of field names, or an array of field-ordinal positions.

Not all providers support the Find method.

BookmarkEnum Enumeration, CursorOptionEnum Enumeration, GetRowsOptionEnum Enumeration, Recordset.Bookmark Property, Recordset.EOF Property, Recordset.Supports Method

The GetString method returns the entire Recordset object as a String value.

StringFormat (StringFormatEnum)

Indicates the format of the returned Recordset in String form.

NumRows

Optional. Indicates the number of rows to be converted to a String. If the value of this parameter is either missing or greater than the total number of records in the Recordset object, then all of the records are converted.

ColumnDelimeter

Optional. Used only when the StringFormat parameter is set to adClipString. Indicates the delimeter used between columns. The tab character is the default character.

RowDelimeter

Optional. Used only when the StringFormat parameter is set to adClipString. Indicates the delimeter used between rows. The carriage return character is the default character.

NullExpr

Optional. Used only when the StringFormat parameter is set to adClipString. Indicates the String used to replace Null characters. The default for this parameter is the empty String.

Variant

The GetString method converts the contents of the Recordset object to a String value.

StringFormatEnum Enumeration

The Index property sets the current index for a given recordset.

String

The Index property is both read- and write-enabled. However, it cannot be set within a WillRecordsetChange or RecordsetChangeComplete event or during an asynchronous execution.

The Index property is used in conjunction with the Seek method to take advantage of the underlying table's indexed structure (as compared to the Find method, which operates sequentially).

The position of the record pointer may change when the Index is set (changing the AbsolutePosition property value). In addition, the following events occur: WillRecordsetChange, RecordsetChangeComplete, WillMove, and MoveComplete.

If the LockType property is set to adLockPessimistic or adLockOptimistic, then the UpdateBatch method is called releasing any filter that may be applied. In addition, the record pointer is moved to the first record in the indexed recordset.

Not all providers support indexes; therefore, they do not all support the Index property.

CursorOptionEnum Enumeration, Recordset.MoveComplete Event, Recordset.RecordsetChangeComplete Event, Recordset.Seek Method, Recordset.UpdateBatch Method, Recordset.WillMove Event, Recordset.WillRecordsetChange Event, Recordset.Supports Method

The LockType property indicates the type of locks that are set on records when they are being edited.

LockTypeEnum (Long)

The LockType property is read- and write-enabled when the Recordset object is closed, but read-only once it is opened. The LockType property may be any one of the values in Table E-29.

Not all data providers support every type of record locking. In this case, the data provider may automatically select a different type of lock type. Check the available functionality of a data provider with the Supports property.

LockTypeEnum Enumeration, Recordset.Open Method, Recordset.Supports Method, Recordset.Update Method

The MarshalOptions property indicates which records are to be marshaled back to the server.

MarshalOptionsEnum (Long)

The MarshalOptions property can be one of the MarshalOptionsEnum enumeration values listed in Appendix E.

MarshalOptionsEnum Enumeration

The MaxRecords property indicates the maximum number of records to be returned to a recordset from a query.

Long

The MaxRecords property is read- and write-enabled when the Recordset object is open, but read-only when it is closed. A value of 0 (default) indicates that all of the valid records will be returned from a query.

The Move method of the Recordset object moves the position of the record pointer within the specified Recordset object.

NumRecords (Long)

Specifies the number of records you want the record pointer to move.

Start (String or Variant)

Optional. Represents the bookmark from which you want the record pointer to move.

The Move method of the Recordset object moves the record pointer a specified number of records. If the NumRecords argument is less than zero, the pointer is moved forward the desired number. If the NumRecords argument is greater than zero, the record pointer is moved forward the desired number of records.

If the current Recordset object supports bookmarks, then you can indicate a beginning position to start moving from with the Start argument. The Start argument should be set to a valid bookmark within the current Recordset object, and the record pointer will be moved the desired number of records from that point. If no bookmark is used, the record pointer will move from the current record.

Attempting to move to a point before the first record will result in moving to the record before the first record, which is a BOF. Attempting to move past the last record will result in the record pointer moving to the record after the last record, which is the EOF. In either case, if the Move method is used to attempt to move past the BOF or EOF, an error is generated.

If the CacheSize property is set to cache records locally from the data provider and you pass a NumRecords that ventures outside of the cache, ADO is forced to retrieve a new group of records from the data provider. The number of records received is dependent upon the CacheSize property. This also happens if you are using a local cache and use the Start argument. The first record to be received, in this case, would be the desired destination record.

Even if the Recordset object is forward-only, you can still pass a NumRecords value that is less than zero, as long as the destination record is within the current cache. If it is before the current cache, an error is generated.

Not all providers support the Move method.

BookmarkEnum Enumeration, Recordset.Bookmark Property, Recordset.CacheSize Property

The MoveComplete event is called after an operation changes the position of the record pointer within the Recordset object.

adReason (EventReasonEnum)

Indicates the reason for this event. Proper values for the adReason parameter are: adRsnMoveFirst, adRsnMoveLast, adRsnMoveNext, adRsnMovePrevious, adRsnMove, and adRsnRequery.

pError (Error)

Contains details about an error that occurred if the adStatus parameter is set to adStatusErrorsOccurred.

adStatus (EventStatusEnum)

Indicates the status of the current operation. If the adStatus parameter is set to adStatusOK, the operation was successful. If the adStatus parameter is set to adStatusErrorsOccurred, the operation failed, and the pError object contains the details regarding the error. If the adStatus parameter is set to adStatusCancel, the operation has been canceled before completion by the application. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, Recordset.AbsolutePage Property, Recordset.AbsolutePosition Property, Recordset.AddNew Method, Recordset.Bookmark Method, Recordset.Filter Property, Recordset.Index Property, Recordset.Open Method, Recordset.Move Method, Recordset.MoveFirst Method, Recordset.MoveLast Method, Recordset.MoveNext Method, Recordset.MovePrevious Method, Recordset.Requery Method, Recordset.WillMove Event

The MoveFirst, MoveLast, MoveNext, and MovePrevious methods of the Recordset object move the record pointer to the first, last, next, and previous records, respectively, and make that record the current record.

The MoveFirst, MoveLast, MoveNext, and MovePrevious methods of the Recordset object allow you to move freely throughout the specified open Recordset object.

The MoveFirst method moves to the first record in the recordset, making it the current record.

The MoveLast method moves to the last record in the recordset, making it the current record. This method requires the Recordset object to support bookmarks. If it does not, an error is generated when attempting to use the MoveLast method.

The MoveNext method moves to the next record in the recordset, making it the current record. If the current record is the last record in the recordset before the call to MoveNext, then the record pointer is moved to the record after the last in the recordset and sets the EOF property to True. Attempting to move past the EOF results in an error.

The MovePrevious method moves to the record directly before the current record in the recordset. This record is then set to the current record. This method requires that the recordset support either bookmarks or backward cursor movement; otherwise, an error is generated. If the current record -- before calling the MovePrevious method -- is the first record in the recordset, the record pointer is set to the record directly before the first record, and the BOF property is set to True. Attempting to move before the beginning of the recordset results in an error.

Not all providers support the MoveFirst and MovePrevious methods.

CursorOptionEnum Enumeration, Recordset.BOF Property, Recordset.EOF Property, Recordset.Supports Method

The NextRecordset method of the Recordset object returns the next recordset by advancing through a series of commands:

recordset.MoveFirst

RecordsAffected (Long)

Set to the number of records that the current operation affected. The data provider does this.

Use the NextRecordset method of the Recordset object to obtain the next recordset in a compound command statement or a stored procedure that returns multiple results. An example of a compound command statement is:

SELECT * FROM upstairs; SELECT * FROM downstairs

The recordset that is originally created with either the Execute or Open methods returns a Recordset object based only on the first SQL statement in this compound statement. You must call NextRecordset to obtain each additional recordset. If the Recordset object is closed and there are remaining statements, those statements will never be executed.

The NextRecordset method continues to return recordsets as long as there are more in the list. If a row-returning statement successfully executes, and the result is zero records, then the Recordset object's EOF and BOF properties are both be set to True. If a non-row-returning statement successfully executes, then the Recordset object should not be set to Nothing, but the EOF property should be True.

If there are no more statements in the compound command statement, the returned Recordset object is set to Nothing.

You must call the Update or the CancelUpdate methods before requesting the next recordset if you are in immediate update mode and editing. Otherwise, an error will be generated.

Parameters for compound command statements are passed like those of regular statements; all parameters must be filled in the Parameters collection in the proper order across statements. In addition, you must read all the results of a recordset before reading output parameter values.

Recordset.Update Method, Recordset.CancelUpdate Method, Recordset.BOF Property, Recordset.EOF Property

The Open method opens a cursor within a Recordset object.

Source (Variant)

Optional. Indicates the actual data that is used to open the Recordset object. This can be a Command object, a SQL statement, a table name, a stored procedure, a URL, a filename, or a Stream object that contains a previously persisted Recordset object.

ActiveConnection (Variant)

Optional. Specifies either an open Connection object or a connection string to be used when the Recordset object creates its own Connection object.

CursorType (CursorTypeEnum)

Optional. Indicates the type of cursor that is to be used when opening the Recordset object. By default this value is adLockReadOnly.

LockType (LockTypeEnum)

Optional. Specifies the locking to be used on the opened Recordset object. The adLockReadOnly enumeration value is the default value for this argument.

Options (Long -- CommandTypeEnum and ExecuteOptionEnum)

Optional. Specifies the type of data that is to be specified by the Source argument; additionally, can indicate that the Recordset object is to be opened asynchronously. The default value for the Options argument if a Command object is not the source of the Recordset object is adCmdFile.

The Source, ActiveConnection, CursorType, and LockType arguments have matching properties within the Recordset object. If the arguments are omitted in the Open method call, the individual values are obtained from the corresponding properties. If a value is specified for a given argument, however, it will overwrite the previous value stored in the property value.

The source of a Recordset object can be one of the following:

• Command object

• SQL statement

• Stored procedure

• Table name

• URL

• Filename

• Stream object (with the contents of a previously persisted Recordset object)

If anything other than a Command object is used to open a Recordset, specify the data source by using the Options argument. If you do not, ADO must call the data provider repeatedly to determine the type of data that it is opening.

When specifying a file as a Recordset object's source, you can do so with a full pathname, a relative pathname, or even a URL value (http://www.domain.com).

The ActiveConnection argument is used only if you do not specify a Command object. In fact, it is read-only if a valid Command object is set to the Source property.

The ActiveConnection argument can be either an already opened Connection object or a connection string, which will be used to open a new Connection object for the Recordset object.

It is possible to change the value of the ActiveConnection property after a Recordset object is opened, in order to send the updates to the recordset to another data source. However, the remaining arguments and their corresponding properties become read-only once the Recordset object is opened.

You can also open a Recordset asynchronously by adding the adAsyncFetch enumeration value (from the ExecuteOptionEnum enumeration).

Once the Recordset is opened if it is empty, both the BOF and the EOF properties will be set True. Close the Recordset object by calling the Close method. This doesn't remove the Recordset object from memory because you can reopen a Recordset object. To remove the Recordset from memory, set the object to Nothing.

When opening a Recordset object with a Stream object, the Recordset will automatically be opened synchronously regardless of the ExecuteOptionEnum values specified. In addition, you should not specify any other arguments to the Open method when opening a Recordset object from a Stream object.

CommandTypeEnum Enumeration, CursorTypeEnum Enumeration, ExecuteOptionEnum, LockTypeEnum Enumeration, Recordset.ActiveConnection Property, Recordset.BOF Property, Recordset.Close Method, Recordset.CursorType Property, Recordset.EOF Property, Recordset.LockType Property, Recordset.Source Property

The PageCount property returns the number of logical pages that are in the current Recordset object.

Long

The PageCount property returns a value indicating how many logical pages of data are contained within the recordset. A page is determined by the number of records in the recordset divided by the number of records per page (determined by the PageSize property).

If the last page does not contain the number of records in the PageSize property, that page is still counted as a page in the PageCount property.

If the Recordset object does not support the PageCount property, the return value is -1. This indicates that the number of pages could not be determined.

Recordset.AbsolutePage Property, Recordset.PageSize Property

The PageSize property indicates the number of records in a logical page.

Long

The PageSize property determines how many records belong to a logical page within your recordset. The default value is 10. This property can be set at any time and is used with the AbsolutePage property to move to the first record within a specified page.

Recordset.AbsolutePage Property, Recordset.PageCount Property

The Properties collection contains characteristics specific to the Recordset object for the currently used provider.

Properties (Collection object)

The Properties collection class contains a Property class instance for each property specific to the Recordset object for the data provider.

The Properties collection of the Command object is not populated until the ActiveConnection property of the Command object has been set to an open Connection object or a valid connection string value.

Command.ActiveConnection Property

The RecordChangeComplete event is called after an operation changes one or more records in the Recordset object.

adReason (EventReasonEnum)

Indicates the reason for this event. Proper values for the adReason parameter are: adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete, and adRsnFirstChange.

cRecords (Long)

Indicates how many records are affected by the operation causing this event.

pError (Error)

Contains details about an error that occurred if the adStatus parameter is set to adStatusErrorsOccurred.

adStatus(EventStatusEnum)

Indicates the status of the current operation. If the adStatus parameter is set to adStatusOK, the operation was successful. If the adStatus parameter is set to adStatusErrorsOccurred, the operation failed, and the pError object contains the details regarding the error. If the adStatus parameter is set to adStatusCancel, the operation has been canceled before completion by the application. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, Recordset.AddNew Method, Recordset.CancelBatch Method, Recordset.CancelUpdate Method, Recordset.Delete Method, Recordset.WillChangeRecord Event, Recordset.Update Method, Recordset.UpdateBatch Method

The RecordsetChangeComplete event is called after an operation changes the Recordset object.

adReason (EventReasonEnum)

Indicates the reason for this event. Proper values for the adReason parameter are: adRsnReQuery, adRsnReSynch, adRsnClose, and adRsnOpen.

pError (Error)

Contains details about an error that occurred if the adStatus parameter is set to adStatusErrorsOccurred.

adStatus (EventReasonEnum)

Indicates the status of the current operation. If the adStatus parameter is set to adStatusOK, the operation was successful. If the adStatus parameter is set to adStatusErrorsOccurred, the operation failed, and the pError object contains the details regarding the error. If the adStatus parameter is set to adStatusCancel, the operation has been canceled before completion by the application. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, Recordset.Open Method, Recordset.Requery Method, Recordset.WillChangeRecordset Event

The RecordCount property returns the number of records in the current Recordset object.

Long

If the provider or the cursor does not support the RecordCount property, or if the number of records cannot be determined by ADO, -1 is returned.

The actual number of records is always returned by the RecordCount property for Keyset or Static cursors, but -1 is always returned for a Forward Only cursor. Dynamic cursors can return either -1 or the actual number of records, depending upon the data source.

The RecordCount efficiently reports the number of records in a recordset only if the current Recordset object supports approximate positioning (Supports -- adApproxPosition) or bookmarks (Supports -- adBookmark); otherwise, this property uses a lot of resources because ADO must load all of the records to count them.

The Requery method of the Recordset object re-executes the command that created the recordset in the first place in order to cause a refresh of the recordset. This method has the same effect as calling the Close method followed by the Open method.

If you are adding a new record or editing an existing one, when you call the Requery method, an error is generated.

If you wish to change properties that are read-only while a Recordset object is open (CursorType, LockType, etc.), you must manually close and reopen the Recordset object by calling the Close method, editing the properties, and calling the Open method.

ExecuteOptionEnum

The Resync method of the Recordset object refreshes the data in the recordset from the underlying data source.

AffectRecords (AffectEnum)

Optional. An enumerator of type AffectEnum having the value of adAffectCurrent (1), adAffectGroup (2), or adAffectAll (3, the default).

If the value of AffectRecords is adAffectCurrent, the Resync method call affects only the pending updates for the current record of the recordset.

If the value of AffectRecords is adAffectGroup, the Resync method call affects only the pending records that are dictated through the Filter property of the current Recordset object. This property must be already set for the Resync method to be called with the adAffectGroup parameter.

If the value of AffectRecords is adAffectAll, all records pending updates within the current Recordset object (including those hidden by the Filter property) are affected by the Resync method.

The Resync method of the Recordset object is used to resynchronize the records in the current recordset with those found in the underlying data source. This is very useful when you have either a Static or a Forward Only cursor and you want to check whether anyone else has altered the records in the data source.

The Resync method does not show you records that have been added to the data source; rather, it simply updates the ones that you already have. Therefore, the Resync method does not re-execute the underlying command that created the recordset in the first place.

If the Resync method attempts to read a record that has been deleted by another user, a runtime error does not occur. Instead, the Errors collection is populated with warnings. A runtime error occurs only if all of the requested records to be updated have a conflict for some reason. You can use the Filter property with the adFilterAffectedRecords value and the Status property to locate any records with conflicts.

Not all providers support the Resync method.

ADCPROP_UPDATERESYNC_ENUM Enumeration, AffectEnum Enumeration, CursorOptionEnum Enumeration, Recordset.Supports Method, ResyncEnum Enumeration

The Save method saves the current Recordset object to a file or to a Stream object.

Destination (Variant)

Optional. Can be either a name of a file to create or a Stream object that is to accept the saved Recordset object.

PersistFormat (PersistFormatEnum)

Optional. Indicates the format of the Recordset object when it is saved. The default is ADTG, but XML can also be used.

The Save method must be invoked on an Open Recordset object. The first time Save is called, you can specify the Destination argument, but subsequent calls should be made omitting this argument. If the same destination name is used on the same Recordset object, an error will occur, but if two different names are used, both files will remain open until the Close method is called. Omitting the Destination name on the initial call to Save causes a file to be created with the name of the Source to the Recordset object.

When saving a Recordset object with a Filter, only visible records are saved. When saving a hierarchical recordset, the current child Recordset, its children, and the parent Recordset are all saved. When saving a child Recordset, only the child and its children are saved.

If the Save method is called while an asynchronous operation is in effect for the Recordset object, the Save method waits until that operation is complete before attempting to persist the Recordset object. After the Recordset object is persisted, the record pointer points to the first record in the Recordset.

You should obtain better results by setting the CursorLocation property to the client. If the data provider does not support the functionality necessary to save the Recordset object, then the cursor service will. When using the server as the cursor location, you can typically only insert, delete, or update a single table. In addition, the Resync method is not available.

Microsoft warns that when persisting hierarchical recordsets in XML format, you cannot save the Recordset if it contains pending updates or is a parameterized hierarchical Recordset object.

PersistFormatEnum Enumeration, Recordset.Close Method, Recordset.CursorLocation Property, Recordset.Filter Property, Recordset.Source Property

The Seek method quickly changes the record pointer to the record in the Recordset object that matches the index provided.

KeyValues (Variant)

Indicates the values that are used in conjunction with the Recordset.Index value to locate a record.

SeekOptions (SeekEnum)

Indicates the type of comparison used when seeking a record.

The Seek method is used with the Index property of the Recordset object. If the current Recordset supports indexes, you can use the Seek method. Check the value of the Recordset.Supports (adSeek) method call to determine whether the current Recordset object will support this method.

The Index property indicates which Index is used with the Seek method. The Seek method's first parameter, an array of Variant values, should contain one value for each column within the currently used Index.

If the record cannot be found, the record pointer is placed at the EOF marker.

The Seek method can be used only on server-side clients, which are opened with the CommandTypeEnum enumeration value, adCmdTableDirect.

Not all providers support the Seek method.

CommandTypeEnum Enumeration, CursorOptionEnum Enumeration, Recordset.EOF Property, Recordset.Index Property, SeekEnum Enumeration, Recordset.Supports Method

The Sort property sorts a recordset on one or more field names.

String

The Sort property can be set to sort a recordset based upon one or more fields in either ascending or descending order. The Sort property accepts a String value identical to a sort clause of a SQL statement. Fields are separated by commas with either the ASC or DESC keywords following each field name. If the ASC or DESC keyword is absent, ASC is inferred.

Setting the Sort property to an empty String value (") removes the sort from the recordset and returns the order to the default.

For instance, the following value for the Sort property, "Company ASC, Contact DESC," would sort the recordset by the company in ascending order and then by the contact in descending order.

The Sort property does not rearrange data within the recordset; instead, it creates a temporary index for each field that does not already have an index if the CursorLocation property is set to adUseClient.

Not all providers support the Sort property.

Recordset.CursorLocation Property

The Source property returns the source for the data in a Recordset object.

For a Recordset object, the Source property specifies from where a recordset's data comes. The Source property for the Recordset object is read- and write-enabled while the Recordset object is closed, but read-only once it is opened.

The value of the Source property for the Recordset object can contain one of the following:

• Command object variable

• SQL statement

• Stored procedure name

• Table name

• File or URL

If the Source property is set to a Command object, the ActiveConnection property of the Recordset object gets its value from the ActiveConnection property of the Command object, but reading the Source property does not return a Command object. Instead, it returns the CommandText property of the associated Command object from which you set the Source property.

If the Source property is set to a SQL statement, a stored procedure name, or a table name, you would be better off specifying it in the Options argument of the Open method, in order for the Recordset object to optimize performance.

Recordset.Open Method

The State property indicates the current state of the Recordset object.

ObjectStateEnum

The read-only State property indicates whether the current Recordset object is opened or closed.

ObjectStateEnum Enumeration

The Status property indicates the status of the current record in relation to bulk operations.

RecordStatusEnum

The Status property can be set to one or more of the RecordStatusEnum enumeration values listed in Appendix E.

The Status property indicates changes still pending for records that have been updated during a batch operation.

In addition, the Status property indicates why the following functions have failed: Resync, UpdateBatch, CancelBatch, and Filter (setting equal to an array of bookmarks).

Recordset.CancelBatch Method, Recordset.Filter Property, Recordset.Resync Method, Recordset.UpdateBatch Method, RecordStatusEnum Enumeration

The StayInSync property indicates when the references to chapter recordsets change if the record pointer moves to a different parent row for hierarchical recordsets.

Boolean

The StayInSync property is both read- and write-enabled. The default value for this property is True.

If the value of the StayInSync property is set to True, the references of chapter recordsets change when the parent recordset is changed.

If the value of the StayInSync property is set to False, the references of chapter recordsets point to the previous parent recordset when moving the record pointer within a hierarchical recordset changes the parent recordset.

The Supports method determines whether the current data provider supports specified functionality.

CursorOptions (Long)

Represents the type functionality that you are testing for. This value can be one or more of the CursorOptionEnum values listed in Appendix E.

Boolean

The Supports method of the Recordset object tests whether the Recordset object supports individual types of functionality.

If the values of the CursorOptionEnum values are added and passed as the sole argument to the Supports function, a return value indicates whether all of the questioned functionality is supported.

CursorOptionEnum Enumeration

The Update method of the Recordset object saves the changes made to fields within the current record since a call to AddNew changes the contents of a field or array of fields.

Fields (Variant or Variant array)

This argument can hold the field, ordinal position, array of fields, or an array of ordinal positions that you wish to update in the current record. The Fields argument must be of the same type and dimension as that of the Values argument.

Values (Variant or Variant array)

Optional. This argument can hold the value or values of the fields specified in the Fields argument. The Values argument must be of the same type and dimension as that of the Fields argument.

The current record remains the current record after the call to the Update method.

If you specify an array of field names for the Fields argument to the Update method, the Values argument must have the same dimensional array passed to it, containing the corresponding values for each field listed in the Fields array. Otherwise, an error will be generated.

If you move to another record while editing a record, that record will be saved -- by an automatic call to the Update method -- before the record position is changed. In addition, if you are editing the current record and you call the UpdateBatch method, the Update method will again -- automatically be called.

Conversely, the CancelUpdate method cancels any changes made to the current record.

Not all providers support the Update method.

CursorOptionEnum Enumeration, Recordset.Supports Method

The UpdateBatch method of the Recordset object writes all pending batch updates to disk when called.

AffectRecords (AffectEnum)

The optional parameter to the UpdateBatch method is an enumerator of type AffectEnum having the value of adAffectCurrent (1), adAffectGroup (2), or adAffectAll (3, the default).

If the value of AffectRecords is adAffectCurrent, the UpdateBatch method call affects only the pending updates for the current record of the recordset.

If the value of AffectRecords is adAffectGroup, the UpdateBatch method call affects only the pending records that are dictated through the Filter property of the current Recordset object. This property must be already set for the UpdateBatch method to be called with the adAffectGroup parameter.

If the value of AffectRecords is adAffectAll, all records pending updates within the current Recordset object (including those hidden by the Filter property) are affected by the UpdateBatch method.

The UpdateBatch method transmits all pending batch updates to the data source. This method is for use only when in batch update mode, which should be used only with a Keyset or Static cursor.

It is possible to update cached field values multiple times before committing the changes of the pending batch updates. The Update method is automatically called if the UpdateBatch method is called while in edit mode.

If you attempt to update a record that has already been deleted by another user, a runtime error does not occur; instead, the Errors collection is populated with warnings. A runtime error occurs only if all of the requested records to be updated have a conflict for some reason. You can use the Filter property with the adFilterAffectedRecords value and the Status property to locate any records with conflicts.

Conversely, the CancelBatch method cancels all pending batch updates,

Not all providers support the UpdateBatch method.

AffectEnum Enumeration, Recordset.Supports Method, CursorOptionEnum Enumeration

The WillChangeField event is called before an operation changes one or more Field object values.

cFields (Recordset object)

Represents the actual recordset that you wish to refresh.

Fields (Variant array)

Contains the Field objects that are waiting to be changed.

adStatus (EventStatusEnum)

Indicates the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again. If the adStatus parameter is set to adStatusCancel, a cancellation request will be made for this operation.

pRecordset

Represents the Recordset object that fired this event.

EventStatusEnum Enumeration, Recordset.FieldChangeComplete Event, Recordset.Update Method, Recordset.Value Property

The WillChangeRecord event is called before an operation changes one or more records in the Recordset object.

adReason (EventStatusEnum)

Indicates the reason for this event. Proper values for the adReason parameter are: adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete, and adRsnFirstChange.

cRecords (Long)

Indicates how many records are affected by the operation causing this event.

adStatus (EventStatusEnum)

Indicates the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter to adStatusUnwantedEvent, this event will not be called again. If the adStatus parameter is set to adStatusCancel, a cancellation request will be made for this operation.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, Recordset.AddNew Method, Recordset.CancelBatch Method, Recordset.CancelUpdate Method, Recordset.Delete Method, Recordset.RecordChangeComplete Event, Recordset.Update Method, Recordset.UpdateBatch Method

The WillChangeRecordset event is called before an operation changes the Recordset object.

adReason (EventReasonEnum)

Indicates the reason for this event. Values for the adReason parameter are: adRsnReQuery, adRsnReSynch, adRsnClose, and adRsnOpen.

adStatus (EventReasonEnum)

Indicates the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again. If the adStatus parameter is set to adStatusCancel, a cancellation request will be made for this operation.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, RecordsetChangeComplete Event, Recordset.Requery, Recordset.Open

The WillMove event is called before an operation changes the position of the record pointer within the Recordset object.

adReason (EventReasonEnum)

Indicates the reason for this event. Values for the adReason parameter are: adRsnMoveFirst, adRsnMoveLast, adRsnMoveNext, adRsnMovePrevious, adRsnMove, adRsnRequery.

adStatus

Holds an EventStatusEnum value indicating the status of the current operation. The adStatus parameter is set to adStatusOK if the operation causing this event was successful. If the adStatus parameter is set to adStatusCantDeny, the event cannot request that the operation be canceled. If the adStatus parameter is set to adStatusUnwantedEvent, this event will not be called again. If the adStatus parameter is set to adStatusCancel, a cancellation request will be made for this operation.

pRecordset

Represents the Recordset object that fired this event.

EventReasonEnum Enumeration, EventStatusEnum Enumeration, Recordset.AbsolutePage Property, Recordset.AbsolutePosition Property, Recordset.AddNew Method, Recordset.Bookmark Method, Recordset.Filter Property, Recordset.Index Property, Recordset.Move Method, Recordset.MoveFirst Method, Recordset.MoveLast Method, Recordset.MoveNext Method, Recordset.MovePrevious Method, Recordset.Open Method, Recordset.Requery Method, Recordset.WillMove Event