Funzione SQLDescribeCol

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

Sommario
SQLDescribeCol restituisce il descrittore del risultato - nome della colonna, tipo, dimensione della colonna, cifre decimali e nullabilità - per una colonna nell'insieme 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);  

Arguments

StatementHandle
[Input] Handle di istruzione.

Numero di colonna
[Input] Numero di colonne dei dati di risultato, ordinati sequenzialmente in ordine crescente di colonne, a partire da 1. L'argomento ColumnNumber può anche essere impostato a 0 per descrivere la colonna dei segnalibri.

ColumnName
[Output] Puntatore a un buffer terminato nullo in cui restituire il nome della colonna. Questo valore viene letto dal campo SQL_DESC_NAME dell'IRD. Se la colonna non ha nome o il nome della colonna non può essere determinato, il driver restituisce una stringa vuota.

Se ColumnName è NULL, NameLengthPtr restituirà comunque il numero totale di caratteri (escluso il carattere di null-termination per i dati dei caratteri) disponibili da restituire nel buffer indicato da 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 nulla) disponibili da restituire in *NomeColonna. Se il numero di caratteri disponibili da restituire è maggiore o uguale a BufferLength, il nome della colonna in *ColumnName viene troncato a BufferLength meno la lunghezza di un carattere a null-termination.

DataTypePtr
[Output] Puntatore a un buffer in cui restituire il tipo di dato SQL della colonna. Questo valore viene letto dal campo SQL_DESC_CONCISE_TYPE dell'IRD. Questo sarà uno dei valori nei Tipi di Dati SQL, o un tipo di dato SQL specifico per il driver. Se il tipo di dato non può essere determinato, il driver restituisce SQL_UNKNOWN_TYPE.

In ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME o SQL_TYPE_TIMESTAMP viene restituito in *DataTypePtr per i dati di data, ora o timestamp, rispettivamente; in ODBC 2. x, SQL_DATE, SQL_TIME o SQL_TIMESTAMP viene restituito. 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 maggiori informazioni su questi tipi di dati, vedi 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 la dimensione (in caratteri) della colonna sulla sorgente dati. Se la dimensione della colonna non può essere determinata, 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 sulla sorgente dati. Se il numero di cifre decimali non può essere determinato o non è applicabile, il driver restituisce 0. Per maggiori informazioni sulle cifre decimali, vedi Dimensione della colonna, Cifre decimali, Lunghezza dell'ottetto di trasferimento e Dimensione del display 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 dell'IRD. Il valore può essere uno dei seguenti:

SQL_NO_NULLS: La colonna non consente valori NULL.

SQL_NULLABLE: La colonna consente valori NULL.

SQL_NULLABLE_UNKNOWN: Il driver non può determinare se la colonna consente valori NULL.

Returns

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, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLDescribeCol e spiega ciascuno nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLDescribeCol può restituire qualsiasi stato SQLS che possa essere restituito da SQLPrepare o SQLExecute quando chiamato dopo SQLPrepare e prima di SQLExecute, a seconda di quando la sorgente di dati valuta l'istruzione SQL associata all'handle dell'istruzione.

Per motivi di prestazioni, un'applicazione non dovrebbe chiamare SQLDescribeCol prima di eseguire un'istruzione.

Comments

Un'applicazione tipicamente chiama 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 ulteriori informazioni, vedere Set di risultati di metadati.

SQLDescribeCol recupera il nome della colonna, il tipo e la lunghezza generati da un'istruzione SELECT . Se la colonna è un'espressione, *ColumnName è o una stringa vuota o un nome definito dal driver.

Funzioni correlate

Contenuti correlati

• Riferimento API ODBC
• File di intestazione ODBC