ISSAsynchStatus::GetStatus (OLE DB)

Dotyczy do:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSystem Platform Analitycznych (PDW)Baza danych SQL w Microsoft Fabric

pobierz sterownik OLE DB

Zwraca status operacji wykonywanej asynchronicznie.

Składnia

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

Arguments

hChapter[w]
Uchwyt rozdziału. Jeśli badany obiekt nie jest obiektem wiersza lub operacja nie dotyczy rozdziału, powinien być ustawiony na DB_NULL_HCHAPTER, co jest ignorowane przez dostawcę.

eOperation[in]
Operacja, dla której żądany jest status asynchroniczny. Należy użyć następującej wartości:

DBASYNCHOP_OPEN-The konsument prosi o informacje o asynchronicznym otwarciu lub zaludnieniu zbioru wierszy albo o asynchronicznej inicjalizacji obiektu źródła danych. Jeśli dostawca jest zgodny z OLE DB 2.5, który obsługuje bezpośrednie wiązanie URL, konsument żąda informacji o asynchronicznej inicjalizacji lub zaludnieniu źródła danych, wiersza, wiersza lub obiektu strumienia.

pulProgress[out]
Wskaźnik do pamięci, w którym można zwrócić bieżący postęp operacji asynchronicznej względem oczekiwanego maksimum wskazanego w parametrze pulProgressMax . Więcej informacji o znaczeniu pulProgress można znaleźć w opisie peAsynchPhase.

Jeśli pulProgress jest wskaźnikiem null, postęp nie jest zwracany.

pulProgressMax[out]
Wskaźnik do pamięci, w którym można zwrócić oczekiwaną maksymalną wartość parametru pulProgress . Ta wartość może się zmieniać w zależności od wywołań tej metody. Więcej informacji o znaczeniu pulProgressMax, zobacz opis peAsynchPhase.

Jeśli pulProgressMax jest wskaźnikiem zerowym, nie zwraca się oczekiwanej maksymalnej wartości.

peAsynchPhase[out]
Wskaźnik do pamięci, w którym można zwrócić dodatkowe informacje o postępie operacji asynchronicznej. Prawidłowe wartości to:

DBASYNCHPHASE_INITIALIZATION-The obiekt znajduje się w fazie inicjalizacji. Argumenty pulProgress i pulProgressMax wskazują szacowany stosunek ukończenia. Obiekt nie został jeszcze w pełni zmaterializowany. Próba wywołania innych interfejsów może się nie powiódć, a pełny zestaw interfejsów może nie być dostępny na obiekcie. Jeśli operacja asynchroniczna była wynikiem wywołania ICommand::Execute dla polecenia, które aktualizuje, usuwa lub wstawia wiersze, a cParamSets jest większe niż 1, pulProgress i pulProgressMax mogą wskazywać postęp dla pojedynczego zestawu parametrów lub dla pełnej tablicy zestawów parametrów.

DBASYNCHPHASE_POPULATION-The obiekt znajduje się w fazie populacji. Chociaż zestaw wierszy jest w pełni zainicjalizowany, a pełny zakres interfejsów dostępny jest na obiekcie, mogą istnieć dodatkowe wiersze, które jeszcze nie zostały zamieszczone w zestawie wierszy. Chociaż pulProgress i pulProgressMax mogą być oparte na liczbie wierszy wypełnionych, zazwyczaj opierają się one na czasie lub wysiłku potrzebnym do wypełnienia zestawu wierszy. Dzwoniący powinien więc wykorzystać te informacje jako przybliżone oszacowanie czasu trwania procesu, a nie ostateczną liczbę wierszy. Ta faza jest zwracana tylko podczas zaludnienia zestawu wierszowego; nigdy nie jest zwracana podczas inicjalizacji obiektu źródła danych ani przez wykonanie polecenia, które aktualizuje, usuwa lub wstawia wiersze.

