Funzione SQLGetDiagRec

Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92

Sommario
SQLGetDiagRec restituisce i valori attuali di più campi di un record diagnostico che contiene informazioni su errore, avviso e stato. A differenza di SQLGetDiagField, che restituisce un campo diagnostico per chiamata, SQLGetDiagRec restituisce diversi campi comunemente usati di un record diagnostico, inclusi SQLSTATE, il codice di errore nativo e il testo del messaggio diagnostico.

Sintassi

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

Arguments

HandleType
[Input] Identificatore del tipo di handle che descrive il tipo di handle per cui è necessaria la diagnostica. Deve essere uno dei seguenti:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle viene usato solo da Gestione driver e driver. Le applicazioni non devono usare questo tipo di handle. Per maggiori informazioni su SQL_HANDLE_DBC_INFO_TOKEN, vedi Sviluppare la consapevolezza Connection-Pool in un driver ODBC.

Maneggiare
[Input] Handle per la struttura dei dati di diagnostica, del tipo indicato da HandleType. Se handleType è SQL_HANDLE_ENV, handle può essere un handle condiviso o non condiviso.

RecNumber
[Input] Indica il record di stato da cui l'applicazione cerca informazioni. I record di stato sono numerati da 1.

SQLState
[Output] Puntatore a un buffer in cui restituire un codice SQLSTATE di cinque caratteri (e terminazione NULL) per il record diagnostico RecNumber. I primi due caratteri indicano la classe; i tre successivi indicano la sottoclasse. Queste informazioni sono contenute nel campo diagnostico SQL_DIAG_SQLSTATE. Per altre informazioni, vedere SQLSTATEs.

NativeErrorPtr
[Output] Puntatore a un buffer in cui restituire il codice di errore nativo, specifico per la sorgente dati. Queste informazioni sono contenuti nel campo diagnostico SQL_DIAG_NATIVE.

MessageText
[Output] Puntatore a un buffer in cui restituire la stringa di testo del messaggio diagnostico. Queste informazioni sono contenute nel campo diagnostico SQL_DIAG_MESSAGE_TEXT. Per il formato della stringa, vedi Messaggi diagnostici.

Se MessageText è NULL, TextLengthPtr restituirà comunque il numero totale di caratteri (escluso il carattere di null-termination per i dati caratteri) disponibili da restituire nel buffer indicato da MessageText.

BufferLength
[Input] Lunghezza del buffer *MessageText in caratteri. Non esiste una lunghezza massima del testo del messaggio diagnostico.

TextLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escludendo il numero di caratteri richiesti per il carattere di null-termination) disponibili da restituire in *MessageText. Se il numero di caratteri disponibili da restituire è superiore a BufferLength, il testo del messaggio diagnostico in *MessageText viene troncato a BufferLength meno la lunghezza di un carattere di null-termination.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.

Diagnostica

SQLGetDiagRec non pubblica i record diagnostici per conto proprio. Usa i valori restituiti seguenti per segnalare il risultato della propria esecuzione:

  • SQL_SUCCESS: la funzione ha restituito correttamente informazioni di diagnostica.

  • SQL_SUCCESS_WITH_INFO: Il buffer *MessageText era troppo piccolo per contenere il messaggio diagnostico richiesto. Non sono stati generati dati diagnostici. Per determinare che si è verificata una troncatura, l'applicazione deve confrontare BufferLength con il numero effettivo di byte disponibili, che viene scritto su *TextLengthPtr.

  • SQL_INVALID_HANDLE: l'handle indicato da HandleType e Handle non è un handle valido.

  • SQL_ERROR: si è verificato uno dei seguenti:

    • Il numero di raccomandazione era negativo o 0.

    • BufferLength era inferiore a zero.

    • Quando si usa la notifica asincrona, l'operazione asincrona sull'handle non è stata completata.

  • SQL_NO_DATA: RecNumber è maggiore del numero di record di diagnostica esistenti per l'handle specificato in handle . La funzione restituisce anche SQL_NO_DATA per qualsiasi RecNumber positivo se non sono presenti record di diagnostica per Handle.

Comments

Un'applicazione chiama tipicamente SQLGetDiagRec quando una precedente chiamata a una funzione ODBC ha restituito SQL_ERROR o SQL_SUCCESS_WITH_INFO. Tuttavia, poiché qualsiasi funzione ODBC può pubblicare zero o più record diagnostici ogni volta che viene chiamata, un'applicazione può chiamare SQLGetDiagRec dopo qualsiasi chiamata di funzione ODBC. Un'applicazione può chiamare SQLGetDiagRec più volte per restituire alcuni o tutti i record nella struttura dati diagnostica. ODBC non impone limiti al numero di record diagnostici che possono essere memorizzati contemporaneamente.

SQLGetDiagRec non può essere utilizzato per restituire campi dall'intestazione della struttura dati diagnostica. (L'argomento RecNumber deve essere maggiore di 0.) L'applicazione dovrebbe chiamare SQLGetDiagField per questo scopo.

SQLGetDiagRec recupera solo le informazioni diagnostiche più recentemente associate al handle specificato nell'argomento Handle . Se l'applicazione chiama un'altra funzione ODBC, eccetto SQLGetDiagRec, SQLGetDiagField o SQLError, qualsiasi informazione diagnostica delle chiamate precedenti sullo stesso handle viene persa.

Un'applicazione può scansionare tutti i record diagnostici tramite looping, incrementando RecNumber, purché SQLGetDiagRec restituisca SQL_SUCCESS. Le chiamate a SQLGetDiagRec non sono distruttive per i campi di intestazione e record. L'applicazione può richiamare SQLGetDiagRec in un momento successivo per recuperare un campo da un record, purché nessun'altra funzione, tranne SQLGetDiagRec, SQLGetDiagField o SQLError, sia stata chiamata nel frattempo. L'applicazione può anche recuperare il conteggio del numero totale di record diagnostici disponibili chiamando SQLGetDiagField per recuperare il valore del campo SQL_DIAG_NUMBER, e poi chiamando SQLGetDiagRec tante volte.

Per una descrizione dei campi della struttura dati diagnostica, vedi SQLGetDiagField. Per altre informazioni, vedere Using SQLGetDiagRec and SQLGetDiagField and Implementing SQLGetDiagRec and SQLGetDiagField.

La chiamata di un'API diversa da quella eseguita in modo asincrono genererà "Errore di sequenza di funzioni". Tuttavia, non è possibile recuperare il record di errore prima del completamento dell'operazione asincrona.

Argomento HandleType

A ogni tipo di handle possono essere associate informazioni di diagnostica. L'argomento HandleType indica il tipo di handle dell'argomento Handle .

Alcuni campi di intestazione e record non possono essere restituiti per handle di ambiente, connessione, istruzione e descrittore. Quei handle per i quali un campo non è applicabile sono indicati nelle sezioni "Header Fields" e "Record Fields" in SQLGetDiagField.

Una chiamata a SQLGetDiagRec restituirà SQL_INVALID_HANDLE se HandleType è SQL_HANDLE_SENV, il che indica un handle di ambiente condiviso. Tuttavia, se HandleType è SQL_HANDLE_ENV, Handle può essere un handle di ambiente condiviso o non condiviso.

Per informazioni su Vedi
Ottenere un campo di una cartella diagnostica o un campo dell'intestazione diagnostica Funzione SQLGetDiagField

Contenuti correlati

  • Last updated on