Funzione SQLColumns

Conformità
Versione introdotta: Conformità agli Standard ODBC 1.0: Open Group

Sommario
SQLColumns restituisce l'elenco dei nomi delle colonne in tabelle specificate. Il driver restituisce queste informazioni come set di risultati sull'StatementHandle specificato.

Sintassi

  
SQLRETURN SQLColumns(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      ColumnName,  
     SQLSMALLINT    NameLength4);  

Arguments

StatementHandle
[Input] Handle di istruzione.

CatalogName
[Input] Nome catalogo. Se un driver supporta cataloghi per alcune tabelle ma non per altre, ad esempio quando il driver recupera dati da diversi DBMS, una stringa vuota ("") indica quelle tabelle che non hanno cataloghi. CatalogName non può contenere un pattern di ricerca a stringhe.

NameLength1
[Input] Lunghezza nei caratteri di *NomeCatalogo.

SchemaName
[Input] Pattern di ricerca stringa per i nomi degli schemi. Se un driver supporta gli schemi per alcune tabelle ma non per altre, ad esempio quando il driver recupera dati da diversi DBMS, una stringa vuota ("") indica quelle tabelle che non hanno schema.

NameLength2
[Input] Lunghezza nei caratteri di *NomeSchema.

TableName
[Input] Pattern di ricerca stringa per i nomi delle tabelle.

NameLength3
[Input] Lunghezza nei caratteri di *NomeTabella.

ColumnName
[Input] Pattern di ricerca stringa per i nomi delle colonne.

NameLength4
[Input] Lunghezza in caratteri di *NomeColonna.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLColumns 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 tipicamente restituiti da SQLColumns e li spiega 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.

Comments

Questa funzione viene tipicamente utilizzata prima dell'esecuzione dell'istruzione per recuperare informazioni sulle colonne di una tabella o delle tabelle dal catalogo della fonte dati. SQLColumns può essere utilizzato per recuperare dati per tutti i tipi di elementi restituiti da SQLTables. Oltre alle tabelle base, questo può includere (ma non è limitato a) viste, sinonimi, tabelle di sistema e così via. Al contrario, le funzioni SQLColAttribute e SQLDescribeCol descrivono le colonne in un insieme di risultati e la funzione SQLNumResultCols restituisce il numero di colonne in un insieme di risultati. Per altre informazioni, vedere Usi dei dati del catalogo.

SQLColumns restituisce i risultati come un insieme standard, ordinato da TABLE_CAT, TABLE_SCHEM, TABLE_NAME e ORDINAL_POSITION.

Le lunghezze delle colonne VARCHAR non sono indicate nella tabella; Le lunghezze effettive dipendono dalla fonte dei dati. Per determinare la lunghezza effettiva delle colonne TABLE_CAT, TABLE_SCHEM, TABLE_NAME e COLUMN_NAME, un'applicazione può chiamare SQLGetInfo con le opzioni SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.

Le seguenti colonne sono state rinominate in ODBC 3. x. I cambiamenti nel nome delle colonne non influiscono sulla retrocompatibilità perché le applicazioni si assegnano per numero di colonna.

Le seguenti colonne sono state aggiunte al set di risultati restituito da SQLColumns per ODBC 3. x:

Nella tabella seguente sono elencate le colonne nel set di risultati. Colonne aggiuntive oltre la colonna 18 (IS_NULLABLE) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati invece di specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

Esempio di codice

Nel seguente esempio, un'applicazione dichiara buffer per il set di risultati restituito da SQLColumns. Chiama SQLColumns per restituire un set di risultati che descrive ogni colonna nella tabella EMPLOYEE. Chiama quindi SQLBindCol per associare le colonne dell'insieme di risultati ai buffer. Infine, l'applicazione recupera ogni riga di dati con SQLFetch e li elabora.

// SQLColumns_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqlext.h>  
#define STR_LEN 128 + 1  
#define REM_LEN 254 + 1  
  
// Declare buffers for result set data  
SQLCHAR szSchema[STR_LEN];  
SQLCHAR szCatalog[STR_LEN];  
SQLCHAR szColumnName[STR_LEN];  
SQLCHAR szTableName[STR_LEN];  
SQLCHAR szTypeName[STR_LEN];  
SQLCHAR szRemarks[REM_LEN];  
SQLCHAR szColumnDefault[STR_LEN];  
SQLCHAR szIsNullable[STR_LEN];  
  
