Função SQLGetTypeInfo
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
SQLGetTypeInfo retorna informações sobre tipos de dados compatíveis com a fonte de dados. O driver retorna as informações na forma de um conjunto de resultados do SQL. Os tipos de dados destinam-se ao uso em instruções DDL (Linguagem de Definição de Dados).
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
StatementHandle
[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.
Retornos
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 Identificador 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 a condições de trabalho de implementação, portanto, um valor semelhante foi temporariamente substituído. (Chame SQLGetStmtAttr para determinar o valor temporariamente substituído.) O valor substituto é válido para 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 foi conectado falhou antes da conclusão do processamento da função. |
| 24.000 | Estado de cursor inválido | Um cursor foi aberto no StatementHandle e SQLFetch ou SQLFetchScroll foram chamados. Esse erro será retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e for retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA. Um conjunto de resultados foi aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não foram chamados. |
| 40001 | Falha na 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 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 | 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 com suporte do driver. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o StatementHandle, então 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 a função SQLGetTypeInfo foi chamada. (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) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para o StatementHandle e retornaram 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. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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 | Tempo limite esgotado | O período de tempo limite da consulta expirou antes da fonte de dados retornar 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 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 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, pela proximidade com que 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, seguida por TYPE_NAME, ambas crescentes. Por exemplo, suponha que uma fonte de dados definiu tipos de dados INTEGER e COUNTER, em que COUNTER está incrementando automaticamente e que um tipo de dados definido pelo usuário WHOLENUM também foi definido. Elas seriam retornadas na ordem INTEGER, WHOLENUM e COUNTER, porque WHOLENUM é mapeado de perto para o tipo de dados SQL ODBC SQL_INTEGER, enquanto o tipo de dados de incremento automático, mesmo com suporte da fonte de dados, não é mapeado 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 tiver suporte do 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 renomeada 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 por número de 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 contando 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 serem retornados por SQLGetTypeInfo. Os tipos de dados retornados por SQLGetTypeInfo são aqueles compatíveis com a fonte de dados. Elas destinam-se ao uso em instruções DDL (Linguagem de Definição de Dados). 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 nas 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 datetime ou interval, 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 | Integer | O tamanho máximo da coluna compatível com o servidor 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 de cadeia de caracteres (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 à esquerda do 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, Tamanho 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, uma aspa única (') para tipos de dados de caractere 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, uma aspa única (') para tipos de dados de caractere; 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 elas sejam usadas. Por exemplo, CREATE_PARAMS para DECIMAL seria "precisão, escala"; CREATE_PARAMS para VARCHAR seria igual a "length". NULL será retornado se não houver parâmetros para a definição de tipo de dados; por exemplo, INTEGER. O driver fornece o texto CREATE_PARAMS no idioma do país/região em que ele é usado. |
| NULLABLE (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 aceitar 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 ordenações 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 diferencia 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 . (Isso é 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 somente com o predicado LIKE . (Isso é 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 puder 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 está sendo gerado automaticamente: SQL_TRUE se o tipo de dados estiver sendo gerado automaticamente. SQL_FALSE se o tipo de dados não estiver sendo gerado 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 está definido, mas é específico da fonte de dados. Um aplicativo não deve assumir que uma coluna de incremento automático começa em nenhum ponto específico ou incrementa 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 por segundos fracionários. NULL será retornado onde escala não for aplicável. Para obter mais informações, 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. |
| 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 estiver definida como a mesma que a 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, Tamanho 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 NOT NULL | O valor do tipo de dados SQL como ele aparece no campo SQL_DESC_TYPE do descritor. Essa coluna é igual à coluna DATA_TYPE, exceto para tipos de dados interval e datetime. Para tipos de dados interval e datetime, 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 intervalo específico ou o tipo de dados datetime. (Consulte 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 intervalo, esse campo é NULL. Para tipos de dados interval ou datetime, 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 intervalo específico ou o tipo de dados datetime. (Consulte 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 à esquerda do intervalo. (Consulte Precisão do tipo de dados interval 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 |
|---|---|
| Associar um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento da instrução | 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 de avanço | Função SQLFetch |
| Retornando informações sobre um driver ou fonte de dados | Função SQLGetInfo |
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de