Funkce SQLGetDiagRec

Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92

Summary
SQLGetDiagRec vrací aktuální hodnoty více polí diagnostického záznamu, který obsahuje chyby, varování a stavové informace. Na rozdíl od SQLGetDiagField, který vrací jedno diagnostické pole při každém hovoru, SQLGetDiagRec vrací několik běžně používaných polí diagnostického záznamu, včetně SQLSTATE, nativního chybového kódu a textu diagnostické zprávy.

Syntax

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

Arguments

HandleType
[Vstup] Identifikátor typu popisovače, který popisuje typ popisovače, pro který se vyžaduje diagnostika. Musí to být jedna z těchto věcí:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN popisovač používá pouze Správce ovladačů a ovladač. Aplikace by neměly používat tento typ popisovače. Pro více informací o SQL_HANDLE_DBC_INFO_TOKEN viz Rozvoj Connection-Pool povědomí u řidiče ODBC.

Ukazatel
[Vstup] Popisovač struktury diagnostických dat typu označený HandleType. Pokud popisovač SQL_HANDLE_ENV, popisovač může být sdílený nebo nesdílený popisovač prostředí.

Přečíslovat
[Vstup] Označuje záznam stavu, ze kterého aplikace hledá informace. Záznamy o stavu jsou očíslovány od 1.

SQLState
[Výstup] Ukazatel na buffer, do kterého se vrátí pětiznakový SQLSTATE kód (a ukončí NULL) pro diagnostický záznam RecNumber. První dva znaky označují třídu; následující tři označují podtřídu. Tyto informace jsou obsaženy v oblasti SQL_DIAG_SQLSTATE diagnostiky. Další informace naleznete v tématu SQLSTATEs.

NativeErrorPtr
[Výstup] Ukazatel na buffer, do kterého se vrací nativní chybový kód specifický pro datový zdroj. Tyto informace jsou obsaženy v oblasti SQL_DIAG_NATIVE diagnostiky.

Text zprávy
[Výstup] Ukazatel na buffer, do kterého se vrátí textový řetězec diagnostické zprávy. Tyto informace jsou obsaženy v oblasti SQL_DIAG_MESSAGE_TEXT diagnostiky. Pro formát řetězce viz Diagnostické zprávy.

Pokud je MessageText NULL, TextLengthPtr stále vrátí celkový počet znaků (kromě znaku null-termination pro data znaku), které lze vrátit v bufferu na který ukazuje MessageText.

BufferLength
[Vstup] Délka bufferu *MessageText v znacích. Neexistuje maximální délka textu diagnostické zprávy.

TextLengthPtr
[Výstup] Ukazatel na buffer, do kterého lze vrátit celkový počet znaků (bez počtu znaků potřebných pro znak null-termination), které lze vrátit v *MessageText. Pokud je počet znaků dostupných k vrácení větší než BufferLength, text diagnostické zprávy v *MessageText je zkrácen na BufferLength minus délka znaku null-termining.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA nebo SQL_INVALID_HANDLE.

Diagnostika

SQLGetDiagRec si sám nezveřejňuje diagnostické záznamy. K hlášení výsledku vlastního spuštění používá následující návratové hodnoty:

  • SQL_SUCCESS: Funkce úspěšně vrátila diagnostické informace.

  • SQL_SUCCESS_WITH_INFO: Buffer *MessageText byl příliš malý na to, aby pojal požadovanou diagnostickou zprávu. Nebyly vytvořeny žádné diagnostické záznamy. Aby aplikace zjistila, že došlo k oříznutí, musí porovnat BufferLength s reálným počtem dostupných bajtů, který se zapisuje do *TextLengthPtr.

  • SQL_INVALID_HANDLE: Popisovač označený HandleType a Popisovač nebyl platným popisovačem.

  • SQL_ERROR: Došlo k jedné z následujících:

    • RecNumber bylo záporné nebo 0.

    • BufferLength byla menší než nula.

    • Při použití asynchronního oznámení nebyla asynchronní operace popisovače dokončena.

  • SQL_NO_DATA: RecNumber byl větší než počet diagnostických záznamů, které existovaly pro popisovač zadaný v popisovači . Funkce také vrátí SQL_NO_DATA pro všechny kladné RecNumber, pokud neexistují žádné diagnostické záznamy propopisovač .

Comments

Aplikace obvykle volá SQLGetDiagRec , když předchozí volání funkce ODBC vrátilo SQL_ERROR nebo SQL_SUCCESS_WITH_INFO. Nicméně, protože jakákoli funkce ODBC může při každém volání zobrazit nula nebo více diagnostických záznamů, aplikace může po jakémkoli volání funkce ODBC volat SQLGetDiagRec . Aplikace může volat SQLGetDiagRec vícekrát, aby vrátila některé nebo všechny záznamy v diagnostické datové struktuře. ODBC neomezuje počet diagnostických záznamů, které lze uložit najednou.

SQLGetDiagRec nelze použít k vrácení polí z hlavičky diagnostické datové struktury. ( Argument RecNumber musí být větší než 0.) Aplikace by měla pro tento účel volat SQLGetDiagField .

SQLGetDiagRec získává pouze diagnostické informace naposledy spojené s rukojetí specifikovanou v argumentu Handle . Pokud aplikace volá jinou funkci ODBC, kromě SQLGetDiagRec, SQLGetDiagField nebo SQLError, ztratí se jakékoli diagnostické informace z předchozích volání na stejném přečte.

Aplikace může skenovat všechny diagnostické záznamy smyčkováním a zvyšováním RecNumber, pokud SQLGetDiagRec vrací SQL_SUCCESS. Volání SQLGetDiagRec nejsou destruktivní pro hlavičková a záznamová pole. Aplikace může SQLGetDiagRec znovu volat později, aby získala pole ze záznamu, pokud mezitím nebyla vyvolána žádná jiná funkce než SQLGetDiagRec, SQLGetDiagField nebo SQLError. Aplikace také dokáže získat počet dostupných diagnostických záznamů zavoláním SQLGetDiagField pro získání hodnoty SQL_DIAG_NUMBER pole a následným voláním SQLGetDiagRec opakovaně.

Pro popis polí diagnostické datové struktury viz SQLGetDiagField. Další informace naleznete v tématu Použití sqlGetDiagRec a SQLGetDiagField a Implementace sqlGetDiagRec a SQLGetDiagField.

Volání jiného rozhraní API, než které se spouští asynchronně, vygeneruje HY010 "Chyba sekvence funkcí". Záznam chyby však nelze načíst před dokončením asynchronní operace.

Argument typu rukojeti

Každý typ popisovače může mít přidružené diagnostické informace. Argument HandleType označuje typ handle argumentu Handle .

Některá pole hlaviček a záznamů nelze vrátit pro popisovače prostředí, připojení, příkazu a popisovače. Ty rukojeti, pro které pole není použitelné, jsou uvedeny v sekcích "Header Fields" a "Record Fields" v SQLGetDiagField.

Volání SQLGetDiagRec vrátí SQL_INVALID_HANDLE pokud je HandleType SQL_HANDLE_SENV, což označuje sdílený prostředí handle. Pokud je však HandleType SQL_HANDLE_ENV, může být handle buď sdílený, nebo nesdílený prostředí handle.

Informace o Podívejte se
Získání pole diagnostického záznamu nebo pole diagnostického hlavičky SQLGetDiagField Function

Související obsah

  • Last updated on