共用方式為

ISSAsynchStatus::GetStatus (OLE DB)

  • 發行項

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System (PDW)

下載 OLE DB 驅動程式

傳回以非同步方式執行作業的狀態。

語法

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

引數

hChapter[in]
章節控制代碼。 如果輪詢的物件不是資料列集物件，或者作業不適用於章節，則其應該設定為 DB_NULL_HCHAPTER (提供者會加以忽略)。

eOperation[in]
正在要求其非同步狀態的作業。 應使用下列值：

DBASYNCHOP_OPEN：取用者會要求有關非同步開啟或資料列集擴展的資訊，或有關資料來源物件的非同步初始化的資訊。 如果提供者是 OLE DB 2.5 相容且支援 URL 直接繫結的提供者，則取用者會要求有關非同步初始化或資料來源、資料列集、資料列或資料流物件擴展的資訊。

pulProgress[out]
記憶體的指標，會從中傳回相對於 pulProgressMax 參數所指出之預期最大值的非同步作業的目前進度。 如需 pulProgress 之意義的詳細資訊，請參閱 peAsynchPhase 的描述。

如果 pulProgress 是 Null 指標，則不會傳回任何進度。

pulProgressMax[out]
記憶體的指標，會從中傳回 pulProgress 參數的預期最大值。 此值可能會在此方法的呼叫之間變更。 如需 pulProgressMax 之意義的詳細資訊，請參閱 peAsynchPhase 的描述。

如果 pulProgressMax 是 Null 指標，則不會傳回預期的最大值。

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 是 Null 指標，則不會傳回狀態碼。

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::Commit 或 ITransaction::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，或者為 eOperation 傳遞 DBASYNCHOP_OPEN 以外的值，會傳回 S_OK，且 pulProgress 和 pulProgressMax 都設定為相同值。 如果在執行更新、刪除或插入資料列的命令而建立的物件上呼叫 ISSAsynchStatus::GetStatus 方法，則 pulProgress 和 pulProgressMax 都會指出受到該命令影響的資料列總數。

另請參閱

執行非同步作業
ISSAsynchStatus (OLE DB)