Função SQLColumns

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 1.0: Open Group

Summary
O SQLColumns devolve a lista de nomes de colunas em tabelas especificadas. O driver devolve esta informação como um conjunto de resultados no StatementHandle especificado.

Syntax

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

Arguments

HandleStatement
[Entrada] Identificador do extrato.

Nome do Catálogo
[Entrada] Nome do catálogo. Se um driver suporta catálogos para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma string vazia ("") indica as tabelas que não têm catálogos. O CatalogName não pode conter um padrão de pesquisa em cadeia de caracteres.

NomeComprimento1
[Entrada] Comprimento em caracteres de *NomeDeCatálogo.

Nome do esquema
[Entrada] Padrão de pesquisa de cadeias para nomes de esquemas. Se um driver suporta esquemas para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma cadeia vazia ("") indica aquelas tabelas que não têm esquemas.

NomeComprimento2
[Entrada] Comprimento em caracteres de *NomeEsquema.

TableName
[Entrada] Padrão de pesquisa de cadeias para nomes de tabelas.

NomeComprimento3
[Entrada] Comprimento em caracteres de *NomeTabela.

NomeDaColuna
[Entrada] Padrão de pesquisa de cadeia de caracteres para nomes de coluna.

NomeComprimento4
[Entrada] Comprimento em caracteres de *ColumnName.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando o SQLColumns retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLColumns e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

Comments

Esta função é normalmente usada antes da execução da instrução para recuperar informação sobre colunas para uma tabela ou tabelas do catálogo da fonte de dados. O SQLColumns pode ser usado para recuperar dados de todos os tipos de itens devolvidos pelo SQLTables. Para além das tabelas base, isto pode incluir (mas não se limita a) vistas, sinónimos, tabelas do sistema, e assim por diante. Em contraste, as funções SQLColAttribute e SQLDescribeCol descrevem as colunas num conjunto de resultados e a função SQLNumResultCols devolve o número de colunas num conjunto de resultados. Para mais informações, consulte Utilizações dos Dados de Catálogo.

O SQLColumns devolve os resultados como um conjunto padrão de resultados, ordenado por TABLE_CAT, TABLE_SCHEM, TABLE_NAME e ORDINAL_POSITION.

Os comprimentos das colunas VARCHAR não estão indicados na tabela; Os comprimentos reais dependem da fonte de dados. Para determinar os comprimentos reais das colunas TABLE_CAT, TABLE_SCHEM, TABLE_NAME e COLUMN_NAME, uma aplicação pode chamar SQLGetInfo com as opções SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.

As colunas seguintes foram renomeadas para ODBC 3. x. As alterações no nome das colunas não afetam a compatibilidade retroativa porque as aplicações associam por número de coluna.

As colunas seguintes foram adicionadas ao conjunto de resultados devolvido pelo SQLColumns para o ODBC 3. x:

A tabela seguinte lista as colunas do conjunto de resultados. Colunas adicionais para além da coluna 18 (IS_NULLABLE) podem ser definidas pelo driver. Uma aplicação deve aceder a colunas específicas do driver contando decrescentemente a partir do final do conjunto de resultados em vez de especificar uma posição ordinal explícita. Para mais informações, consulte Dados Devolvidos por Funções de Catálogo.

Exemplo de código

No exemplo seguinte, uma aplicação declara buffers para o conjunto de resultados devolvido pelo SQLColumns. Chama SQLColumns para devolver um conjunto de resultados que descreve cada coluna da tabela EMPLOYEE. Depois chama SQLBindCol para associar as colunas do conjunto de resultados aos buffers. Finalmente, a aplicação recolhe cada linha de dados com SQLFetch e processa-os.

// 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;  
        */  
      }  
   }  
}  

Funções relacionadas

Conteúdo relacionado

• Referência da API ODBC
• Ficheiros de Cabeçalho ODBC