ISSAsynchStatus::GetStatus(Native Client OLE DB Provider)
적용 대상: 
SQL Server Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)
Important
SQL Server Native Client(약칭 SNAC)는 SQL Server 2022(16.x) 및 SSMS(SQL Server Management Studio) 19에서 제거되었습니다. SQL Server Native Client OLE DB 공급자(SQLNCLI 또는 SQLNCLI11)와 레거시 Microsoft OLE DB Provider for SQL Server(SQLOLEDB)는 모두 새로운 개발에 권장되지 않습니다. 앞으로 SQL Server용 새 Microsoft OLE DB 드라이버(MSOLEDBSQL)로 전환합니다.
비동기 실행 작업의 상태를 반환합니다.
구문
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가 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의 요소를 나타내지 않으면 공급자는 pulProgress 및 pulProgressMax 를 같은 값으로 설정하여 S_OK를 반환합니다. 공급자가 텍스트 식별자를 기반으로 요소를 구분하지 않으면 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 메서드는 데이터 원본 개체의 초기화가 중단된 경우 E_UNEXPECTED DB_E_CANCELED 대신 반환된다는 점을 제외하고 IDBAsynchStatus::GetStatus 메서드와 정확하게 작동합니다(ISSAsynchStatus::WaitForAsynchCompletion은 DB_E_CANCELED 반환됨). 이는 추가 초기화 작업을 시도할 수 있도록 데이터 원본 개체가 중단 후 일반적인 좀비 상태로 남아 있지 않기 때문입니다.
행 집합이 비동기적으로 초기화되거나 채워진 경우 이 메서드를 지원해야 합니다.
나열된 반환 값 외에도 ISSAsynchStatus::GetStatus 는 비동기 작업을 시작한 메서드에서 반환한 HRESULT를 반환하여 작업의 성공 또는 실패를 나타낼 수 있습니다.
일부 비동기 작업은 "완료됨" 및 "완료되지 않음" 이외의 상태를 반환하지 못할 수 있습니다. pulProgressMax를 1 값으로 설정하여 예상값의 전체 또는 없음 세분성을 나타내야 하므로 답변은 0/1 또는 1/1이 됩니다.
태스크 완료도 예측의 개선을 반영하는 경우 공급자가 연속 호출에서 pulProgressMax 를 변경하고 이전보다 더 작은 비율을 반환할 수도 있습니다.
공급자는 추가 정확도를 보장할 의무가 없지만 합리적인 완료 예측이 가능한 경우 이를 수행하는 것이 좋습니다. 이 함수의 주요 사용은 사용자에게 진행률 피드백을 제공할 가능성이 높기 때문에 이러한 노력은 사용자 인터페이스 품질을 향상시킵니다. 보이지 않는 장기 실행 작업에 대한 피드백 품질에 따라 사용자 만족도가 높아집니다.
초기화된 데이터 원본 개체 또는 채워진 행 집합에서 ISSAsynchStatus::GetStatus를 호출하거나 DBASYNCHOP_OPEN 이외의 eOperation 값을 전달하면 pulProgress 및 pulProgressMax가 동일한 값으로 설정된 S_OK 반환합니다. 행을 업데이트, 삭제 또는 삽입하는 명령을 실행하여 만든 개체에서 ISSAsynchStatus::GetStatus 를 호출하는 경우 pulProgress 및 pulProgressMax 는 모두 해당 명령이 적용된 총 행 수를 나타냅니다.