ADO API 参考

  ADO API 参考

Resync 方法

从基本数据库刷新当前 Recordset 对象中的数据。

语法

recordset .Resync AffectRecords, ResyncValues

参数

AffectRecords    可选， AffectEnum 值，决定 Resync 方法所影响的记录数目，可以为下列常量之一。

常量 说明 AdAffectCurrent 只刷新当前记录。 AdAffectGroup 刷新满足当前 Filter 属性设置的记录。只有将 Filter 属性设置为有效预定义常量之一才能使用该选项。 AdAffectAll 默认值。刷新 Recordset 对象中的所有记录，包括由于当前 Filter 属性设置而隐藏的记录。 adAffectAllChapters 刷新所有子集记录。

ResyncValues    可选， ResyncEnum 值。指定是否覆盖基本值。可为下列常量之一。

常量 说明 AdResyncAllValues 默认值。覆盖数据，取消挂起的更新。 AdResyncUnderlyingValues 不覆盖数据，不取消挂起的更新。

说明

使用 Resync 方法将当前 Recordset 中的记录与基本的数据库重新同步。这在使用静态或仅向前的游标但希望看到基本数据库中的改动时十分有用。

如果将 CursorLocation 属性设置为 adUseClient ，则 Resync 仅对非只读的 Recordset 对象可用。

与 Requery 方法不同， Resync 方法不重新执行 Recordset 对象的基本的命令，基本的数据库中的新记录将不可见。

如果由于与基本的数据冲突（如其他用户已将记录删除）而使重新同步的尝试失败，则提供者将警告返回到 Errors 集合并且产生运行时错误。使用 Filter 属性 (adFilterConflictingRecords) 和 Status 属性可以找到发生冲突的记录。

远程数据服务用法    Resync 方法在客户端 Recordset 上无效。

如果设置了 Unique Table 和 Resync Command 动态属性，并且 Recordset 是对多个表执行 JOIN 操作的结果，那么， Resync 方法将仅对 Unique Table 属性中命名的表执行在 Resync Command 属性中所给定的操作。

Save 方法 (ADO Recordset)

将 Recordset 保存（持久）在文件中。

语法

recordset. Save FileName, PersistFormat

参数

FileName    可选。文件的完整路径名，用于保存 Recordset 。

PersistFormat    可选。 PersistFormatEnum 值，指定保存 Recordset 所使用的格式。可以是如下的某个常量：

常量 说明 adPersistADTG （默认）使用专用的 “Advanced Data Tablegram” 格式保存。 adPersistXML 使用 XML 格式保存。

说明

只能对打开的 Recordset 调用 Save 方法。随后使用 Open 方法可由 FileName 恢复 Recordset 。

如果 Filter 属性影响 Recordset ，将只保存经过筛选的行。如果 Recordset 是分级结构的，那么将保存当前子 Recordset 和它的子 Recordset ，但不保存上一级 Recordset 。

在第一次保存 Recordset 时指定 FileName 。如果随后调用 Save 时，应忽略 FileName ，否则将产生运行时错误。如果随后使用新的 FileName 调用 Save ，那么 Recordset 将保存到新的文件中，但新文件和原始文件都是打开的。

Save 不关闭 Recordset 或 FileName ，从而可以继续使用 Recordset 并保存最新的更改。在 Recordset 关闭之前 FileName 将保持打开，在这段时间其它应用程序可以读取但不能写入 FileName 。

出于安全的原因，对由 Microsoft Internet Explorer 执行的脚本， Save 方法仅允许使用低的和自定义的安全设置。有关安全问题的详细解释，请参阅 在 http://www.microsoft.com/data/techmat.htm 上的白皮书标题 “Security Issues in the Microsoft Internet Explorer” 。

如果正在进行异步 Recordset 获取、执行或更新操作时调用 Save 方法，则 Save 将进入等待状态，直到异步操作完成。

在 Save 方法完成后，当前行位置将成为 Recordset 的首行。

要得到最佳结果，应使用 Save 将 CursorLocation 属性设置为 adUseClient 。如果您的提供者不支持用于保存 Recordset 对象的所需功能，则客户端游标将提供该功能。

