ISSAsynchStatus::GetStatus (Native Client OLE DB Provider)

适用于:SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics 平台系统(PDW)

重要

已从 SQL Server 2022 (16.x) 和 SQL Server Management Studio 19 (SSMS) 中移除 SQL Server Native Client(通常缩写为 SNAC)。 不建议在新的开发工作中使用 SQL Server Native Client OLE DB 提供程序(SQLNCLI 或 SQLNCLI11)和旧版 Microsoft OLE DB Provider for SQL Server (SQLOLEDB)。 此后请切换到新的 Microsoft OLE DB Driver (MSOLEDBSQL) for SQL Server

返回异步执行操作的状态。

语法

  
HRESULT GetStatus(  
        HCHAPTER hChapter,  
        DBASYNCHOP eOperation,  
        DBCOUNTITEM *pulProgress,  
        DBCOUNTITEM *pulProgressMax,  
        DBASYNCHPHASE *peAsynchPhase,  
        LPOLESTR *ppwszStatusText);  

参数

hChapter[in]
章节句柄。 如果轮询的对象不是行集对象或操作不适用于某一章节,则应将此参数设置为 DB_NULL_HCHAPTER,访问接口将忽略此参数。

eOperation[in]
请求其异步状态的操作。 其值应为:

DBASYNCHOP_OPEN - 使用者请求获取有关行集的异步打开或填充的信息,或有关数据源对象的异步初始化的信息。 如果访问接口是支持直接 URL 绑定且与 OLE DB 2.5 兼容的访问接口,使用者则请求有关异步初始化或填充数据源、行集、行或流对象的信息。

pulProgress[out]
指向内存的指针,将在此内存中返回与 pulProgressMax 参数指示的预期最大值相关的异步操作的当前进度 。 有关 pulProgress 的含义的详细信息,请参阅对 peAsynchPhase 的说明 。

如果 pulProgress 为空指针,则不返回进度 。

pulProgressMax[out]
指向内存的指针,将在此内存中返回 pulProgress 参数的预期最大值 。 此值可以随此方法的每次调用而更改。 有关 pulProgressMax 的含义的详细信息,请参阅对 peAsynchPhase 的说明 。

如果 pulProgressMax 为空指针,则不返回预期的最大值 。

peAsynchPhase[out]
指向内存的指针,将在此内存中返回有关异步操作的进度的其他信息。 有效值包括:

DBASYNCHPHASE_INITIALIZATION - 对象处于初始化阶段。 参数 pulProgress 和 pulProgressMax 指示估计的完成比率 。 对象尚未完全具体化。 尝试调用任何其他接口可能失败,并且可能无法对该对象使用整套接口。 如果异步操作是因调用更新、删除或插入行的命令的 ICommand::Execute 而引起的,并且如果 cParamSets 大于 1,pulProgress 和 pulProgressMax 可以指示一个参数集或所有参数集的进度 。

DBASYNCHPHASE_POPULATION - 对象处于填充阶段。 尽管已完全初始化行集,并且可针对该对象使用整套接口,但是可能还有其他行尚未填充到行集中。 虽然 pulProgress 和 pulProgressMax 可以基于填充的行数,但它们通常基于填充行集所需的时间和工作 。 因此,调用方应将此信息用作对此过程所需时间的粗略估计,而不是最终的行计数。 此阶段仅在填充行集期间返回;它永远不会在数据源对象初始化期间返回,也不会因执行更新、删除或插入行的命令而返回。

DBASYNCHPHASE_COMPLETE - 已完成对象的所有异步处理。 ISSAsynchStatus::GetStatus 返回一个 HRESULT,指示操作的结果。 通常,如果已同步调用操作,则将返回 HRESULT。 如果异步操作是因调用更新、删除或插入行的命令的 ICommand::Execute 而引起的,pulProgress 和 pulProgressMax 则等于该命令所影响的总行数 。 如果 cParamSets 大于 1,则等于执行过程中指定的所有参数集所影响的总行数 。 如果 peAsynchPhase 为空指针,则不返回状态代码 。

DBASYNCHPHASE_CANCELED - 已中止对象的异步处理。 ISSAsynchStatus::GetStatus 返回DB_E_CANCELED。 如果异步操作是因调用更新、删除或插入行的命令的 ICommand::Execute 而引起的,pulProgress 则等于取消之前该命令所影响的所有参数集的总行数 。

ppwszStatusText[in/out]
指向包含有关操作的其他信息的内存的指针。 提供程序可以使用此值来区分不同的操作元素(例如,要访问的不同资源)。 该字符串的本地化形式基于数据源对象的 DBPROP_INIT_LCID 属性。

