Funzione SQLGetDiagField

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

Riepilogo
SQLGetDiagField restituisce il valore corrente di un campo di un record della struttura dei dati di diagnostica (associata a un handle specificato) che contiene informazioni su errore, avviso e stato.

Sintassi

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

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. Se l'argomento DiagIdentifier indica un campo dell'intestazione di diagnostica, RecNumber viene ignorato. In caso contrario, deve essere maggiore di 0.

DiagIdentifier
[Input] Indica il campo della diagnostica il cui valore deve essere restituito. Per altre informazioni, vedere la sezione "Argomento DiagIdentifier " in "Comments".

DiagInfoPtr
[Output] Puntatore a un buffer in cui restituire le informazioni di diagnostica. Il tipo di dati dipende dal valore di DiagIdentifier. Se DiagInfoPtr è un tipo integer, le applicazioni devono usare un buffer di SQLULEN e inizializzare il valore su 0 prima di chiamare questa funzione, poiché alcuni driver possono scrivere solo il bit inferiore a 32 bit o 16 bit di un buffer e lasciare invariato il bit di ordine superiore.

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

BufferLength
[Input] Se DiagIdentifier è una diagnostica definita da ODBC e DiagInfoPtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *DiagInfoPtr. Se DiagIdentifier è un campo definito da ODBC e *DiagInfoPtr è un numero intero, BufferLength viene ignorato. Se il valore in *DiagInfoPtr è una stringa Unicode (quando si chiama SQLGetDiagFieldW), l'argomento BufferLength deve essere un numero pari.

Se DiagIdentifier è un campo definito dal driver, l'applicazione indica la natura del campo in Gestione driver impostando l'argomento BufferLength . BufferLength può avere i valori seguenti:

• Se DiagInfoPtr è un puntatore a una stringa di caratteri, BufferLength è la lunghezza della stringa o SQL_NTS.

• Se DiagInfoPtr è un puntatore a un buffer binario, l'applicazione inserisce il risultato della macro SQL_LEN_BINARY_ATTR(length) in BufferLength. In questo modo viene impostato un valore negativo in BufferLength.

• Se DiagInfoPtr è un puntatore a un valore diverso da una stringa di caratteri o una stringa binaria, BufferLength deve avere il valore SQL_IS_POINTER.

• Se *DiagInfoPtr contiene un tipo di dati a lunghezza fissa, BufferLength è SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, in base alle esigenze.

StringLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di byte (escluso il numero di byte necessari per il carattere di terminazione Null) disponibile per restituire in *DiagInfoPtr, per i dati di tipo carattere. Se il numero di byte disponibili per la restituzione è maggiore o uguale a BufferLength, il testo in *DiagInfoPtr viene troncato a BufferLength meno la lunghezza di un carattere di terminazione Null.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_NO_DATA.

Diagnostica

SQLGetDiagField 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: *DiagInfoPtr era troppo piccolo per contenere il campo di diagnostica richiesto. Di conseguenza, i dati nel campo di diagnostica sono stati troncati. Per determinare che si è verificato un troncamento, l'applicazione deve confrontare BufferLength con il numero effettivo di byte disponibili, scritto in *StringLengthPtr.

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

• SQL_ERROR: si è verificato uno dei seguenti:

  • L'argomento DiagIdentifier non è uno dei valori validi.

  • L'argomento DiagIdentifier è stato SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE o SQL_DIAG_ROW_COUNT, ma Handle non era un handle di istruzione. Gestione driver restituisce questa diagnostica.

  • L'argomento RecNumber è negativo o 0 quando DiagIdentifier indica un campo da un record di diagnostica. RecNumber viene ignorato per i campi di intestazione.

  • Il valore richiesto era una stringa di caratteri e BufferLength era 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 SQLGetDiagField per raggiungere uno dei tre obiettivi seguenti:

1. Per ottenere informazioni di errore o avviso specifiche quando una chiamata di funzione ha restituito SQL_ERROR o SQL_SUCCESS_WITH_INFO (o SQL_NEED_DATA per la funzione SQLBrowseConnect ).

2. Per determinare il numero di righe nell'origine dati interessate durante l'esecuzione di operazioni di inserimento, eliminazione o aggiornamento con una chiamata a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos (dal campo di intestazione SQL_DIAG_ROW_COUNT) o per determinare il numero di righe presenti nel cursore aperto corrente, se il driver può fornire queste informazioni (dal campo di intestazione SQL_DIAG_CURSOR_ROW_COUNT).

3. Per determinare quale funzione è stata eseguita da una chiamata a SQLExecDirect o SQLExecute (dai campi di intestazione SQL_DIAG_DYNAMIC_FUNCTION e SQL_DIAG_DYNAMIC_FUNCTION_CODE).

Qualsiasi funzione ODBC può registrare zero o più record di diagnostica ogni volta che viene chiamata, in modo che un'applicazione possa chiamare SQLGetDiagField dopo qualsiasi chiamata di funzione ODBC. Non esiste alcun limite al numero di record di diagnostica che possono essere archiviati in qualsiasi momento. SQLGetDiagField recupera solo le informazioni di diagnostica più di recente associate alla struttura dei dati di diagnostica specificata nell'argomento Handle . Se l'applicazione chiama una funzione ODBC diversa da SQLGetDiagField o SQLGetDiagRec, tutte le informazioni di diagnostica di una chiamata precedente con lo stesso handle andranno perse.

Un'applicazione può analizzare tutti i record di diagnostica incrementando RecNumber, purché SQLGetDiagField restituisca SQL_SUCCESS. Il numero di record di stato è indicato nel campo dell'intestazione SQL_DIAG_NUMBER. Le chiamate a SQLGetDiagField non sono distruttive per i campi di intestazione e record. L'applicazione può chiamare di nuovo SQLGetDiagField in un secondo momento per recuperare un campo da un record, purché una funzione diversa dalle funzioni di diagnostica non sia stata chiamata nel frattempo, che inserirebbe i record sullo stesso handle.

