Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Conformidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Summary
O SQLDescribeCol retorna o descritor do resultado - nome da coluna, tipo, tamanho da coluna, dígitos decimais e nulidade - para uma coluna no conjunto de resultados. Essas informações também estão disponíveis nos campos do IRD.
Sintaxe
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Número da Coluna
[Entrada] Número de colunas dos dados de resultados, ordenados sequencialmente em ordem crescente de coluna, começando em 1. O argumento Número de Colomna também pode ser definido como 0 para descrever a coluna de favoritos.
ColumnName
[Saída] Apontador para um buffer terminado por nulo no qual deveria retornar o nome da coluna. Esse 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 retorna uma cadeia vazia.
Se NomeColumn for NULL, NameLengthPtr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para serem retornados no buffer apontado por NomeColumnName.
BufferLength
[Entrada] Comprimento do buffer *Nomecolina , em caracteres.
NameLengthPtr
[Saída] Apontador para um buffer no qual retorna o número total de caracteres (excluindo a terminação nula) disponíveis para retorno em *NomeColumnWord. Se o número de caracteres disponíveis para retorno for maior ou igual a BufferLength, o nome da coluna em *ColumnName é truncado para BufferLength menos o comprimento de um caractere de terminação nula.
DataTypePtr
[Saída] Apontador para um buffer no qual retorna o tipo de dado SQL da coluna. Esse valor é lido a partir do campo SQL_DESC_CONCISE_TYPE do IRD. Esse será um dos valores em Tipos de Dados SQL, ou um tipo de dado SQL específico para o driver. Se o tipo de dado não puder ser determinado, o driver retorna SQL_UNKNOWN_TYPE.
No ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP são retornados em *DataTypePtr para dados de data, hora ou carimbo de data, respectivamente; em ODBC 2. X, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP é devolvido. O Gerenciador de Driver executa os mapeamentos necessários quando um ODBC 2.x está funcionando com um ODBC 3.x ou quando um driver ODBC 3.x está funcionando com um ODBC 2.x driver.
Quando ColumnNumber é igual a 0 (para uma coluna de indicador), SQL_BINARY é retornado em *DataTypePtr para indicadores de comprimento variável. (SQL_INTEGER será retornado se os indicadores forem usados por um ODBC 3.x aplicativo trabalhando com um aplicativo ODBC 2.x ou por um ODBC 2.x aplicativo trabalhando com um ODBC 3.x driver.)
Para mais informações sobre esses tipos de dados, veja Tipos de Dados SQL no Apêndice D: Tipos de Dados. Para informações sobre tipos de dados SQL específicos do driver, confira a documentação do driver.
ColumnSizePtr
[Saída] Apontador para um buffer no qual retorna 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 obter mais informações sobre o tamanho da coluna, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho de exibição no Apêndice D: Tipos de dados.
DecimalDigitsPtr
[Saída] Apontador para um buffer no qual retorna 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 retorna 0. Para mais informações sobre dígitos decimais, veja Tamanho da Colunha, Dígitos Decimais, Comprimento do Octeto de Transferência e Tamanho da Exibição no Apêndice D: Tipos de Dados.
NullablePtr
[Saída] Apontador para um buffer no qual retorna um valor que indica se a coluna permite valores NULL. Esse 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.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Quando 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 a seguir lista os valores SQLSTATE comumente retornados pelo SQLDescribeCol e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | O buffer *NomeColuna não era grande o suficiente para retornar o nome da coluna inteiro, então o nome da coluna foi truncado. O comprimento do nome da coluna não arrunada é retornado em *NameLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07005 | Instrução preparada, não uma especificação de cursor | A instrução associada ao HandleStatement não retornou 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 de Coluna era igual a 0, e a opção de SQL_ATTR_USE_BOOKMARKS instrução era SQL_UB_OFF. O valor especificado para o argumento Número de Colunas era maior que o número de colunas no conjunto de resultados. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Falha de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando o SQLDescribeCol foi chamado. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi 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 foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY090 | Cadeia de caracteres ou comprimento de buffer inválido | (DM) O valor especificado para o argumento BufferLength era menor que 0. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao StatementHandle não dá suporte à função. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
SQLDescribeCol pode retornar qualquer estado SQLSTATE que possa ser retornado por SQLPrepare ou SQLExecute quando chamado após SQLPrepare e antes de SQLExecute, dependendo de quando a fonte de dados avalia a instrução SQL associada ao handle.
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 para SQLPrepare e antes ou depois da chamada associada para SQLExecute. Uma aplicação também pode chamar SQLDescribeCol após uma chamada para SQLExecDirect. Para obter mais informações, confira Metadados de 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, *NomeColuna é ou uma string vazia ou um nome definido pelo driver.
Note
ODBC suporta SQL_NULLABLE_UNKNOWN como extensão, mesmo que a especificação Open Group and SQL Access Group Call Level Interface não especifique a opção para SQLDescribeCol.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | SQLBindCol |
| Cancelando o processamento de instruções | Sqlcancel |
| Retornando informações sobre uma coluna em um conjunto de resultados | Sqlcolattribute |
| Buscando várias linhas de dados | SQLFetch |
| Retornando o número de colunas do conjunto de resultados | SQLNumResultCols |
| Preparando uma instrução para execução | Sqlprepare |