如果 ppwszStatusText 在输入时为非 Null,提供程序则返回与 ppwszStatusText 标识的特定元素相关联的状态 。 如果 ppwszStatusText 未指示 eOperation 的元素,提供程序则返回 S_OK,并将 pulProgress 和 pulProgressMax 设置为相同的值 。 如果提供程序不能基于文本标识符区分各元素,则会将 ppwszStatusText 设置为 NULL,并返回有关整个操作的信息;否则,如果 ppwszStatusText 在输入时为非 Null,提供程序将使 ppwszStatusText 保持不变 。

如果在 输入时 ppwszStatusText 为 null,则提供程序会将 ppwszStatusText 设置为指示有关操作的详细信息的值,如果没有此类信息,或者 ISSAsynchStatus ::GetStatus 返回错误,则为 NULL。 如果 ppwszStatusText 在输入时为 Null,提供程序将为状态字符串分配内存,并返回此内存的地址 。 如果不再需要此字符串,使用者可以使用 IMalloc::Free 释放此内存 。

如果 ppwszStatusText 在输入时为 NULL,则不会返回状态字符串,提供程序将返回有关操作的任一元素的信息或有关操作的总体信息 。

返回代码值

S_OK
该方法已成功返回。

  • 如果 peAsynchPhase 等于 DBASYNCHPHASE_INITIALIZATION,则尚未完全初始化对象;尝试调用任何其他接口可能失败,并且可能无法对该对象使用整套接口 。

  • 如果 peAsynchPhase 等于 DBASYNCHPHASE_POPULATION,则已完全初始化行集,并且可针对该对象使用整套接口;但是可能还有其他行尚未填充到行集中 。

  • 如果 peAsynchPhase 等于 DBASYNCHPHASE_COMPLETE,则已完成对象的所有异步处理 。 已完全初始化并填充该对象。

DB_E_CANCELED
异步处理在行集填充过程中取消。 填充停止,但是对于已填充的行,该行集仍保持有效。

异步处理在数据源对象的初始化过程中取消。 数据源对象处于未初始化状态。

E_INVALIDARG
hChapter 参数不正确。

E_UNEXPECTED
ISSAsynchStatus::GetStatus 是在数据源对象上调用的,并且 尚未对数据源对象调用 IDBInitialize::Initialize

ISSAsynchStatus::GetStatus 是在行集、 ITransaction::CommitITransaction::Abort 上调用的,对象处于僵尸状态。

ISSAsynchStatus::GetStatus 是在初始化阶段异步取消的行集上调用的。 该行集处于僵停状态。

E_FAIL
发生了特定于访问接口的错误。

备注

ISSAsynchStatus::GetStatus 方法的行为与 IDBAsynchStatus::GetStatus 方法完全类似,不同之处在于如果中止对数据源对象的初始化,前者将返回 E_UNEXPECTED,而不是 DB_E_CANCELED(但是 ISSAsynchStatus::WaitForAsynchCompletion 将返回 DB_E_CANCELED) 。 这是因为在中止后,数据源对象不会照常处于僵停状态,以便进一步尝试初始化操作。

如果异步初始化或填充行集,则必须支持此方法。

除列出的返回值以外,ISSAsynchStatus::GetStatus 还可以返回应由启动异步操作的方法返回的任何 HRESULT,以指示操作成功或失败 。

某些异步操作可能无法返回除“完成”和“尚未完成”以外的任何状态。 这些异步操作应将 pulProgressMax 值设置为 1,指示其估计的粒度(全部粒度或没有任何粒度),因此返回的值将为 0/1 或 1/1

提供程序可以在后续调用中更改 pulProgressMax,甚至返回比先前更小的比率,条件是该比率反映对任务完成程度的改善估计 。

访问接口不必保证任何进一步的准确性,但是对于可以对完成情况进行合理估计的情况,建议执行此工作。 这一工作将改进用户界面的质量,因为此函数的主要用途是向用户提供进度反馈。 由于改善了长期运行的不可见任务的反馈质量,用户的满意度也随之提高。

对已初始化的数据源对象或已填充的行集调用 ISSAsynchStatus::GetStatus,或者传递除 DBASYNCHOP_OPEN 以外的 eOperation 值将返回 S_OK,并将 pulProgress 和 pulProgressMax 设置为相同的值 。 如果在 执行更新、删除或插入行的命令中创建的对象上调用 ISSAsynchStatus::GetStatus则 pulProgresspulProgressMax 都指示受命令影响的行总数。

另请参阅

执行异步操作
ISSAsynchStatus (OLE DB)