Funzione SQLDescribeCol
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLDescribeCol restituisce il descrittore dei risultati, ovvero il nome della colonna, il tipo, le dimensioni della colonna, le cifre decimali e il supporto dei valori Null, per una colonna nel set di risultati. Queste informazioni sono disponibili anche nei campi dell'IRD.
Sintassi
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argomenti
StatementHandle
[Input] Handle di istruzione.
ColumnNumber
[Input] Numero di colonne di dati dei risultati, ordinato in sequenza in ordine crescente di colonna, a partire da 1. L'argomento ColumnNumber può anche essere impostato su 0 per descrivere la colonna del segnalibro.
ColumnName
[Output] Puntatore a un buffer con terminazione Null in cui restituire il nome della colonna. Questo valore viene letto dal campo SQL_DESC_NAME di IRD. Se la colonna non è denominata o non è possibile determinare il nome della colonna, il driver restituisce una stringa vuota.
Se ColumnName è NULL, NameLengthPtr 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 ColumnName.
BufferLength
[Input] Lunghezza del buffer *ColumnName , in caratteri.
NameLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (esclusa la terminazione Null) disponibile per la restituzione in *ColumnName. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength, il nome della colonna in *ColumnName viene troncato in BufferLength meno la lunghezza di un carattere di terminazione Null.
DataTypePtr
[Output] Puntatore a un buffer in cui restituire il tipo di dati SQL della colonna. Questo valore viene letto dal campo SQL_DESC_CONCISE_TYPE di IRD. Si tratta di uno dei valori in Tipi di dati SQL o di un tipo di dati SQL specifico del driver. Se non è possibile determinare il tipo di dati, il driver restituisce SQL_UNKNOWN_TYPE.
In ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME o SQL_TYPE_TIMESTAMP vengono restituiti rispettivamente in *DataTypePtr per i dati di data, ora o timestamp; in ODBC 2.viene restituito x, SQL_DATE, SQL_TIME o SQL_TIMESTAMP. Gestione driver esegue i mapping necessari quando un odbc 2.L'applicazione x funziona con odbc 3.x driver o quando un ODBC 3.L'applicazione x funziona con odbc 2.x driver.
Quando ColumnNumber è uguale a 0 (per una colonna di segnalibro), SQL_BINARY viene restituito in *DataTypePtr per i segnalibri a lunghezza variabile. (SQL_INTEGER viene restituito se i segnalibri vengono utilizzati da un ODBC 3.Applicazione x che utilizza un'applicazione ODBC 2.driver x o da odbc 2.Applicazione x che funziona con ODBC 3.x driver.)
Per altre informazioni su questi tipi di dati, vedere Tipi di dati SQL nell'Appendice D: Tipi di dati. Per informazioni sui tipi di dati SQL specifici del driver, vedere la documentazione del driver.
ColumnSizePtr
[Output] Puntatore a un buffer in cui restituire le dimensioni (in caratteri) della colonna nell'origine dati. Se non è possibile determinare le dimensioni della colonna, il driver restituisce 0. Per altre informazioni sulle dimensioni delle colonne, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione nell'Appendice D: Tipi di dati.
DecimalDigitsPtr
[Output] Puntatore a un buffer in cui restituire il numero di cifre decimali della colonna nell'origine dati. Se il numero di cifre decimali non può essere determinato o non è applicabile, il driver restituisce 0. Per altre informazioni sulle cifre decimali, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione nell'Appendice D: Tipi di dati.
NullablePtr
[Output] Puntatore a un buffer in cui restituire un valore che indica se la colonna consente valori NULL. Questo valore viene letto dal campo SQL_DESC_NULLABLE di IRD. I possibili valori sono i seguenti:
SQL_NO_NULLS: la colonna non consente valori NULL.
SQL_NULLABLE: la colonna consente valori NULL.
SQL_NULLABLE_UNKNOWN: il driver non è in grado di determinare se la colonna consente valori NULL.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLDescribeCol 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 SQLDescribeCol 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 *ColumnName non è abbastanza grande da restituire l'intero nome della colonna, quindi il nome della colonna è stato troncato. La lunghezza del nome della colonna non troncata viene restituita in *NameLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 07005 | Istruzione preparata non specifica cursore | L'istruzione associata a StatementHandle non ha restituito un set di risultati. Nessuna colonna da descrivere. |
| 07009 | Indice descrittore non valido | (DM) Il valore specificato per l'argomento ColumnNumber è uguale a 0 e l'opzione di istruzione SQL_ATTR_USE_BOOKMARKS è stata SQL_UB_OFF. Il valore specificato per l'argomento ColumnNumber è maggiore del numero di colonne nel set di risultati. |
| 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 memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY008 | Operazione annullata | L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stato chiamato SQLDescribeCol . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) La funzione è stata chiamata prima di chiamare SQLPrepare, SQLExecute o una funzione di catalogo nell'handle di istruzione. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. |
| 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. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) Il valore specificato per l'argomento BufferLength è minore di 0. |
| 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 StatementHandle non supporta la funzione. |
| IM017 | Il polling è disabilitato in modalità di notifica asincrona | Ogni volta che viene usato il modello di notifica, il polling è disabilitato. |
| IM018 | SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. | Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione. |
SQLDescribeCol può restituire qualsiasi SQLSTATE che può essere restituito da SQLPrepare o SQLExecute quando viene chiamato dopo SQLPrepare e prima di SQLExecute, a seconda di quando l'origine dati valuta l'istruzione SQL associata all'handle di istruzione.
Per motivi di prestazioni, un'applicazione non deve chiamare SQLDescribeCol prima di eseguire un'istruzione.
Commenti
Un'applicazione chiama in genere SQLDescribeCol dopo una chiamata a SQLPrepare e prima o dopo la chiamata associata a SQLExecute. Un'applicazione può anche chiamare SQLDescribeCol dopo una chiamata a SQLExecDirect. Per altre informazioni, vedere Metadati del set di risultati.
SQLDescribeCol recupera il nome, il tipo e la lunghezza della colonna generati da un'istruzione SELECT . Se la colonna è un'espressione, *ColumnName è una stringa vuota o un nome definito dal driver.
Nota
ODBC supporta SQL_NULLABLE_UNKNOWN come estensione, anche se la specifica Open Group e SQL Access Group Call Level Interface non specifica l'opzione per SQLDescribeCol.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a una colonna in un set di risultati | SQLBindCol |
| Annullamento dell'elaborazione delle istruzioni | SQLCancel |
| Restituzione di informazioni su una colonna in un set di risultati | SQLColAttribute |
| Recupero di più righe di dati | SQLFetch |
| Restituzione del numero di colonne del set di risultati | SQLNumResultCols |
| Preparazione di un'istruzione per l'esecuzione | Sqlprepare |