Un'applicazione può chiamare SQLGetDiagField per restituire qualsiasi campo di diagnostica in qualsiasi momento, ad eccezione di SQL_DIAG_CURSOR_ROW_COUNT o SQL_DIAG_ROW_COUNT, che restituirà SQL_ERROR se Handle non è un handle di istruzione. Se un altro campo di diagnostica non è definito, la chiamata a SQLGetDiagField restituirà SQL_SUCCESS (purché non venga rilevata alcuna altra diagnostica) e viene restituito un valore non definito per il campo.

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.

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" seguenti.

Se HandleType è SQL_HANDLE_ENV, Handle può essere un handle di ambiente condiviso o non condiviso.

Nessun campo di diagnostica dell'intestazione specifico del driver deve essere associato a un handle di ambiente.

Gli unici campi di intestazione di diagnostica definiti per un handle descrittore sono SQL_DIAG_NUMBER e SQL_DIAG_RETURNCODE.

Argomento DiagIdentifier

Questo argomento indica l'identificatore del campo richiesto dalla struttura dei dati di diagnostica. Se RecNumber è maggiore o uguale a 1, i dati nel campo descrivono le informazioni di diagnostica restituite da una funzione. Se RecNumber è 0, il campo si trova nell'intestazione della struttura dei dati di diagnostica e pertanto contiene i dati relativi alla chiamata di funzione che ha restituito le informazioni di diagnostica, non alle informazioni specifiche.

I driver possono definire campi di intestazione e record specifici del driver nella struttura dei dati di diagnostica.

Un'applicazione ODBC 3*.x* che utilizza un driver ODBC 2*.x* potrà chiamare SQLGetDiagField solo con un argomento DiagIdentifier di SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME o SQL_DIAG_SQLSTATE. Tutti gli altri campi di diagnostica restituiranno SQL_ERROR.

Campi intestazione

I campi di intestazione elencati nella tabella seguente possono essere inclusi nell'argomento DiagIdentifier .

Campi record

I campi di record elencati nella tabella seguente possono essere inclusi nell'argomento DiagIdentifier .

Valori dei campi della funzione dinamica

Nella tabella seguente vengono descritti i valori di SQL_DIAG_DYNAMIC_FUNCTION e SQL_DIAG_DYNAMIC_FUNCTION_CODE che si applicano a ogni tipo di istruzione SQL eseguita da una chiamata a SQLExecute o SQLExecDirect. Il driver può aggiungere valori definiti dal driver a quelli elencati.

Sequenza di record di stato

I record di stato vengono posizionati in una sequenza in base al numero di riga e al tipo della diagnostica. Gestione driver determina l'ordine finale in cui restituire i record di stato generati. Il driver determina l'ordine finale in cui restituire i record di stato generati.

Se i record di diagnostica vengono registrati sia da Gestione driver che dal driver, Gestione driver è responsabile dell'ordinamento.

Se sono presenti due o più record di stato, la sequenza dei record viene determinata per prima in base al numero di riga. Le regole seguenti si applicano alla determinazione della sequenza di record di diagnostica per riga:

• I record che non corrispondono ad alcuna riga vengono visualizzati davanti ai record che corrispondono a una determinata riga, perché SQL_NO_ROW_NUMBER è definito come -1.

• I record per i quali il numero di riga è sconosciuto vengono visualizzati davanti a tutti gli altri record, perché SQL_ROW_NUMBER_UNKNOWN è definito come -2.

• Per tutti i record relativi a righe specifiche, i record vengono ordinati in base al valore nel campo SQL_DIAG_ROW_NUMBER. Vengono elencati tutti gli errori e gli avvisi della prima riga interessata, quindi tutti gli errori e gli avvisi della riga successiva interessati e così via.

All'interno di ogni riga o per tutti i record che non corrispondono a una riga o per cui il numero di riga è sconosciuto oppure per tutti i record con un numero di riga uguale a SQL_NO_ROW_NUMBER, il primo record elencato viene determinato utilizzando un set di regole di ordinamento. Dopo il primo record, l'ordine degli altri record che interessano una riga non è definito. Un'applicazione non può presupporre che gli errori precedono gli avvisi dopo il primo record. Le applicazioni devono analizzare la struttura completa dei dati di diagnostica per ottenere informazioni complete su una chiamata non riuscita a una funzione.

Le regole seguenti vengono utilizzate per determinare il primo record all'interno di una riga. Il record con il rango più alto è il primo record. L'origine di un record (Gestione driver, driver, gateway e così via) non viene considerata quando si classificano i record.

• I record di stato degli errori che descrivono gli errori hanno il rango più alto. Le regole seguenti vengono applicate agli errori di ordinamento:

  • Record che indicano un errore di transazione o un possibile errore di transazione hanno bevuto tutti gli altri record.

  • Se due o più record descrivono la stessa condizione di errore, SQLSTATEs definiti dalla specifica dell'interfaccia della riga di comando del gruppo open (classi da 03 a HZ) hanno superato ODBC e SQLSTATEs definiti dal driver.

• I record di stato No Data Values definiti dall'implementazione che descrivono i valori No Data definiti dal driver (classe 02) hanno il secondo rango più alto.

• I record di stato degli avvisi che descrivono gli avvisi (classe 01) hanno il rango più basso. Se due o più record descrivono la stessa condizione di avviso, gli avvisi SQLSTATEs definiti dalla specifica dell'interfaccia della riga di comando open group hanno outrank ODBC-defined e SQLSTATEs definiti dal driver.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC