Função SQLGetTypeInfo
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLGetTypeInfo retorna informações sobre os tipos de dados compatíveis com a fonte de dados. O driver retorna as informações na forma de um conjunto de resultados SQL. Os tipos de dados destinam-se ao uso em instruções DDL (Data Definition Language).
Importante
Os aplicativos devem usar os nomes de tipo retornados na coluna TYPE_NAME do conjunto de resultados SQLGetTypeInfo nas instruções ALTER TABLE e CREATE TABLE . SQLGetTypeInfo pode retornar mais de uma linha com o mesmo valor na coluna DATA_TYPE.
Sintaxe
SQLRETURN SQLGetTypeInfo(
SQLHSTMT StatementHandle,
SQLSMALLINT DataType);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução para o conjunto de resultados.
DataType
[Entrada] O tipo de dados SQL. Esse deve ser um dos valores na seção Tipos de Dados SQL do Apêndice D: Tipos de Dados ou um tipo de dados SQL específico do driver. SQL_ALL_TYPES especifica que as informações sobre todos os tipos de dados devem ser retornadas.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetTypeInfo 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 normalmente retornados por SQLGetTypeInfo 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.) |
| 01S02 | Valor da opção alterado | Um atributo de instrução especificado era inválido devido às condições de trabalho de implementação, portanto, um valor semelhante foi substituído temporariamente. (Chamada SQLGetStmtAttr para determinar o valor temporariamente substituído.) O valor substituto é válido para o StatementHandle até que o cursor seja fechado. Os atributos de instrução que podem ser alterados são: SQL_ATTR_CONCURRENCY, SQL_ATTR_CURSOR_TYPE, SQL_ATTR_KEYSET_SIZE, SQL_ATTR_MAX_LENGTH, SQL_ATTR_MAX_ROWS, SQL_ATTR_QUERY_TIMEOUT e SQL_ATTR_SIMULATE_CURSOR. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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. |
| 24.000 | Estado de cursor inválido | Um cursor estava aberto no StatementHandle e SQLFetch ou SQLFetchScroll havia sido chamado. Esse erro será retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e será retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA. Um conjunto de resultados estava aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não havia sido chamado. |
| 40001 | Falha de serialização | A transação foi revertida devido a um deadlock de recursos com outra transação. |
| 40003 | Conclusão da instrução desconhecida | A conexão associada falhou durante a execução dessa função e o estado da transação não pode ser determinado. |
| 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 | Erro 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. |
| HY004 | Tipo de dados SQL inválido | O valor especificado para o argumento DataType não era um identificador de tipo de dados SQL ODBC válido nem um identificador de tipo de dados específico do driver compatível com o driver. |
| 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 a função SQLGetTypeInfo foi chamada. (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) 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. |
| 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. |
| HYC00 | Recurso opcional não implementado | A combinação das configurações atuais dos atributos de instrução SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE não era compatível com o driver ou a fonte de dados. O atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_VARIABLE e o atributo de instrução SQL_ATTR_CURSOR_TYPE foi definido como um tipo de cursor para o qual o driver não dá suporte a indicadores. |
| HYT00 | Timeout expired | O período de tempo limite da consulta expirou antes que a fonte de dados retornasse o conjunto de resultados. O período de tempo limite é definido por meio de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 correspondente 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. |
Comentários
SQLGetTypeInfo retorna os resultados como um conjunto de resultados padrão, ordenado por DATA_TYPE e, em seguida, por quão próximo o tipo de dados é mapeado para o tipo de dados SQL ODBC correspondente. Os tipos de dados definidos pela fonte de dados têm precedência sobre os tipos de dados definidos pelo usuário. Consequentemente, a ordem de classificação não é necessariamente consistente, mas pode ser generalizada como DATA_TYPE primeiro, seguido por TYPE_NAME, ambos crescentes. Por exemplo, suponha que uma fonte de dados tenha definido os tipos de dados INTEGER e COUNTER, em que COUNTER é incrementado automaticamente, e que um tipo de dados definido pelo usuário WHOLENUM também tenha sido definido. Eles seriam retornados na ordem INTEGER, WHOLENUM e COUNTER, pois WHOLENUM mapeia de perto o tipo de dados SQL ODBC SQL_INTEGER, enquanto o tipo de dados de incremento automático, embora suportado pela fonte de dados, não mapeia de perto para um tipo de dados SQL ODBC. Para obter informações sobre como essas informações podem ser usadas, consulte Instruções DDL.
Se o argumento DataType especificar um tipo de dados válido para a versão do ODBC compatível com o driver, mas não compatível com o driver, ele retornará um conjunto de resultados vazio.
Observação
Para obter mais informações sobre o uso geral, argumentos e dados retornados de funções de catálogo ODBC, consulte Funções de catálogo.
As colunas a seguir foram renomeadas para ODBC 3.x. As alterações de nome de coluna não afetam a compatibilidade com versões anteriores porque os aplicativos são associados pelo número da coluna.
| Coluna ODBC 2.0 | ODBC 3.coluna x |
|---|---|
| PRECISION | COLUMN_SIZE |
| MONEY | FIXED_PREC_SCALE |
| AUTO_INCREMENT | AUTO_UNIQUE_VALUE |
As colunas a seguir foram adicionadas ao conjunto de resultados retornado por SQLGetTypeInfo para ODBC 3.x:
SQL_DATA_TYPE
INTERVAL_PRECISION
SQL_DATETIME_SUB
NUM_PREC_RADIX
A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 19 (INTERVAL_PRECISION) podem ser definidas pelo driver. Um aplicativo deve obter acesso a colunas específicas do driver fazendo uma contagem regressiva a partir do final do conjunto de resultados, em vez de especificar uma posição ordinal explícita. Para obter mais informações, consulte Dados retornados por funções de catálogo.
Observação
SQLGetTypeInfo pode não retornar todos os tipos de dados. Por exemplo, um driver pode não retornar tipos de dados definidos pelo usuário. Os aplicativos podem usar qualquer tipo de dados válido, independentemente de ele ser retornado por SQLGetTypeInfo. Os tipos de dados retornados por SQLGetTypeInfo são aqueles com suporte pela fonte de dados. Eles devem ser usados em instruções DDL (Data Definition Language). Os drivers podem retornar dados do conjunto de resultados usando tipos de dados diferentes dos tipos retornados por SQLGetTypeInfo. Ao criar o conjunto de resultados para uma função de catálogo, o driver pode usar um tipo de dados que não é compatível com a fonte de dados.
| Nome da coluna | Coluna número |
Tipo de dados | Comentários |
|---|---|---|---|
| TYPE_NAME (ODBC 2.0) | 1 | Varchar não NULL | Nome do tipo de dados dependente da fonte de dados; por exemplo, "CHAR()", "VARCHAR()", "MONEY", "LONG VARBINARY" ou "CHAR ( ) FOR BIT DATA". Os aplicativos devem usar esse nome em instruções CREATE TABLE e ALTER TABLE . |
| DATA_TYPE (ODBC 2.0) | 2 | Smallint não NULL | Tipo de dados SQL. Pode ser um tipo de dados SQL ODBC ou um tipo de dados SQL específico do driver. Para tipos de dados de data e hora ou intervalo, essa coluna retorna o tipo de dados conciso (como SQL_TYPE_TIME ou SQL_INTERVAL_YEAR_TO_MONTH). Para obter uma lista de tipos de dados SQL ODBC válidos, 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. |
| COLUMN_SIZE (ODBC 2.0) | 3 | Inteiro | O tamanho máximo da coluna que o servidor suporta para esse tipo de dados. Para dados numéricos, essa é a precisão máxima. Para dados de cadeia de caracteres, esse é o comprimento em caracteres. Para tipos de dados datetime, esse é o comprimento em caracteres da representação da string (supondo a precisão máxima permitida do componente de segundos fracionários). NULL é retornado para tipos de dados em que o tamanho da coluna não é aplicável. Para tipos de dados de intervalo, esse é o número de caracteres na representação de caracteres do literal de intervalo (conforme definido pela precisão de entrelinha de intervalo; consulte Comprimento do tipo de dados de intervalo no Apêndice D: Tipos de dados). 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. |
| LITERAL_PREFIX (ODBC 2.0) | 4 | Varchar | Caractere ou caracteres usados para prefixar um literal; por exemplo, aspas simples (') para tipos de dados de caracteres ou 0x para tipos de dados binários; NULL é retornado para tipos de dados em que um prefixo literal não é aplicável. |
| LITERAL_SUFFIX (ODBC 2.0) | 5 | Varchar | Caractere ou caracteres usados para encerrar um literal; por exemplo, aspas simples (') para tipos de dados de caracteres; NULL é retornado para tipos de dados em que um sufixo literal não é aplicável. |
| CREATE_PARAMS (ODBC 2.0) | 6 | Varchar | Uma lista de palavras-chave, separadas por vírgulas, correspondentes a cada parâmetro que o aplicativo pode especificar entre parênteses ao usar o nome retornado no campo TYPE_NAME. As palavras-chave na lista podem ser qualquer uma das seguintes: comprimento, precisão ou escala. Eles aparecem na ordem em que a sintaxe exige que sejam usados. Por exemplo, CREATE_PARAMS para DECIMAL seria "precisão, escala"; CREATE_PARAMS para VARCHAR seria igual a "comprimento". NULL será retornado se não houver parâmetros para a definição do tipo de dados; por exemplo, INTEGER. O driver fornece o texto CREATE_PARAMS no idioma do país/região em que é usado. |
| ANULÁVEL (ODBC 2.0) | 7 | Smallint não NULL | Se o tipo de dados aceita um valor NULL: SQL_NO_NULLS se o tipo de dados não aceitar valores NULL. SQL_NULLABLE se o tipo de dados aceita valores NULL. SQL_NULLABLE_UNKNOWN se não se sabe se a coluna aceita valores NULL. |
| CASE_SENSITIVE (ODBC 2.0) | 8 | Smallint não NULL | Se um tipo de dados de caractere diferencia maiúsculas de minúsculas em agrupamentos e comparações: SQL_TRUE se o tipo de dados for um tipo de dados de caractere e diferenciar maiúsculas de minúsculas. SQL_FALSE se o tipo de dados não for um tipo de dados de caractere ou não diferenciar maiúsculas de minúsculas. |
| PESQUISÁVEL (ODBC 2.0) | 9 | Smallint não NULL | Como o tipo de dados é usado em uma cláusula WHERE : SQL_PRED_NONE se a coluna não puder ser usada em uma cláusula WHERE . (É o mesmo que o valor SQL_UNSEARCHABLE no ODBC 2.x.) SQL_PRED_CHAR se a coluna puder ser usada em uma cláusula WHERE, mas apenas com o predicado LIKE. (É o mesmo que o valor SQL_LIKE_ONLY no ODBC 2.x.) SQL_PRED_BASIC se a coluna puder ser usada em uma cláusula WHERE com todos os operadores de comparação, exceto LIKE (comparação, comparação quantificada, BETWEEN, DISTINCT, IN, MATCH e UNIQUE). (Isso é o mesmo que o valor SQL_ALL_EXCEPT_LIKE no ODBC 2.x.) SQL_SEARCHABLE se a coluna pode ser usada em uma cláusula WHERE com qualquer operador de comparação. |
| UNSIGNED_ATTRIBUTE (ODBC 2.0) | 10 | Smallint | Se o tipo de dados não está assinado: SQL_TRUE se o tipo de dados não estiver assinado. SQL_FALSE se o tipo de dados estiver assinado. NULL será retornado se o atributo não for aplicável ao tipo de dados ou se o tipo de dados não for numérico. |
| FIXED_PREC_SCALE (ODBC 2.0) | 11 | Smallint não NULL | Se o tipo de dados tem precisão e escala fixas predefinidas (que são específicas da fonte de dados), como um tipo de dados money: SQL_TRUE se tiver precisão e escala fixas predefinidas. SQL_FALSE se não tiver precisão e escala fixas predefinidas. |
| AUTO_UNIQUE_VALUE (ODBC 2.0) | 12 | Smallint | Se o tipo de dados é incremento automático: SQL_TRUE se o tipo de dados for incrementado automaticamente. SQL_FALSE se o tipo de dados não for incrementado automaticamente. NULL será retornado se o atributo não for aplicável ao tipo de dados ou se o tipo de dados não for numérico. Um aplicativo pode inserir valores em uma coluna com esse atributo, mas normalmente não pode atualizar os valores na coluna. Quando uma inserção é feita em uma coluna de incremento automático, um valor exclusivo é inserido na coluna no momento da inserção. O incremento não é definido, mas é específico da fonte de dados. Um aplicativo não deve presumir que uma coluna de incremento automático começa em um ponto específico ou é incrementada por qualquer valor específico. |
| LOCAL_TYPE_NAME (ODBC 2.0) | 13 | Varchar | Versão localizada do nome do tipo de dados dependente da fonte de dados. NULL será retornado se a fonte de dados não oferecer suporte a um nome localizado. Esse nome destina-se apenas à exibição, como em caixas de diálogo. |
| MINIMUM_SCALE (ODBC 2.0) | 14 | Smallint | A escala mínima do tipo de dados na fonte de dados. Se um tipo de dados tiver uma escala fixa, as colunas MINIMUM_SCALE e MAXIMUM_SCALE conterão esse valor. Por exemplo, uma coluna SQL_TYPE_TIMESTAMP pode ter uma escala fixa para frações de segundo. NULL será retornado onde escala não for aplicável. Para obter mais informações, 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. |
| MAXIMUM_SCALE (ODBC 2.0) | 15 | Smallint | A escala máxima do tipo de dados na fonte de dados. NULL será retornado onde escala não for aplicável. Se a escala máxima não for definida separadamente na fonte de dados, mas for definida como igual à precisão máxima, essa coluna conterá o mesmo valor que a coluna COLUMN_SIZE. Para obter mais informações, 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. |
| SQL_DATA_TYPE (ODBC 3.0) | 16 | Smallint NÃO NULO | O valor do tipo de dados SQL conforme aparece no campo SQL_DESC_TYPE do descritor. Essa coluna é igual à coluna DATA_TYPE, exceto para os tipos de dados de intervalo e data e hora. Para tipos de dados de intervalo e data e hora, o campo SQL_DATA_TYPE no conjunto de resultados retornará SQL_INTERVAL ou SQL_DATETIME e o campo SQL_DATETIME_SUB retornará o subcódigo para o tipo de dados de intervalo ou data e hora específico. (Veja Apêndice D: Tipos de dados.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 17 | Smallint | Quando o valor de SQL_DATA_TYPE é SQL_DATETIME ou SQL_INTERVAL, essa coluna contém o subcódigo datetime/interval. Para tipos de dados diferentes de datetime e interval, esse campo é NULL. Para tipos de dados de intervalo ou data e hora, o campo SQL_DATA_TYPE no conjunto de resultados retornará SQL_INTERVAL ou SQL_DATETIME e o campo SQL_DATETIME_SUB retornará o subcódigo para o tipo de dados de intervalo ou data e hora específico. (Veja Apêndice D: Tipos de dados.) |
| NUM_PREC_RADIX (ODBC 3.0) | 18 | Inteiro | Se o tipo de dados for um tipo numérico aproximado, essa coluna conterá o valor 2 para indicar que COLUMN_SIZE especifica um número de bits. Para tipos numéricos exatos, essa coluna contém o valor 10 para indicar que COLUMN_SIZE especifica um número de dígitos decimais. Caso contrário, esta coluna será NULL. |
| INTERVAL_PRECISION (ODBC 3.0) | 19 | Smallint | Se o tipo de dados for um tipo de dados de intervalo, essa coluna conterá o valor da precisão de entrelinha do intervalo. (Veja Precisão do tipo de dados de intervalo no Apêndice D: Tipos de dados.) Caso contrário, essa coluna será NULL. |
As informações de atributo podem ser aplicadas a tipos de dados ou a colunas específicas em um conjunto de resultados. SQLGetTypeInfo retorna informações sobre atributos associados a tipos de dados; SQLColAttribute retorna informações sobre atributos associados a colunas em um conjunto de resultados.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento de instruções | Função SQLCancel |
| Retornando informações sobre uma coluna em um conjunto de resultados | Função SQLColAttribute |
| Buscando um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Buscando uma única linha ou um bloco de dados em uma direção somente para frente | Função SQLFetch |
| Retornando informações sobre um driver ou fonte de dados | Função SQLGetInfo |