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.

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.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC