ADO API 参考( ADO 属性)

指示字段的值的实际长度。

设置和返回值

返回长整型值。某些提供者允许设置该属性以便为 BLOB 数据预留空间，在此情况下默认值为 0。

说明

使用 ActualSize 属性可返回 Field 对象值的实际长度。对于所有字段，ActualSize 属性为只读。如果 ADO 无法确定 Field 对象值的实际长度，ActualSize 属性将返回 adUnknown。

如以下范例所示，ActualSize 和  DefinedSize 属性有所不同：adVarChar 声明类型且最大长度为 50 个字符的 Field 对象将返回为 50 的 DefinedSize 属性值，但是返回的 ActualSize 属性值是当前记录的字段中存储的数据的长度。

指示对象的一项或多项特性。

设置和返回值

设置或返回长整型值。

对于 Connection 对象，Attributes 属性为读/写，并且其值可能为以下任意一个或多个 XactAttributeEnum 值的和（默认为零）。

常量 说明 AdXactCommitRetaining 执行保留的提交，即通过自动调用 CommitTrans 启动新事务。并非所有提供者都支持该常量。 AdXactAbortRetaining 执行保留的中止，即通过自动调用 RollbackTrans 启动新事务。并非所有提供者都支持该常量。

对于 Parameter 对象，Attributes 属性为读/写，并且其值可能为以下任意一个或多个 ParameterAttributesEnum 值的和。

常量 说明 AdParamSigned 默认值。指示该参数接受带符号的值。 AdParamNullable 指示该参数接受 Null 值。 AdParamLong 指示该参数接受长二进制数据。

对于 Field 对象，Attributes 属性为只读，其值可能为以下任意一个或多个 FieldAttributeEnum 值的和。

常量 说明 adFldMayDefer 指示字段被延迟，即不从拥有整个记录的数据源检索字段值，仅在显式访问这些字段时才进行检索。 adFldUpdatable 指示可以写入该字段。 adFldUnknownUpdatable 指示提供者无法确定是否可以写入该字段。 adFldFixed 指示该字段包含定长数据。 adFldIsNullable 指示该字段接受 Null 值。 adFldMayBeNull 指示可以从该字段读取 Null 值。 adFldLong 指示该字段为长二进制字段。并指示可以使用 AppendChunk 和 GetChunk 方法。 adFldRowID 指示字段包含持久的行标识符，该标识符无法被写入并且除了对行进行标识（如记录号、唯一标识符等）外不存在有意义的值。 adFldRowVersion 指示该字段包含用来跟踪更新的某种时间或日期标记。 adFldCacheDeferred 指示提供者缓存了字段值，并已完成随后对缓存的读取。

对于 Property 对象，Attributes 属性为只读，并可能是以下任意一个或多个 PropertyAttributesEnum 值的和：

常量 说明 adPropNotSupported 指示提供者不支持该属性。 adPropRequired 指示数据源初始化之前用户必须指定该属性的值。 adPropOptional 指示数据源初始化之前用户不必为该属性指定值。 adPropRead 指示用户可以读取该属性。 adPropWrite 指示用户可以设置该属性。

说明

使用 Attributes 属性可设置或返回 Connection 对象、Paramete 对象、Field 对象或 Property 对象的特性。

设置多个属性时，可以将相应的常量相加。如果将属性值设置为包括不兼容常量的总和，那么将产生错误。

远程数据服务用法   该属性在客户端的 Connection 对象上无效。

返回值

BOF 和 EOF 属性返回布尔型值。

说明

使用 BOF 和 EOF 属性可确定 Recordset 对象是否包含记录，或者从一个记录移动到另一个记录时是否超出 Recordset 对象的限制。

如果当前记录位于第一个记录之前，BOF 属性将返回 True (-1)，如果当前记录为第一个记录或位于其后则将返回 False (0)。

如果当前记录位于 Recordset 对象的最后一个记录之后 EOF 属性将返回 True，而当前记录为 Recordset 对象的最后一个记录或位于其前，则将返回 False。

如果 BOF 或 EOF 属性为 True，则没有当前记录。

如果打开没有记录的 Recordset 对象，BOF 和 EOF 属性将设置为 True，而 Recordset 对象的 RecordCount 属性设置为零。打开至少包含一条记录的 Recordset 对象时，第一条记录为当前记录，而 BOF 和 EOF 属性为 False。

如果删除 Recordset 对象中保留的最后记录，BOF 和 EOF 属性将保持 False，直到重新安排当前记录。

以下表格说明不同 BOF 和 EOF 属性组合所允许的 Move 方法。

MoveFirst,
MoveLast MovePrevious,
Move < 0
Move 0 MoveNext,
Move > 0 BOF=True,
EOF=False 允许 错误 错误 允许 BOF=False,
EOF=True 允许 允许 错误 错误 同时为 True 错误 错误 错误 错误 同时为 False 允许 允许 允许 允许

允许使用 Move 方法并不能保证该方法成功定位记录，只是意味着调用指定的 Move 方法不会产生错误。

下表说明当调用各种 Move 方法但未成功定位记录时 BOF 和 EOF 属性设置所发生的情况。

BOF EOF MoveFirst, MoveLast 设置为 True 设置为 True Move 0 没有变化 没有变化 MovePrevious, Move < 0 设置为 True 没有变化 MoveNext, Move > 0 没有变化 设置为 True

返回唯一标识 Recordset 对象中当前记录的书签，或者将 Recordset 对象的当前记录设置为由有效书签所标识的记录。

设置和返回值

设置或返回计算有效书签的变体型表达式。

说明

使用 Bookmark 属性可保存当前记录的位置并随时返回到该记录。书签只能在支持书签功能的 Recordset 对象中使用。

打开 Recordset 对象时，其每个记录都有唯一的书签。要保存当前记录的书签，请将 Bookmark 属性的值赋给一个变量。移动到其他记录后要快速返回到该记录，请将该 Recordset 对象的 Bookmark 属性设置为该变量的值。

用户可能无法查看书签的值，也同样无法对书签直接进行比较（指向同一记录的两个书签的值可能不同）。

如果使用 Clone 方法创建 Recordset 的一个副本，则原始的和复制的 Recordset 对象 Bookmark 属性设置相同并可以替换使用。但是，无法替换使用不同 Recordset 对象的书签，即使这些书签是通过同一数据源或命令创建的。

远程数据服务用法   在客户端 (ADOR) Recordset 对象上使用时，Bookmark 属性始终有效。

指示缓存在本地内存中的 Recordset 对象的记录数。

设置和返回值

设置或返回必须大于 0 的长整型值。默认值为 1。

说明

使用 CacheSize 属性可控制提供者在缓存中所保存的记录的数目，并可控制一次恢复到本地内存的记录数。例如，如果 CacheSize 为 10，首次打开 Recordset 对象后，提供者将前面 10 个记录调入本地内存。当在 Recordset 对象中移动时，提供者返回本地内存缓冲区中的数据；一旦移动超过缓存中最后的记录，提供者便将数据源中随后的 10 个记录恢复到缓存。

可以在 Recordset 对象的存活期调整该属性的值，但是更改该值只影响随后从数据源调入缓存的记录数。只更改属性值将不会更改缓存中的当前内容。

如果要检索的记录较 CacheSize 指定的少，提供者将返回其余的记录，不会产生错误。

不允许将 CacheSize 设置为零，否则将返回错误。

从缓存恢复的记录不反映其他用户对数据源同时所作的更改。如需强行对所有缓存数据进行更新，请使用 Resync 方法。

包含要根据提供者发送的命令的文本。

设置和返回值

设置或返回包含提供者命令（如 SOL 语句、表格名称或存储的过程调用）的字符串值。默认值为 ""（零长度字符串）。

说明

使用 CommandText 属性可设置或返回 Command 对象的文本。通常，该属性为 SQL 语句，但也可以是提供者识别的任何其他类型的命令语句（如存储的过程调用）。SQL 语句必须是提供者查询处理程序支持的特定语法或版本。

如果设置 CommandText 属性时将 Command 对象的 Prepared 属性设置为 True，并将 Command 对象绑定到打开的连接，则在调用 Execute 或 Open 方法时 ADO 将准备查询（即，提供者保存已编译的查询格式）。

取决于 CommandType 属性的设置，ADO 可能改变 CommandText 属性。请随时阅读 CommandText 属性查看在执行过程中 ADO 将要使用的实际命令文本。

