SQLGetDiagRec, funkcja

Zgodność
Wprowadzona wersja: Zgodność z normami ODBC 3.0: ISO 92

Podsumowanie
SQLGetDiagRec zwraca aktualne wartości wielu pól rekordu diagnostycznego zawierającego informacje o błędach, ostrzeżeniach i statusie. W przeciwieństwie do SQLGetDiagField, który zwraca jedno pole diagnostyczne na każde połączenie, SQLGetDiagRec zwraca kilka często używanych pól rekordu diagnostycznego, w tym SQLSTATE, natywny kod błędu oraz tekst wiadomości diagnostycznej.

Syntax

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);

Arguments

HandleType
[Dane wejściowe] Identyfikator typu dojścia opisujący typ uchwytu, dla którego wymagana jest diagnostyka. Musi być jednym z następujących elementów:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN dojście jest używane tylko przez Menedżera sterowników i sterownik. Aplikacje nie powinny używać tego typu dojścia. Więcej informacji o SQL_HANDLE_DBC_INFO_TOKEN można znaleźć w artykule Rozwijanie świadomości Connection-Pool u kierowcy ODBC.

Uchwyt
[Dane wejściowe] Dojście dla struktury danych diagnostycznych typu wskazanego przez HandleType. Jeśli handletype jest SQL_HANDLE_ENV, może być współużytkowanym lub nieudostępnym dojściem środowiska.

NumerRekordów
[Dane wejściowe] Wskazuje rekord stanu, z którego aplikacja szuka informacji. Rekordy stanu są numerowane z zakresu 1.

SQLState
[Wyjście] Wskaż do bufora, w którym zwraca pięcioosobowy kod SQLSTATE (kończący NULL) dla rejestru diagnostycznego RecNumber. Pierwsze dwa znaki wskazują klasę; kolejne trzy wskazują podklasę. Informacje te znajdują się w obszarze SQL_DIAG_SQLSTATE diagnostyki. Aby uzyskać więcej informacji, zobacz SQLSTATEs.

NativeErrorPtr
[Wyjście] Wskaźnik do bufora, do którego zwraca natywny kod błędu, specyficzny dla źródła danych. Informacje te zawarte są w dziedzinie SQL_DIAG_NATIVE diagnostyki.

Messagetext
[Wyjście] Wskaźnik do bufora, w którym zwraca ciąg tekstowy wiadomości diagnostycznej. Informacje te znajdują się w dziedzinie diagnostyki SQL_DIAG_MESSAGE_TEXT. Format ciągu można znaleźć w sekcji Wiadomości diagnostyczne.

Jeśli MessageText jest NULL, TextLengthPtr nadal zwraca łączną liczbę znaków (z wyłączeniem znaku zakończenia zera dla danych znaków) dostępnych do zwrócenia w buforze wskazanym przez MessageText.

BufferLength
[Input] Długość bufora *MessageText w znakach. Nie ma maksymalnej długości tekstu wiadomości diagnostycznej.

TextLengthPtr
[Wyjście] Wskaźnik do bufora, w którym można zwrócić łączną liczbę znaków (z wyłączeniem liczby znaków wymaganych dla znaku zakończenia zerowego) dostępnych do zwrotu w *MessageText. Jeśli liczba znaków dostępnych do zwracania jest większa niż BufferLength, tekst wiadomości diagnostycznej w *MessageText jest skracany do BufferLength minus długość znaku zakończenia zerowego.

Zwroty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA lub SQL_INVALID_HANDLE.

Diagnostyka

SQLGetDiagRec nie publikuje dla siebie rekordów diagnostycznych. Używa ona następujących wartości zwracanych w celu raportowania wyniku własnego wykonania:

  • SQL_SUCCESS: funkcja pomyślnie zwróciła informacje diagnostyczne.

  • SQL_SUCCESS_WITH_INFO: Bufor *MessageText był zbyt mały, by pomieścić żądaną wiadomość diagnostyczną. Nie powstały żadne zapisy diagnostyczne. Aby ustalić, że doszło do obcięcia, aplikacja musi porównać BufferLength z rzeczywistą liczbą bajtów, które są zapisywane do *TextLengthPtr.

  • SQL_INVALID_HANDLE: uchwyt wskazywany przez HandleType i Handle nie był prawidłowym uchwytem.

  • SQL_ERROR: Wystąpił jeden z następujących:

    • RecNumber był ujemny lub 0.

    • BufferLength był mniejszy niż zero.

    • W przypadku korzystania z powiadomienia asynchronicznego operacja asynchroniczna na dojściu nie została ukończona.

  • SQL_NO_DATA: RecNumber była większa niż liczba rekordów diagnostycznych, które istniały dla dojścia określonego w Handle. Funkcja zwraca również SQL_NO_DATA dla wszystkich dodatnich RecNumber, jeśli nie ma żadnych rekordów diagnostycznych dladojścia .