Seek 方法

搜索 Recordset 的索引，快速定位与指定值相匹配的行，并将当前行更改为该行。

语法

recordset .Seek KeyValues, SeekOption

参数

KeyValues    VARIANT 值的数组。索引由一个或多个列组成，而数组包含与每个对应列进行比较的值。

SeekOption    SeekEnum 只值，指定在索引的列和对应的 KeyValues 之间进行的比较的类型。可以是如下某个比较常量：

常量 说明 AdSeekAfterEQ 查找等于 KeyValues 的关键字，或仅在已经匹配过的位置之后进行查找。 AdSeekAfter 仅在已经有过与 KeyValues 匹配的位置之后进行查找。 AdSeekBeforeEQ 查找等于 KeyValues 的关键字，或仅在已经匹配过的位置之前进行查找。 AdSeekBefore 仅在已经有过与 KeyValues 匹配的位置之前进行查找。 AdSeekFirstEQ 查找等于 KeyValues 的第一个关键字。 AdSeekLastEQ 查找等于 KeyValues 的最后一个关键字。

说明

如果基本提供者支持对 Recordset 对象使用索引，请结合 Index 属性使用 Seek 方法。请使用 Supports (adIndex) 方法判断基本提供者是否支持索引。

如果 Seek 没有找到想要的行，则不发生错误，并且行被定位于 EOF 。请在执行该方法之前，将 Index 属性设置为所需索引。

该方法只能用于当 Recordset 对象的 CursorLocation 属性的值不是 adUseClient 时。

SubmitChanges 方法 (RDS)

将本地缓存的可更新 Recordset 的挂起更改提交到在 Connect 属性中指定的 ODBC 数据源中。

语法

DataControl. SubmitChanges

DataFactory .SubmitChanges Connection, Recordset

参数

DataControl    对象变量，代表 RDS.DataControl 对象。

DataFactory    对象变量，代表 RDSServer.DataFactory 对象。

Connection    字符串 值，代表用 RDS.DataControl 对象的 Connect 属性创建的连接。

Recordset    对象变量，代表 Recordset 对象。

说明

在使用 RDS.DataControl 对象的 SubmitChanges 方法之前必须设置 Connect 、 Server 和 SQL 属性。

如果在已经调用相同 Recordset 对象的 SubmitChanges 后调用 CancelUpdate 方法，那么 CancelUpdate 调用将由于更改已提交而失败。

仅发送已更改的记录用于修改，更改或者全部成功或者全部失败。

只能通过默认的 RDSServer.DataFactory 对象使用 SubmitChanges 。自定义业务对象不能使用该方法。

Supports 方法

确定指定的 Recordset 对象是否支持特定类型的功能。

语法

boolean = recordset.Supports( CursorOptions )

返回值

返回布尔型值，指示提供者是否支持 CursorOptions 参数所标识的所有功能。

参数

CursorOptions    长整型 表达式，包括一个或多个下列 CursorOptionEnum 值。

常量 说明 adAddNew 可使用 AddNew 方法添加新记录。 adApproxPosition 可读取并设置 AbsolutePosition 和 AbsolutePage 的属性。 adBookmark 可使用 Bookmark 属性获得对特定记录的访问。 adDelete 可以使用 Delete 方法删除记录。 AdHoldRecords 可以检索多个记录或者更改下一个检索位置而不必提交所有挂起的更改。 AdMovePrevious 可使用 MoveFirst 和 MovePrevious 方法，以及 Move 或 GetRows 方法将当前记录位置向后移动而不必使用书签。 AdResync 通过 Resync 方法，使用在基本的数据库中可见的数据更新游标。 AdUpdate 可使用 Update 方法修改现有的数据。 AdUpdateBatch 可以使用批更新（ UpdateBatch 和 CancelBatch 方法）将更改组传输给提供者。 AdIndex 可以使用 Index 属性命名索引。 AdSeek 可以使用 Seek 方法定位 Recordset 中的行。

说明

使用 Supports 方法确定 Recordset 对象所支持的功能类型。如果 Recordset 对象支持其相应常量在 CursorOptions 中的功能，那么 Supports 方法返回 True 。否则返回 False 。

