SQLGetDiagRec-funktion

Överensstämmelse
Version introducerad: ODBC 3.0 Standardsefterlevnad: ISO 92

Summary
SQLGetDiagRec returnerar aktuella värden för flera fält i en diagnostisk post som innehåller fel-, varnings- och statusinformation. Till skillnad från SQLGetDiagField, som returnerar ett diagnostiskt fält per anrop, returnerar SQLGetDiagRec flera vanligt använda fält i en diagnostisk post, inklusive SQLSTATE, den inbyggda felkoden och diagnostiska meddelandetexten.

Syntax

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

Arguments

HandleType
[Indata] En identifierare för referenstyp som beskriver vilken typ av handtag som diagnostik krävs för. Måste vara något av följande:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handtag används endast av Drivrutinshanteraren och drivrutinen. Program bör inte använda den här referenstypen. För mer information om SQL_HANDLE_DBC_INFO_TOKEN, se Utveckling av Connection-Pool medvetenhet i en ODBC-drivrutin.

Hanterare
[Indata] Ett handtag för diagnostikdatastrukturen, av den typ som anges av HandleType. Om HandleType- är SQL_HANDLE_ENV kan Hantera antingen vara en delad eller en odelad miljöreferens.

RecNumber
[Indata] Anger den statuspost som programmet söker information från. Statusposter numreras från 1.

SQLState
[Utdata] Pekare till en buffert där en femteckens SQLSTATE-kod (och avslutande NULL) returneras för diagnostikposten RecNumber. De två första tecknen anger klassen; de tre följande indikerar underklassen. Denna information finns i det SQL_DIAG_SQLSTATE diagnostiska fältet. Mer information finns i SQLSTATEs.

NativeErrorPtr
[Utdata] Pekar på en buffert där den inbyggda felkoden kan returneras, specifik för datakällan. Denna information finns i det SQL_DIAG_NATIVE diagnostiska fältet.

MessageText
[Utdata] Pekare till en buffert där man returnerar den diagnostiska meddelandetextsträngen. Denna information finns i det SQL_DIAG_MESSAGE_TEXT diagnostiska fältet. För strängens format, se Diagnostiska meddelanden.

Om MessageText är NULL kommer TextLengthPtr ändå att returnera det totala antalet tecken (exklusive null-termineringstecknet för teckendata) som finns tillgängliga att returnera i bufferten som MessageText pekar på.

BufferLength
[Input] Längden på *MessageText-bufferten i tecken. Det finns ingen maximal längd på diagnosmeddelandetexten.

TextLengthPtr
[Utdata] Pekare till en buffert där det totala antalet tecken (exklusive antalet tecken som krävs för null-termineringstecknet) kan returneras i *MessageText. Om antalet tecken som kan returneras är större än BufferLength, förkortas den diagnostiska meddelandetexten i *MessageText till BufferLength minus längden på ett null-termineringstecken.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA eller SQL_INVALID_HANDLE.

Diagnostics

SQLGetDiagRec publicerar inte diagnostiska poster för sig själv. Den använder följande returvärden för att rapportera resultatet av sin egen körning:

  • SQL_SUCCESS: Funktionen returnerade diagnostikinformation.

  • SQL_SUCCESS_WITH_INFO: *MessageText-bufferten var för liten för att hålla det begärda diagnosmeddelandet. Inga diagnostiska journaler genererades. För att fastställa att en trunkering har skett måste applikationen jämföra BufferLength med det faktiska antalet tillgängliga bytes, vilket skrivs till *TextLengthPtr.

  • SQL_INVALID_HANDLE: Handtaget som anges av HandleType och Handle var inte ett giltigt handtag.

  • SQL_ERROR: Något av följande inträffade:

    • RecNumber var negativ eller 0.

    • BufferLength var mindre än noll.

    • När du använde asynkrona meddelanden slutfördes inte den asynkrona åtgärden på handtaget.

  • SQL_NO_DATA: RecNumber var större än antalet diagnostikposter som fanns för referensen som anges i Handle. Funktionen returnerar också SQL_NO_DATA för positiva RecNumber- om det inte finns några diagnostikposter för Handle.

Comments

En applikation anropar vanligtvis SQLGetDiagRec när ett tidigare anrop till en ODBC-funktion har returnerat SQL_ERROR eller SQL_SUCCESS_WITH_INFO. Eftersom vilken ODBC-funktion som helst kan posta noll eller fler diagnostiska poster varje gång den anropas, kan en applikation anropa SQLGetDiagRec efter varje ODBC-funktionsanrop. En applikation kan anropa SQLGetDiagRec flera gånger för att returnera några eller alla poster i diagnostikdatastrukturen. ODBC sätter ingen gräns för antalet diagnostiska poster som kan lagras samtidigt.

SQLGetDiagRec kan inte användas för att returnera fält från headern i den diagnostiska datastrukturen. ( RecNumber-argumentet måste vara större än 0.) Applikationen bör anropa SQLGetDiagField för detta ändamål.

SQLGetDiagRec hämtar endast den diagnostiska information som senast var kopplad till handtaget som specificerats i Handle-argumentet . Om applikationen anropar en annan ODBC-funktion, förutom SQLGetDiagRec, SQLGetDiagField eller SQLError, förloras all diagnostisk information från tidigare anrop på samma handtag.

En applikation kan skanna alla diagnostiska poster genom att loopa, öka RecNumber, så länge SQLGetDiagRec returnerar SQL_SUCCESS. Anrop till SQLGetDiagRec är icke-destruktiva för header- och postfälten. Applikationen kan anropa SQLGetDiagRec igen vid ett senare tillfälle för att hämta ett fält från en post så länge ingen annan funktion än SQLGetDiagRec, SQLGetDiagField eller SQLError har anropats under tiden. Applikationen kan också hämta en räkning av det totala antalet diagnostiska poster genom att anropa SQLGetDiagField för att hämta värdet av det SQL_DIAG_NUMBER fältet, och sedan anropa SQLGetDiagRec så många gånger.

För en beskrivning av fälten i den diagnostiska datastrukturen, se SQLGetDiagField. Mer information finns i Using SQLGetDiagRec and SQLGetDiagField and Implementing SQLGetDiagRec and SQLGetDiagField.

Om du anropar ett annat API än det som körs asynkront genereras HY010 "Funktionssekvensfel". Det går dock inte att hämta felposten innan den asynkrona åtgärden har slutförts.

HandleType-argument

Varje referenstyp kan ha diagnostikinformation associerad med den. HandleType-argumentet betecknar handtagstypen för Handle-argumentet.

Vissa rubrik- och postfält kan inte returneras för miljö-, anslutnings-, instruktions- och deskriptorreferenser. De handtag där ett fält inte är tillämpligt anges i avsnitten "Header Fields" och "Record Fields" i SQLGetDiagField.

Ett anrop till SQLGetDiagRec returnerar SQL_INVALID_HANDLE om HandleType är SQL_HANDLE_SENV, vilket betecknar ett delat miljöhandtag. Men om HandleType är SQL_HANDLE_ENV kan Handle vara antingen ett delat eller ett icke-delat miljöhandtag.

Mer information om Se
Att hämta ett fält i en diagnostisk post eller ett fält i diagnoshuvudet SQLGetDiagField-funktionen

Relaterat innehåll

  • Last updated on