Comments

Aplikacja zazwyczaj wywołuje SQLGetDiagRec , gdy poprzednie wywołanie funkcji ODBC zwracało SQL_ERROR lub SQL_SUCCESS_WITH_INFO. Jednakże, ponieważ każda funkcja ODBC może za każdym razem wyświetlić zero lub więcej rekordów diagnostycznych, aplikacja może wywołać SQLGetDiagRec po każdym wywołaniu funkcji ODBC. Aplikacja może wielokrotnie wywoływać SQLGetDiagRec , aby zwrócić część lub wszystkie rekordy w strukturze danych diagnostycznych. ODBC nie nakłada ograniczeń co do liczby rekordów diagnostycznych, które mogą być przechowywane jednocześnie.

SQLGetDiagRec nie może być używany do zwracania pól z nagłówka diagnostycznej struktury danych. (Argument RecNumber musi być większy niż 0.) Aplikacja powinna wywołać SQLGetDiagField w tym celu.

SQLGetDiagRec pobiera tylko informacje diagnostyczne ostatnio powiązane z uchwytem określonym w argumentze Handle . Jeśli aplikacja wywoła inną funkcję ODBC, inną niż SQLGetDiagRec, SQLGetDiagField lub SQLError, wszelkie informacje diagnostyczne z poprzednich wywołań na tym samym uchwytie zostają utracone.

Aplikacja może skanować wszystkie rekordy diagnostyczne poprzez pętlę, zwiększanie RecNumber, pod warunkiem, że SQLGetDiagRec zwraca SQL_SUCCESS. Wywołania do SQLGetDiagRec nie destrukcyjne dla pola nagłówka i rekordu. Aplikacja może ponownie wywołać SQLGetDiagRec w późniejszym czasie, aby pobrać pole z rekordu, o ile w międzyczasie nie zostanie wywołana żadna inna funkcja, poza SQLGetDiagRec, SQLGetDiagField lub SQLError. Aplikacja może również pobrać liczbę dostępnych rekordów diagnostycznych, wywołując SQLGetDiagField w celu pobrania wartości pola SQL_DIAG_NUMBER, a następnie wywołując SQLGetDiagRec tyle razy.

Opis pól struktury danych diagnostycznych można znaleźć w SQLGetDiagField. Aby uzyskać więcej informacji, zobacz Using SQLGetDiagRec and SQLGetDiagField and Implementowanie obiektów SQLGetDiagRec i SQLGetDiagField.

Wywołanie interfejsu API innego niż wykonywane asynchronicznie spowoduje wygenerowanie hy010 "Błąd sekwencji funkcji". Nie można jednak pobrać rekordu błędu przed ukończeniem operacji asynchronicznej.

HandleType, argument

Każdy typ uchwytu może mieć skojarzone z nim informacje diagnostyczne. Argument HandleType oznacza typ uchwytu argumentu Handle .

Niektórych pól nagłówka i rekordu nie można zwracać dla obsługi środowiska, połączenia, instrukcji i deskryptora. Uchwyty, dla których pole nie jest odpowiednie, są wskazane w sekcjach "Head Fields" i "Record Fields" w SQLGetDiagField.

Wywołanie do SQLGetDiagRec zwróci SQL_INVALID_HANDLE jeśli HandleType jest SQL_HANDLE_SENV, co oznacza uchwyt środowiska współdzielonego. Jednak jeśli HandleType jest SQL_HANDLE_ENV, Handle może być zarówno dzielonym, jak i niewspółdzielonym środowiskiem.

Aby uzyskać informacje o Zobacz
Uzyskanie pola w rekordzie diagnostycznym lub pola nagłówka diagnostycznego Funkcja SQLGetDiagField

Treści powiązane

  • Last updated on