DBASYNCHPHASE_COMPLETE-All asynchroniczne przetwarzanie obiektu zostało zakończone. Metoda ISSAsynchStatus::GetStatus zwraca wynik HED wskazujący wynik operacji. Zazwyczaj jest to HRESULT, który zostałby zwrócony, gdyby operacja była wywołana synchronicznie. Jeśli operacja asynchroniczna była wynikiem wywołania ICommand::Execute dla polecenia, które aktualizuje, usuwa lub wstawia wiersze, pulProgress i pulProgressMax są równe łącznej liczbie wierszy dotkniętych przez polecenie. Jeśli cParamSets jest większy niż 1, jest to całkowita liczba wierszy dotkniętych przez wszystkie zestawy parametrów określone w wykonaniu. Jeśli peAsynchPhase jest wskaźnikiem zerowym, nie zwraca się kodu statusu.

DBASYNCHPHASE_CANCELED-Asynchronous przetwarzanie obiektu zostało przerwane. Metoda ISSAsynchStatus::GetStatus zwraca DB_E_CANCELED. Jeśli operacja asynchroniczna była wynikiem wywołania ICommand::Execute dla polecenia, które aktualizuje, usuwa lub wstawia wiersze, pulProgress jest równy całkowitej liczbie wierszy dla wszystkich zestawów parametrów, na które polecenie upłynie przed anulowaniem.

ppwszStatusText[in/out]
Wskaźnik do pamięci zawierający dodatkowe informacje o operacji. Dostawca może użyć tej wartości do rozróżnienia różnych elementów operacji – na przykład różnych dostępnych zasobów. Ten ciąg jest lokalizowany zgodnie z własnością DBPROP_INIT_LCID na obiekcie źródłowym danych.

Jeśli ppwszStatusText jest nie-null przy wejściu, dostawca zwraca status powiązany z konkretnym elementem zidentyfikowanym przez ppwszStatusText. Jeśli ppwszStatusText nie wskazuje elementu eOperation, dostawca zwraca S_OK z pulProgress i pulProgressMax ustawionymi na tę samą wartość. Jeśli dostawca nie rozróżni elementów na podstawie identyfikatora tekstowego, ustawia ppwszStatusText na NULL i zwraca informacje o całej operacji; w przeciwnym razie, jeśli ppwszStatusText nie jest null przy wejściu, dostawca pozostawia ppwszStatusText nietknięty.

Jeśli ppwszStatusText jest null przy wejściu, dostawca ustawia ppwszStatusText na wartość wskazującą więcej informacji o operacji, lub na NULL, jeśli takie informacje nie są dostępne lub jeśli metoda ISSAsynchStatus::GetStatus zwraca błąd. Gdy ppwszStatusText jest null przy wejściu, dostawca przydziela pamięć na ciąg statusu i zwraca adres do tej pamięci. Konsument zwalnia tę pamięć z IMalloc::Free , gdy nie potrzebuje już tego ciągu danych.

Jeśli ppwszStatusText jest NULL przy wejściu, nie zwraca się żadnego ciągu statusu, a dostawca zwraca informacje o dowolnym elemencie operacji lub o operacji w ogóle.

Zwracanie wartości kodu

S_OK
Metoda powróciła pomyślnie.

• Jeśli peAsynchPhase jest równy DBASYNCHPHASE_INITIALIZATION, obiekt nie jest jeszcze w pełni zainicjalizowany; próba wywołania innych interfejsów może się nie powiodować, a pełny zestaw interfejsów może nie być dostępny na obiekcie.

• Jeśli peAsynchPhase jest równy DBASYNCHPHASE_POPULATION, zestaw wierszy jest w pełni inicjowany i pełny zakres interfejsów jest dostępny na obiekcie; Jednak mogą istnieć dodatkowe wiersze, które jeszcze nie zostały zapełnione w zestawie wierszy.

• Jeśli peAsynchPhase jest równy DBASYNCHPHASE_COMPLETE, całe asynchroniczne przetwarzanie obiektu zostało zakończone. Obiekt jest w pełni inicjalizowany i zapełniony.

DB_E_CANCELED
Przetwarzanie asynchroniczne było anulowane podczas zaludniania wierszy. Populacja się zatrzymuje, ale zestaw wierszy pozostaje ważny dla już zamieszkanych wierszy.

Przetwarzanie asynchroniczne zostało anulowane podczas inicjalizacji obiektu źródła danych. Obiekt źródła danych znajduje się w stanie niezainicjalizowanym.

E_INVALIDARG
Parametr hChapter jest nieprawidłowy.

E_UNEXPECTED
Metoda ISSAsynchStatus::GetStatus została wywołana na obiekcie źródłowym danych, a IDBInitialize::Initialize nie została wywołana na obiekcie źródłowym danych.

Metoda ISSAsynchStatus::GetStatus została wywołana na rowsecie, wywołano ITransaction::Commit lub ITransaction::Abort , a obiekt znajduje się w stanie zombie.

Metoda ISSAsynchStatus::GetStatus została wywołana na zestawie wierszowym, który został asynchronicznie anulowany w fazie inicjalizacji. Zestaw wierszy jest w stanie zombie.

E_FAIL
Wystąpił błąd specyficzny dla operatora.

Uwagi

Metoda ISSAsynchStatus::GetStatus zachowuje się dokładnie jak metoda IDBAsynchStatus::GetStatus , z tą różnicą, że jeśli inicjalizacja obiektu źródłowego danych zostanie przerwana, zwraca się E_UNEXPECTED zamiast DB_E_CANCELED (choć ISSAsynchStatus::WaitForAsynchCompletion zwraca DB_E_CANCELED). Dzieje się tak, ponieważ obiekt źródłowy danych nie pozostaje w zwykłym stanie zombie po przerwaniu abortu, aby można było podjąć dalsze operacje inicjalizacyjne.

Jeśli zestaw wierszy jest inicjowany lub wypełniany asynchronicznie, musi obsługiwać tę metodę.

Oprócz wymienionych wartości zwrotu, ISSAsynchStatus::GetStatus może zwrócić dowolny HRESULT, który został zwrócony przez metodę inicjującą operację asynchroniczną, wskazując powodzenie lub niepowodzenie operacji.

Niektóre operacje asynchroniczne mogą nie być w stanie zwrócić żadnych stanów poza "zakończone" i "niezakończone". Powinni ustawić pulProgressMax na wartość 1, co wskazuje na szczegółowość ich szacunku typu wszystko albo nic, więc ich odpowiedzi będą wynosić 0/1 lub 1/1.

Dostawca może zmieniać pulProgressMax w kolejnych połączeniach, a nawet zwracać w mniejszym stopniu niż wcześniej, jeśli odzwierciedla to poprawiające się oszacowanie stopnia ukończenia zadania.

Dostawca nie jest zobowiązany do zapewnienia dalszej dokładności, ale zaleca się to w przypadkach, gdy możliwe są rozsądne szacunki ukończenia. Takie działania poprawią jakość interfejsu użytkownika, ponieważ głównym zastosowaniem tej funkcji jest prawdopodobnie przekazywanie użytkownikowi informacji zwrotnej o postępach. Satysfakcja użytkownika rośnie wraz z jakością informacji zwrotnej na temat niewidocznego, długotrwałego zadania.

Wywołanie ISSAsynchStatus::GetStatus na zainicjalizowanym obiekcie źródłowym danych lub zaludnionym zestawie wierszy, albo przekazanie wartości eOperation innej niż DBASYNCHOP_OPEN, zwraca S_OK z pulProgress i pulProgressMax ustawionymi na tę samą wartość. Jeśli metoda ISSAsynchStatus::GetStatus zostanie wywołana na obiekcie utworzonym w wyniku wykonania polecenia, które aktualizuje, usuwa lub wstawia wiersze, zarówno pulProgress , jak i pulProgressMax wskazują łączną liczbę wierszy objętych poleceniem.

Zobacz też

Wykonywanie operacji asynchronicznych
ISSAsynchStatus (OLE DB)