Funzione SQLDescribeCol

  • Articolo

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC