Função SQLDescribeCol

Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92

Summary
O SQLDescribeCol devolve o descritor do resultado - nome da coluna, tipo, tamanho da coluna, dígitos decimais e anulabilidade - para uma coluna do conjunto de resultados. Esta informação também está disponível nos campos do IRD.

Syntax

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);

Arguments

HandleStatement
[Entrada] Identificador do extrato.

Número da Coluna
[Entrada] Número de colunas de dados de resultados, ordenados sequencialmente em ordem crescente de colunas, começando em 1. O argumento ColumnNumber também pode ser definido como 0 para descrever a coluna de favoritos.

NomeDaColuna
[Saída] Apontador para um buffer terminado por nulo onde se deve devolver o nome da coluna. Este valor é lido a partir do campo SQL_DESC_NAME do IRD. Se a coluna não for nomeada ou o nome da coluna não puder ser determinado, o driver devolve uma cadeia vazia.

Se o ColumnName for NULL, o NameLengthPtr continuará a devolver o número total de caracteres (excluindo o carácter de terminação nula para os dados de caracteres) disponíveis para devolver no buffer apontado pelo ColumnName.

BufferLength
[Entrada] Comprimento do buffer *Nomecolina , em caracteres.

NomeComprimentoPtr
[Saída] Apontador para um buffer onde se deve devolver o número total de caracteres (excluindo a terminação nula) disponíveis para devolver em *NomeColumnName. Se o número de caracteres disponíveis para devolver for maior ou igual a BufferLength, o nome da coluna em *ColumnName é truncado para BufferLength menos o comprimento de um carácter de terminação nula.

DataTypePtr
[Saída] Apontador para um buffer onde se deve devolver o tipo de dado SQL da coluna. Este valor é lido a partir do campo SQL_DESC_CONCISE_TYPE do IRD. Este será um dos valores nos Tipos de Dados SQL, ou um tipo de dado SQL específico do driver. Se o tipo de dado não puder ser determinado, o driver devolve SQL_UNKNOWN_TYPE.

No ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP é devolvido em *DataTypePtr para dados de data, hora ou carimbo temporal, respetivamente; em ODBC 2. X, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP é devolvido. O Gestor de Drivers realiza os mapeamentos necessários quando um ODBC 2. a aplicação x está a funcionar com um ODBC 3. driver x ou quando é um ODBC 3. A aplicação x está a funcionar com um ODBC 2. Condutor X .

Quando Número de Coluna é igual a 0 (para uma coluna de favoritos), SQL_BINARY é devolvido em *DataTypePtr para marcadores de comprimento variável. (SQL_INTEGER é devolvido se os favoritos forem usados por um ODBC 3. Aplicação x a funcionar com um ODBC 2. x ou por um ODBC 2. Aplicação x a funcionar com um ODBC 3. x condutor.)

Para mais informações sobre estes tipos de dados, consulte Tipos de Dados SQL no Apêndice D: Tipos de Dados. Para informações sobre tipos de dados SQL específicos de cada driver, consulte a documentação do driver.

ColumnSizePtr
[Saída] Apontador para um buffer onde se deve devolver o tamanho (em caracteres) da coluna na fonte de dados. Se o tamanho da coluna não puder ser determinado, o driver retorna 0. Para mais informações sobre o tamanho da coluna, consulte Tamanho da Coluna, Dígitos Decimais, Comprimento do Octeto de Transferência e Tamanho do Ecrã no Apêndice D: Tipos de Dados.

DecimalDigitsPtr
[Saída] Apontador para um buffer onde deves o número de dígitos decimais da coluna na fonte de dados. Se o número de dígitos decimais não puder ser determinado ou não for aplicável, o driver devolve 0. Para mais informações sobre dígitos decimais, consulte Tamanho da Coluna, Dígitos Decimais, Comprimento do Octeto de Transferência e Tamanho do Ecrã no Apêndice D: Tipos de Dados.

NullablePtr
[Saída] Apontador para um buffer no qual devolver um valor que indica se a coluna permite valores NULL. Este valor é lido a partir do campo SQL_DESC_NULLABLE do IRD. O valor é um dos seguintes:

SQL_NO_NULLS: A coluna não permite valores NULL.

SQL_NULLABLE: A coluna permite valores NULL.

SQL_NULLABLE_UNKNOWN: O driver não pode determinar se a coluna permite valores NULL.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando o SQLDescribeCol 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 SQLDescribeCol 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.

SQLSTATE Erro Description
01000 Aviso geral Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia, truncados à direita O buffer *ColumnName não era suficientemente grande para devolver o nome da coluna inteiro, pelo que o nome da coluna foi truncado. O comprimento do nome da coluna não arrunhado é devolvido em *NameLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.)
07005 Instrução preparada, não uma especificação de cursor A instrução associada ao HandleStatement não devolveu um conjunto de resultados. Não havia colunas para descrever.
07009 Índice de descritores inválido (DM) O valor especificado para o argumento Número da Coluna era igual a 0, e a opção de SQL_ATTR_USE_BOOKMARKS afirmação era SQL_UB_OFF.

O valor especificado para o argumento Número das Colunas era maior do que o número de colunas no conjunto de resultados.
08S01 Falha da ligação de comunicação A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento.
HY000 Erro geral Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa.
HY001 Falha de alocação de memória O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY008 Operação cancelada O processamento assíncrono foi ativado para o StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle. Depois, a função era chamada novamente no StatementHandle.

A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle a partir de um thread diferente numa aplicação multithread.
HY010 Erro de sequência de funções (DM) Uma função de execução assíncrona era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando o SQLDescribeCol foi chamado.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o StatementHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos.

(DM) Uma função de execução assíncrona (não esta) era chamada para o StatementHandle e continuava a ser executada quando esta função era chamada.

(DM) A função era chamada antes de chamar SQLPrepare, SQLExecute ou uma função de catálogo no handle da instrução.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para o StatementHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução.
HY013 Erro de gestão de memória A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY090 Comprimento inválido da corda ou do buffer (DM) O valor especificado para o argumento BufferLength era inferior a 0.
HY117 A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYT01 Expirou o tempo limite de ligação O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não suporta esta função (DM) O driver associado ao StatementHandle não suporta a função.
IM017 A sondagem está desativada no modo de notificação assíncrona Sempre que o modelo de notificação é utilizado, o sonding é desativado.
IM018 O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle. Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação.

O SQLDescribeCol pode devolver qualquer estado SQLSTATE que possa ser devolvido por SQLPrepare ou SQLExecute quando chamado após SQLPrepare e antes do SQLExecute, dependendo de quando a fonte de dados avalia a instrução SQL associada ao handle da instrução.

Por razões de desempenho, uma aplicação não deve chamar o SQLDescribeCol antes de executar uma instrução.

Comments

Uma aplicação normalmente chama SQLDescribeCol após uma chamada ao SQLPrepare e antes ou depois da chamada associada ao SQLExecute. Uma aplicação também pode chamar SQLDescribeCol após uma chamada ao SQLExecDirect. Para mais informações, consulte Metadados do Conjunto de Resultados.

O SQLDescribeCol recupera o nome, tipo e comprimento da coluna gerados por uma instrução SELECT . Se a coluna for uma expressão, *ColumnName é ou uma cadeia vazia ou um nome definido pelo driver.

Note

O ODBC suporta SQL_NULLABLE_UNKNOWN como extensão, embora a especificação Open Group e SQL Access Group Call Level Interface não especifique a opção para SQLDescribeCol.

Para obter informações sobre Veja
Ligar um buffer a uma coluna num conjunto de resultados SQLBindCol
Cancelamento do processamento de extratos SQLCancel
Devolver informação sobre uma coluna num conjunto de resultados SQLColAttribute
Obtenção de várias linhas de dados SQLFetch
Devolvendo o número de colunas do conjunto de resultados SQLNumResultCols
Preparação de uma declaração para execução SQLPrepare

Conteúdo relacionado

  • Last updated on