指示在终止尝试和产生错误之前执行命令期间需等待的时间。

设置和返回值

设置或返回长整型值，该值指示等待命令执行的时间（单位为秒）。默认值为 30。

说明

使用 Connection 对象或 Command 上的 CommandTimeout 属性，允许由于网络拥塞或服务器负载过重产生的延迟而取消 Execute 方法调用。如果在 CommandTimeout 属性中设置的时间间隔内没有完成命令执行，将产生错误，然后 ADO 将取消该命令。如果将该属性设置为零，ADO 将无限期等待直到命令执行完毕。请确保正在写入代码的提供者和数据源支持 CommandTimeout 功能。

Connection 对象的 CommandTimeout 设置不会对相同 Connection 上 Command 对象的 CommandTimeout 设置产生影响，即 Command 对象的 CommandTimeout 属性不继承 Connection 对象的 CommandTimeout 的值。

在 Connection 对象上，打开 Connection 后，CommandTimeout 属性将保持读/写。

指示 Command 对象的类型。

设置和返回值

设置或返回以下某个 CommandTypeEnum 值。

常量 说明 AdCmdText 将 CommandText 作为命令或存储过程调用的文本化定义进行计算。 AdCmdTable 将 CommandText 作为其列全部由内部生成的 SQL 查询返回的表格的名称进行计算。 AdCmdTableDirect 将 CommandText 作为其列全部返回的表格的名称进行计算。 AdCmdStoredProc 将 CommandText 作为存储过程名进行计算。 AdCmdUnknown 默认值。CommandText 属性中的命令类型未知。 adCmdFile 将 CommandText 作为持久 Recordset 文件名进行计算。 AdExecuteNoRecords 指示 CommandText 为不返回行的命令或存储过程（例如，插入数据的命令）。如果检索任意行，则将丢弃这些行且并不返回。它总是与 adCmdText 或 adCmdStoredProc 进行组合。

说明

使用 CommandType 属性可优化 CommandText 属性的计算。

如果 CommandType 属性的值等于 adCmdUnknown（默认值），系统的性能将会降低，因为 ADO 必须调用提供者以确定 CommandText 属性是 SQL 语句、还是存储过程或表格名称。如果知道正在使用的命令的类型，可通过设置 CommandType 属性指令 ADO 直接转到相关代码。如果 CommandType 属性与 CommandText 属性中的命令类型不匹配，调用 Execute 方法时将产生错误。

adExecuteNoRecords 常量通过最小化内部处理来提高性能。该常量不独立使用，它总是与 adCmdText 或 adCmdStoredProc 组合（如 adCmdText+adExecuteNoRecords）一起使用。如果与 Recordset.Open 一起使用 adExecuteNoRecords，或者该方法使用 Command 对象都将产生错误。

设置或返回对其运行查询和更新操作的数据库名称。

可以在设计时在 RDS.DataControl 对象的 OBJECT 标记中设置 Connect 属性，或者在运行时在脚本代码（如 VBScript）中设置 Connect 属性。

语法

设计时：<PARAM NAME="Connect" VALUE="DSN=DSNName;UID=usr;PWD=pw;">

运行时：DataControl.Connect = "DSN=DSNName;UID=usr;PWD=pw;"

参数

DSNName   指定系统数据源名称的字符串，该系统数据源名称标识指定的数据库。

usr   表示服务器上合法用户帐号的字符串。

pw   表示用户帐号合法密码的字符串。

DataControl   表示 RDS.DataControl 对象的对象变量。

包含用于建立连接数据源的信息。

设置和返回值

设置或返回字符串值。

说明

使用 ConnectionString 属性，通过传递包含一系列由分号分隔的 argument = value 语句的详细连接字符串可指定数据源。

ADO 支持 ConnectionString 属性的四个参数，任何其他参数将直接传递到提供者而不经过 ADO 处理。ADO 支持的参数如下：

参数 说明 Provider= 指定用来连接的提供者名称。 File Name= 指定包含预先设置连接信息的特定提供者的文件名称（例如，持久数据源对象）。 Remote Provider= 指定打开客户端连接时使用的提供者名称。（仅限于远程数据服务） Remote Server= 指定打开客户端连接时使用的服务器的路径名称。（仅限于远程数据服务）

设置 ConnectionString 属性并打开 Connection 对象后，提供者可以更改属性的内容，例如通过将 ADO 定义的参数名映射到其提供者等价项来更改属性的内容。

ConnectionString 属性将自动继承用于 Open 方法的 ConnectionString 参数的值，以便在 Open 方法调用期间覆盖当前的 ConnectionString 属性。

由于 File Name 参数使得 ADO 加载关联的提供者，因此无法传递 Provider 和 File Name 参数。

连接关闭时 ConnectionString 属性为读/写，打开时其属性为只读。

远程数据服务用法   在客户端 Connection 对象上使用该服务时，ConnectionString 属性只能包括 Remote Provider 和 Remote Server 参数。

指示在终止尝试和产生错误前建立连接期间所等待的时间。

设置和返回值

设置或返回指示等待连接打开的时间的长整型值（单位为秒）。默认值为 15。

说明

如果由于网络拥塞或服务器负载过重导致的延迟使得必须放弃连接尝试时，请使用 Connection 对象的 ConnectionTimeout 属性。如果打开连接前所经过的时间超过 ConnectionTimeout 属性上设置的时间，将产生错误，并且 ADO 将取消该尝试。如果将该属性设置为零，ADO 将无限等待直到连接打开。请确认正在对其编写代码的提供者会支持 ConnectionTimeout 功能。

连接关闭时 ConnectionTimeout 属性为读/写，而打开时其属性为只读。

指示集合中对象的数目。

返回值

返回长整型值。

说明

使用 Count 属性可确定给定集合中对象的数目。

因为集合成员的编号从零开始，因此应该始终以零成员开头且以 Count 属性的值减 1 结尾而进行循环编码。如果正在使用 Microsoft® Visual Basic® 并想在不使用 Count 属性的情况下在集合的成员中循环操作，请使用 For Each...Next 命令。

如果 Count 属性为零，集合中将不存在对象。

设置或返回游标服务的位置。

设置和返回值

设置或返回可设置为以下某个常量的长整型值。

常量 说明 adUseNone 没有使用游标服务。（该常量已过时并且只为了向后兼容才出现）。 adUseClient 使用由本地游标库提供的客户端游标。本地游标服务通常允许使用的许多功能可能是驱动程序提供的游标无法使用的，因此使用该设置对于那些将要启用的功能是有好处的。AdUseClient 具有向后兼容性，也支持同义的 adUseClientBatch。 adUseServer 默认值。使用数据提供者的或驱动程序提供的游标。这些游标有时非常灵活，对于其他用户对数据源所作的更改具有额外的敏感性。但是，Microsoft Client Cursor Provider（如已断开关联的记录集）的某些功能无法由服务器端游标模拟，通过该设置将无法使用这些功能。

说明

该属性允许在可用于提供者的各种游标库中进行选择。通常，可以选择使用客户端游标库或位于服务器上的某个游标库。

该属性设置仅对属性已经设置后才建立的连接有影响。更改 CursorLocation 属性不会影响现有的连接。

对于 Connection 或关闭的 Recordset 该属性为读/写，而对打开的 Recordset 该属性为只读。

由 Execute 方法返回的游标继承该设置。Recordset 将自动从与之关联的连接中继承该设置。

远程数据服务用法   当用于客户端 (ADOR) Recordset 或 Connection 对象时，只能将 CursorLocation 属性设置为 adUseClient。

指示在 Recordset 对象中使用的游标类型。

设置和返回值

设置或返回以下某个 CursorTypeEnum 值。

常量 说明 AdOpenForwardOnly 仅向前游标，默认值。除了只能在记录中向前滚动外，与静态游标相同。当只需要在记录集中单向移动时，使用它可提高性能。 AdOpenKeyset 键集游标。尽管从您的记录集不能访问其他用户删除的记录，但除无法查看其他用户添加的记录外，键集游标与动态游标相似。仍然可以看见其他用户更改的数据。 AdOpenDynamic 动态游标。可以看见其他用户所作的添加、更改和删除。允许在记录集中进行所有类型的移动，但不包括提供者不支持的书签操作。 AdOpenStatic 静态游标。可以用来查找数据或生成报告的记录集合的静态副本。另外，对其他用户所作的添加、更改或删除不可见。