注意     尽管 Supports 方法可对给定的功能返回 True ，但它不能保证提供者可以使功能在所有环境下均有效。 Supports 方法只返回提供者是否支持指定的功能（假定符合某些条件）。例如， Supports 方法可能指示 Recordset 对象支持更新（即使游标基于多个表的合并），但并且某些列仍然无法更新。

Update 方法

保存对 Recordset 对象的当前记录所做的所有更改。

语法

recordset .Update Fields, Values

参数

Fields    可选。变体型，代表单个名称；或变体型数组，代表需要修改的字段（一个或多个）名称及序号位置。

Values    可选。变体型，代表单个值；或变体型数组，代表新记录中字段（单个或多个）值。

说明

使用 Update 方法保存自调用 AddNew 方法或更改现有记录中任何字段值以来所作的所有更改。 Recordset 对象必须支持更新。

要设置字段值，请进行下列某项操作：

• 为 Field 对象的 Value 属性赋值，并调用 Update 方法。
• 在 Update调用中传送字段名和值作为参数。
• 在 Update 调用中传送字段名数组和值数组。

在使用字段和值的数组时，两个数组中必须有相等数量的元素，同时字段名的次序必须匹配字段值的次序。字段和值的数量及次序不匹配将产生错误。

如果 Recordset 对象支持批更新，那么可以在调用 UpdateBatch 方法之前将一个或多个记录的多个改动缓存在本地。如果在调用 UpdateBatch 对象时正在编辑当前记录或者添加新的记录，那么 ADO 将自动调用 Update 方法以便在将批更改传送到提供者之前保存挂起的更改。

如果在调用 Update 方法之前移动出正在添加或编辑的记录，那么 ADO 将自动调用 Update 以便保存更改。如果希望取消对当前记录所做的任何更改或者放弃新添加的记录，则必须调用 CancelUpdate 方法。

在调用 Update 方法后当前记录仍为当前记录。

如果设置了 Unique Table 动态属性，并且 Recordset 是对多个表执行 JOIN 操作的结果，那么， Update 方法将无法更新多个表的任何主要关键字。此外， Update 只能更新在 Unique Table 属性中指定的表中的字段。

UpdateBatch 方法

将所有挂起的批更新写入磁盘。

语法

recordset .UpdateBatch AffectRecords

参数

AffectRecords    可选， AffectEnum 值。决定 UpdateBatch 方法所影响的记录数目。可以为如下常量之一。

常量 说明 adAffectCurrent 只写入当前记录的挂起更改。 adAffectGroup 写入满足当前 Filter 属性设置的记录所发生的挂起更改。必须将 Filter 属性设置为某个有效的预定义常量才能使用该选项。 adAffectAll （默认值）。写入 Recordset 对象中所有记录的挂起更改，包括由于当前 Filter 属性设置而隐藏的任何记录。 adAffectAllChapters 写入所有子集的挂起更改。

说明

按批更新模式修改 Recordset 对象时，使用 UpdateBatch 方法可将 Recordset 对象中的所有更改传递到基本数据库。

如果 Recordset 对象支持批更新，那么可以将一个或多个记录的多重更改缓存在本地，然后再调用 UpdateBatch 方法。如果在调用 UpdateBatch 方法时正在编辑当前记录或者添加新的记录，那么在将批更新传送到提供者之前， ADO 将自动调用 Update 方法保存对当前记录的所有挂起更改。

注意     只能对键集或静态游标使用批更新。

如果由于与基本的数据冲突而导致对所有或任意记录的传送更改失败（如其他用户已将记录删除），那么提供者将把警告返回给 Errors 集合，并发生运行时错误。使用 Filter 属性 (adFilterAffectedRecords) 和 Status 属性可以找到发生冲突的记录。

要取消所有挂起的批更新，请使用 CancelBatch 方法。

如果设置了 Unique Table 和 Update Resync 动态属性，并且 Recordset 是对多个表执行 JOIN 操作的结果，那么，取决于 Update Resync 属性，执行 UpdateBatch 方法会隐性导致 Resync 方法。