Funzione SQLGetDescField

  • Articolo

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

Riepilogo
SQLGetDescField restituisce l'impostazione o il valore corrente di un singolo campo di un record descrittore.

Sintassi

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Argomenti

DescriptorHandle
[Input] Handle del descrittore.

RecNumber
[Input] Indica il record descrittore da cui l'applicazione cerca informazioni. I record del descrittore sono numerati da 0, con il numero di record 0 come record del segnalibro. Se l'argomento FieldIdentifier indica un campo di intestazione, RecNumber viene ignorato. Se RecNumber è minore o uguale a SQL_DESC_COUNT ma la riga non contiene dati per una colonna o un parametro, una chiamata a SQLGetDescField restituirà i valori predefiniti dei campi. Per altre informazioni, vedere "Inizializzazione dei campi descrittore" in SQLSetDescField.

FieldIdentifier
[Input] Indica il campo del descrittore il cui valore deve essere restituito. Per altre informazioni, vedere la sezione "Argomento FieldIdentifier " in SQLSetDescField.

ValuePtr
[Output] Puntatore a un buffer in cui restituire le informazioni del descrittore. Il tipo di dati dipende dal valore di FieldIdentifier.

Se ValuePtr è di tipo integer, le applicazioni devono usare un buffer di SQLULEN e inizializzare il valore su 0 prima di chiamare questa funzione perché 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 ValuePtr è 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 ValuePtr.

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

Se FieldIdentifier è 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 *ValuePtr è un puntatore a una stringa di caratteri, BufferLength è la lunghezza della stringa o SQL_NTS.

  • Se *ValuePtr è 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 *ValuePtr è un puntatore a un valore diverso da una stringa di caratteri o una stringa binaria, BufferLength deve avere il valore SQL_IS_POINTER.

  • Se *ValuePtr contiene un tipo di dati a lunghezza fissa, BufferLength è SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, se necessario.

StringLengthPtr
[Output] Puntatore al buffer in cui restituire il numero totale di byte (escluso il numero di byte necessari per il carattere di terminazione Null) da restituire in *ValuePtr.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.

SQL_NO_DATA viene restituito se RecNumber è maggiore del numero corrente di record del descrittore.

SQL_NO_DATA viene restituito se DescriptorHandle è un handle IRD e l'istruzione si trova nello stato preparato o eseguito, ma non è stato associato alcun cursore aperto.

Diagnostica

Quando SQLGetDescField restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLGetDescField e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01004 Dati stringa, troncati a destra Il buffer *ValuePtr non era sufficientemente grande da restituire l'intero campo descrittore, quindi il campo è stato troncato. La lunghezza del campo descrittore non modificato viene restituita in *StringLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
07009 Indice descrittore non valido (DM) L'argomento RecNumber era uguale a 0, l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARK era SQL_UB_OFF e l'argomento DescriptorHandle era un handle IRD. Questo errore può essere restituito per un descrittore allocato in modo esplicito solo se il descrittore è associato a un handle di istruzione.

L'argomento FieldIdentifier era un campo record, l'argomento RecNumber era 0 e l'argomento DescriptorHandle era un handle IPD.

L'argomento RecNumber è minore di 0.
08S01 Errore del collegamento di comunicazione Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
HY000 Errore generale: Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria Il driver non è riuscito ad allocare la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY007 Istruzione associata non preparata DescriptorHandle è stato associato a statementHandle come IRD e l'handle di istruzione associato non è stato preparato o eseguito.
HY010 Errore della sequenza di funzioni (DM) DescriptorHandle è stato associato a un StatementHandle per il quale è stata chiamata una funzione in esecuzione asincrona (non questa) ed era ancora in esecuzione quando questa funzione è stata chiamata.

(DM) DescriptorHandle è stato associato a un statementHandle per cui è stato SQL_NEED_DATA chiamato SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos . Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.

(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a DescriptorHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLGetDescField .
HY013 Errore di gestione della memoria Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY021 Informazioni sul descrittore incoerente I campi SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE non formano un tipo SQL ODBC valido, un tipo SQL specifico del driver valido (per IPD) o un tipo ODBC C valido (per API o ARD).
HY090 Lunghezza della stringa o del buffer non valida (DM) *ValuePtr era una stringa di caratteri e BufferLength era minore di zero.
HY091 Identificatore di campo del descrittore non valido FieldIdentifier non era un campo definito da ODBC e non era un valore definito dall'implementazione.

FieldIdentifier non è stato definito per DescriptorHandle.
HY117 La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Il driver non supporta questa funzione (DM) Il driver associato a DescriptorHandle non supporta la funzione.

Commenti

Un'applicazione può chiamare SQLGetDescField per restituire il valore di un singolo campo di un record descrittore. Una chiamata a SQLGetDescField può restituire l'impostazione di qualsiasi campo in qualsiasi tipo di descrittore, inclusi campi di intestazione, campi di record e campi segnalibro. Un'applicazione può ottenere le impostazioni di più campi negli stessi descrittori o diversi, in ordine arbitrario, effettuando chiamate ripetute a SQLGetDescField. È anche possibile chiamare SQLGetDescField per restituire campi descrittori definiti dal driver.

Per motivi di prestazioni, un'applicazione non deve chiamare SQLGetDescField per un IRD prima di eseguire un'istruzione .

Le impostazioni di più campi che descrivono il nome, il tipo di dati e l'archiviazione dei dati delle colonne o dei parametri possono essere recuperate anche in una singola chiamata a SQLGetDescRec. È possibile chiamare SQLGetStmtAttr per restituire l'impostazione di un singolo campo nell'intestazione del descrittore che è anche un attributo di istruzione. Campi record restituiti o segnalibri sqlColAttribute, SQLDescribeCol e SQLDescribeParam .

Quando un'applicazione chiama SQLGetDescField per recuperare il valore di un campo non definito per un particolare tipo di descrittore, la funzione restituisce SQL_SUCCESS ma il valore restituito per il campo non è definito. Ad esempio, la chiamata a SQLGetDescField per il campo SQL_DESC_NAME o SQL_DESC_NULLABLE di un APD o ARD restituirà SQL_SUCCESS ma un valore non definito per il campo.

Quando un'applicazione chiama SQLGetDescField per recuperare il valore di un campo definito per un particolare tipo di descrittore, ma che non ha ancora un valore predefinito e non è ancora stato impostato, la funzione restituisce SQL_SUCCESS ma il valore restituito per il campo non è definito. Per altre informazioni sull'inizializzazione di campi descrittori e descrizioni dei campi, vedere "Inizializzazione dei campi descrittore" in SQLSetDescField. Per altre informazioni sui descrittori, vedere Descrittori.

Per informazioni su Vedere
Recupero di più campi descrittore Funzione SQLGetDescRec
Impostazione di un singolo campo descrittore Funzione SQLSetDescField
Impostazione di più campi descrittori Funzione SQLSetDescRec

Vedi anche

Riferimento API ODBC
File di intestazione ODBC