说明

使用 CursorType 属性可指定打开 Recordset 对象时应该使用的游标类型。Recordset 关闭时 CursorType 属性为读/写，而 Recordset 打开时该属性为只读。

如果将 CursorLocation 属性设置为 adUseClient 则只支持 adUseStatic 的设置。如果设置了不支持的值，不会导致错误，将使用最接近支持的 CursorType。

如果提供者不支持所请求的游标类型，提供者可能会返回其他游标类型。打开 Recordset 对象时，将更改 CursorType 属性使之与实际使用的游标匹配。要验证返回游标的指定功能，请使用 Supports 方法。关闭 Recordset 后，CursorType 属性将恢复为最初的设置。

下表说明每个游标类型所需的提供者功能（由 Supports 方法常量标识）。

对于该 CursorType 的某Recordset 对于所有这些常量， Supports 方法必须返回 True AdOpenForwardOnly 无 AdOpenKeyset AdBookmark、adHoldRecords、adMovePrevious、adResync AdOpenDynamic adMovePrevious AdOpenStatic adBookmark, adHoldRecords, adMovePrevious, adResync

注意   尽管对于动态游标和仅向前游标 Supports(adUpdateBatch) 可能是真，但对于批处理更新应使用键集游标或静态游标。请将 LockType 属性设置为 adLockBatchOptimistic，然后将 CursorLocation 属性设置为 adUseClient 以启用批更新需要的 OLE DB 游标服务。

远程数据服务用法   当用于客户端 (ADOR) Recordset 对象时，只能将 CursorType 属性设置为 adOpenStatic。

指定要从 DataSource 属性所引用的对象中检索的数据成员的名称。

设置和返回值

设置或返回字符串值。名称不区分大小写。

说明

该属性用于通过“数据环境”创建数据绑定控件。“数据环境”保存着数据集合（数据源），而数据集合包含将被表示为 Recordset 对象的已命名对象（数据成员）。

DataMember 和 DataSource 属性必须连同使用。

DataMember 属性决定将把 DataSource 属性所指定的哪个对象作为 Recordset 对象提取出来。设置该属性前必须关闭 Recordset 对象。如果在设置 DataSource 属性前没有设置 DataMember 属性，或者在 DataSource 属性中指定的对象不能识别 DataMember 名称，都将产生错误。

详细信息，请参阅“Data Access SDK”的“Control Writer”部分内容。

用法

Dim rs as New ADODB.Recordset rs.DataMember = "Command" '需绑定的行集合名称 Set rs.DataSource = myDE '包含 IRowset 的对象名称

DataSource 属性

指定所包含的数据将被表示为 Recordset 对象的对象。

说明

该属性用于通过“数据环境”创建数据绑定控件。“数据环境”保存着数据集合（数据源），而数据集合包含将被表示为 Recordset 对象的已命名对象（数据成员）。

DataMember 和 DataSource 属性必须连同使用。

所引用的对象必须执行 IDataSource 接口，并且必须包含 IRowset 接口。

详细信息，请参阅“Data Access SDK”的“Control Writer”部分内容。

用法

Dim rs as New ADODB.Recordset rs.DataMember = "Command" '要绑定到的行集合的名称 Set rs.DataSource = myDE '包含 IRowset 的对象的名称

DefaultDatabase 属性

指示 Connection 对象的默认数据库。

设置和返回值

设置或返回字符串来计算出从提供者处可用的数据库的名称。

说明

使用 DefaultDatabase 属性可设置或返回指定 Connection 对象上默认数据库的名称。

如果有默认数据库，SQL 字符串可使用非限定语法访问该数据库中的对象。如要访问 DefaultDatabase 属性中指定数据库以外的数据库中的对象，对象名必须与所需的数据库名称匹配。连接时，提供者将默认数据库信息写入 DefaultDatabase 属性。某些提供者对于每个连接只允许一个数据库，在此情况下将不能更改 DefaultDatabase 属性。

某些数据源和提供者可能不支持此项功能，这时将返回错误或空的字符串。

远程数据服务用法   该属性在客户端的 Connection 对象上无效。