Funzione SQLGetDiagRec

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

Riepilogo
SQLGetDiagRec restituisce i valori correnti di più campi di un record di diagnostica che contiene informazioni di errore, avviso e stato. A differenza di SQLGetDiagField, che restituisce un campo di diagnostica per chiamata, SQLGetDiagRec restituisce diversi campi di uso comune di un record di diagnostica, tra cui SQLSTATE, il codice di errore nativo e il testo del messaggio di diagnostica.

Sintassi

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

Argomenti

HandleType
[Input] Identificatore del tipo di handle che descrive il tipo di handle per cui è necessaria la diagnostica. I possibili valori sono i 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 altre informazioni sulle SQL_HANDLE_DBC_INFO_TOKEN, vedere Sviluppo di consapevolezza del pool di connessioni in un driver ODBC.

Handle
[Input] Handle per la struttura dei dati di diagnostica, del tipo indicato da HandleType. Se HandleType è SQL_HANDLE_ENV, Handle può essere un handle di ambiente 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 di diagnostica RecNumber. I primi due caratteri indicano la classe ; i tre successivi indicano la sottoclasse. Queste informazioni sono contenute nel campo di diagnostica SQL_DIAG_SQLSTATE. Per altre informazioni, vedere SQLSTATEs.

NativeErrorPtr
[Output] Puntatore a un buffer in cui restituire il codice di errore nativo, specifico per l'origine dati. Queste informazioni sono contenute nel campo di diagnostica SQL_DIAG_NATIVE.

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

Se MessageText è NULL, TextLengthPtr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta MessageText.

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

TextLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escluso il numero di caratteri necessari per il carattere di terminazione Null) disponibile per restituire in *MessageText. Se il numero di caratteri disponibili per la restituzione è maggiore di BufferLength, il testo del messaggio di diagnostica in *MessageText viene troncato in BufferLength meno la lunghezza di un carattere di terminazione Null.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.

Diagnostica

SQLGetDiagRec non registra i record di diagnostica per se stesso. 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 di diagnostica richiesto. Non sono stati generati record di diagnostica. Per determinare che si è verificato un troncamento, l'applicazione deve confrontare BufferLength con il numero effettivo di byte disponibili, scritto in *TextLengthPtr.

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

• SQL_ERROR: si è verificato uno dei seguenti:

  • RecNumber è negativo o 0.

  • BufferLength è minore di 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.

Commenti

Un'applicazione chiama in genere SQLGetDiagRec quando una chiamata precedente a una funzione ODBC ha restituito SQL_ERROR o SQL_SUCCESS_WITH_INFO. Tuttavia, poiché qualsiasi funzione ODBC può registrare zero o più record di diagnostica 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 dei dati di diagnostica. ODBC non impone alcun limite al numero di record di diagnostica che possono essere archiviati in qualsiasi momento.

Non è possibile usare SQLGetDiagRec per restituire campi dall'intestazione della struttura dei dati di diagnostica. (L'oggetto L'argomento RecNumber deve essere maggiore di 0. A questo scopo, l'applicazione deve chiamare SQLGetDiagField .

SQLGetDiagRec recupera solo le informazioni di diagnostica più di recente associate all'handle specificato nell'argomento Handle . Se l'applicazione chiama un'altra funzione ODBC, ad eccezione di SQLGetDiagRec, SQLGetDiagField o SQLError, tutte le informazioni di diagnostica delle chiamate precedenti sullo stesso handle andranno perse.

Un'applicazione può analizzare tutti i record di diagnostica eseguendo cicli, incrementando RecNumber, purché SQLGetDiagRec restituisca SQL_SUCCESS. Le chiamate a SQLGetDiagRec non sono distruttive per i campi intestazione e record. L'applicazione può chiamare di nuovo SQLGetDiagRec in un secondo momento per recuperare un campo da un record, purché nessun'altra funzione, ad eccezione di SQLGetDiagRec, SQLGetDiagField o SQLError, sia stata chiamata nel frattempo. L'applicazione può anche recuperare un conteggio del numero totale di record di diagnostica disponibili chiamando SQLGetDiagField per recuperare il valore del campo SQL_DIAG_NUMBER e quindi chiamando SQLGetDiagRec più volte.

Per una descrizione dei campi della struttura dei dati di diagnostica, vedere SQLGetDiagField. Per altre informazioni, vedere Uso di SQLGetDiagRec e SQLGetDiagField e Implementazione di SQLGetDiagRec e 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. Gli handle per i quali un campo non è applicabile sono indicati nelle sezioni "Campi intestazione" e "Campi record" in SQLGetDiagField.

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

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Programma di esempio ODBC