Função SQLDescribeCol
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
SQLDescribeCol retorna o descritor de 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
StatementHandle
[Entrada] Identificador de instrução.
ColumnNumber
[Entrada] Número de colunas de dados de resultado, ordenados sequencialmente em ordem de coluna crescente, começando em 1. O argumento ColumnNumber também pode ser definido como 0 para descrever a coluna de indicador.
ColumnName
[Saída] Ponteiro para um buffer encerrado em nulo no qual retornar o nome da coluna. Esse valor é lido no campo SQL_DESC_NAME do IRD. Se a coluna não tiver nome ou o nome da coluna não puder ser determinado, o driver retornará uma cadeia de caracteres vazia.
Se ColumnName for NULL, NameLengthPtr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por ColumnName.
BufferLength
[Entrada] Comprimento do buffer *ColumnName , em caracteres.
NameLengthPtr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo a terminação nula) disponível para retornar em *ColumnName. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength, o nome da coluna em *ColumnName será truncado para BufferLength menos o comprimento de um caractere de terminação nula.
DataTypePtr
[Saída] Ponteiro para um buffer no qual retornar o tipo de dados SQL da coluna. Esse valor é lido no campo SQL_DESC_CONCISE_TYPE do IRD. Esse será um dos valores em Tipos de Dados SQL ou um tipo de dados SQL específico do driver. Se o tipo de dados não puder ser determinado, o driver retornará SQL_UNKNOWN_TYPE.
No ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP é retornado em *DataTypePtr para dados de data, hora ou carimbo de data/hora, respectivamente; no ODBC 2. x, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP é retornado. O Gerenciador de Driver executa os mapeamentos necessários quando um ODBC 2. O aplicativo x está trabalhando com um ODBC 3. x driver ou quando um ODBC 3. o aplicativo x está trabalhando 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 ODBC 2. x driver ou por um ODBC 2. x aplicativo trabalhando com um ODBC 3. x driver.)
Para obter mais informações sobre esses 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 do driver, confira a documentação do driver.
ColumnSizePtr
[Saída] Ponteiro para um buffer no qual retornar o tamanho (em caracteres) da coluna na fonte de dados. Se o tamanho da coluna não puder ser determinado, o driver retornará 0. Para obter mais informações sobre o tamanho da coluna, consulte Tamanho da coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados.
DecimalDigitsPtr
[Saída] Ponteiro para um buffer no qual retornar 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 retornará 0. Para obter mais informações sobre dígitos decimais, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados.
NullablePtr
[Saída] Ponteiro para um buffer no qual retornar um valor que indica se a coluna permite valores NULL. Esse valor é lido no 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.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLDescribeCol e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 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 *ColumnName não era grande o suficiente para retornar o nome de coluna inteiro, portanto, o nome da coluna foi truncado. O comprimento do nome da coluna não confiável é 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 StatementHandle não retornou um conjunto de resultados. Não havia colunas para descrever. |
| 07009 | Índice de descritor inválido | (DM) O valor especificado para o argumento ColumnNumber era igual a 0 e a opção de instrução SQL_ATTR_USE_BOOKMARKS foi SQL_UB_OFF. O valor especificado para o argumento ColumnNumber foi 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 foi conectado falhou antes da conclusão do processamento da função. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia nenhum 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ções | (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 SQLDescribeCol foi chamado. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi 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) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) A função foi chamada antes de chamar SQLPrepare, SQLExecute ou uma função de catálogo no identificador de instrução. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados SQL_NEED_DATA. Essa função foi chamada antes de os dados serem 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 | Comprimento de buffer ou cadeia de caracteres inválido | (DM) O valor especificado para o argumento BufferLength era menor que 0. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar 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 da fonte de dados responder à 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 dá suporte a essa 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 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 identificador de instrução.
Por motivos de desempenho, um aplicativo não deve chamar SQLDescribeCol antes de executar uma instrução .
Comentários
Um aplicativo normalmente chama SQLDescribeCol após uma chamada para SQLPrepare e antes ou depois da chamada associada para SQLExecute. Um aplicativo também pode chamar SQLDescribeCol após uma chamada para SQLExecDirect. Para obter mais informações, consulte Metadados do conjunto de resultados.
SQLDescribeCol recupera o nome, o tipo e o comprimento da coluna gerados por uma instrução SELECT . Se a coluna for uma expressão, *ColumnName será uma cadeia de caracteres vazia ou um nome definido pelo driver.
Observação
O ODBC dá suporte a SQL_NULLABLE_UNKNOWN como uma extensão, embora a especificação Open Group e SQL Access Group Call Level Interface não especifique a opção para SQLDescribeCol.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associar um buffer a uma coluna em um conjunto de resultados | SQLBindCol |
| Cancelando o processamento da instrução | 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 |