SQLINTEGER ColumnSize;  
SQLINTEGER BufferLength;  
SQLINTEGER CharOctetLength;  
SQLINTEGER OrdinalPosition;  
  
SQLSMALLINT DataType;  
SQLSMALLINT DecimalDigits;  
SQLSMALLINT NumPrecRadix;  
SQLSMALLINT Nullable;  
SQLSMALLINT SQLDataType;  
SQLSMALLINT DatetimeSubtypeCode;  
  
SQLHSTMT hstmt = NULL;  
  
// Declare buffers for bytes available to return  
SQLINTEGER cbCatalog;  
SQLINTEGER cbSchema;  
SQLINTEGER cbTableName;  
SQLINTEGER cbColumnName;  
SQLINTEGER cbDataType;  
SQLINTEGER cbTypeName;  
SQLINTEGER cbColumnSize;  
SQLLEN cbBufferLength;  
SQLINTEGER cbDecimalDigits;  
SQLINTEGER cbNumPrecRadix;  
SQLINTEGER cbNullable;  
SQLINTEGER cbRemarks;  
SQLINTEGER cbColumnDefault;  
SQLINTEGER cbSQLDataType;  
SQLINTEGER cbDatetimeSubtypeCode;  
SQLINTEGER cbCharOctetLength;  
SQLINTEGER cbOrdinalPosition;  
SQLINTEGER cbIsNullable;  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
   retcode = SQLColumns(hstmt, NULL, 0, NULL, 0, (SQLCHAR*)"CUSTOMERS", SQL_NTS, NULL, 0);  
  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      // Bind columns in result set to buffers  
      SQLBindCol(hstmt, 1, SQL_C_CHAR, szCatalog, STR_LEN,&cbCatalog);  
      SQLBindCol(hstmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);  
      SQLBindCol(hstmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&cbTableName);  
      SQLBindCol(hstmt, 4, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);  
      SQLBindCol(hstmt, 5, SQL_C_SSHORT, &DataType, 0, &cbDataType);  
      SQLBindCol(hstmt, 6, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);  
      SQLBindCol(hstmt, 7, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);  
      SQLBindCol(hstmt, 8, SQL_C_SLONG, &BufferLength, 0, &cbBufferLength);  
      SQLBindCol(hstmt, 9, SQL_C_SSHORT, &DecimalDigits, 0, &cbDecimalDigits);  
      SQLBindCol(hstmt, 10, SQL_C_SSHORT, &NumPrecRadix, 0, &cbNumPrecRadix);  
      SQLBindCol(hstmt, 11, SQL_C_SSHORT, &Nullable, 0, &cbNullable);  
      SQLBindCol(hstmt, 12, SQL_C_CHAR, szRemarks, REM_LEN, &cbRemarks);  
      SQLBindCol(hstmt, 13, SQL_C_CHAR, szColumnDefault, STR_LEN, &cbColumnDefault);  
      SQLBindCol(hstmt, 14, SQL_C_SSHORT, &SQLDataType, 0, &cbSQLDataType);  
      SQLBindCol(hstmt, 15, SQL_C_SSHORT, &DatetimeSubtypeCode, 0, &cbDatetimeSubtypeCode);  
      SQLBindCol(hstmt, 16, SQL_C_SLONG, &CharOctetLength, 0, &cbCharOctetLength);  
      SQLBindCol(hstmt, 17, SQL_C_SLONG, &OrdinalPosition, 0, &cbOrdinalPosition);  
      SQLBindCol(hstmt, 18, SQL_C_CHAR, szIsNullable, STR_LEN, &cbIsNullable);  
  
      while (SQL_SUCCESS == retcode) {  
         retcode = SQLFetch(hstmt);  
         /*  
         if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
            0;   // show_error();  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
            0;   // Process fetched data  
         else  
            break;  
        */  
      }  
   }  
}  

Funzioni correlate

Contenuti correlati

• Riferimento API ODBC
• File di intestazione ODBC