Suporte a tipos de dados para aprimoramentos de data e hora do ODBC
Aplica-se a:
SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)
Este tópico fornece informações sobre tipos ODBC que dão suporte SQL Server tipos de dados de data e hora.
Mapeamento de tipo de dados em parâmetros e conjuntos de resultados
Além dos tipos de dados ODBC (SQL_TYPE_TIMESTAMP e SQL_TIMESTAMP), dois novos tipos de dados foram adicionados no SQL Server Native Client ODBC para expor os novos tipos de servidor:
SQL_SS_TIME2
SQL_SS_TIMESTAMPOFFSET
A tabela seguinte mostra o mapeamento completo de tipo do servidor. Observe que algumas células da tabela contêm duas entradas; nestes casos, a primeira é o valor ODBC 3.0 e a segunda é o valor ODBC 2.0.
| Tipo de dados do SQL Server | Tipo de dados SQL | Valor |
|---|---|---|
| Datetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
| Smalldatetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
| Data | SQL_TYPE_DATE SQL_DATE |
91 (sql.h) 9 (sqlext.h) |
| Hora | SQL_SS_TIME2 | -154 (SQLNCLI.h) |
| DatetimeOFFSET | SQL_SS_TIMESTAMPOFFSET | -155 (SQLNCLI.h) |
| Datetime2 | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
A tabela seguinte lista as estruturas correspondentes e os tipos ODBC C. Como o ODBC não permite tipos C definidos pelo driver, SQL_C_BINARY é usado para time e datetimeoffset como estruturas binárias.
| Tipo de dados SQL | Layout de memória | Tipo de dados C padrão | Valor (sqlext.h) |
|---|---|---|---|
| SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
SQL_TIMESTAMP_STRUCT TIMESTAMP_STRUCT |
SQL_C_TYPE_TIMESTAMP SQL_C_TIMESTAMP |
SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
| SQL_TYPE_DATE SQL_DATE |
SQL_DATE_STRUCT DATE_STRUCT |
SQL_C_TYPE_DATE SQL_C_DATE |
SQL_TYPE_DATE SQL_DATE |
| SQL_SS_TIME2 | SQL_SS_TIME2_STRUCT | SQL_C_SS_TIME2 SQL_C_BINARY (ODBC 3.5 e anterior) |
0x4000 (sqlncli.h) SQL_BINARY (-2) |
| SQL_SS_TIMESTAMPOFFSET | SQL_SS_TIMESTAMPOFFSET_STRUCT | SQL_C_SS_TIMESTAMPOFFSET SQL_C_BINARY (ODBC 3.5 e anterior) |
0x4001 (sqlncli.h) SQL_BINARY (-2) |
Quando a associação SQL_C_BINARY é especificada, a verificação do alinhamento será executada e um erro relatado para alinhamento incorreto. O SQLSTATE para esse erro será IM016, com a mensagem "Alinhamento de estrutura incorreto".
Formatos de dados: cadeias e literais
A tabela a seguir mostra os mapeamentos entre SQL Server tipos de dados, tipos de dados ODBC e literais de cadeia de caracteres ODBC.
| Tipo de dados do SQL Server | Tipo de dados ODBC | Formato de cadeia de caracteres para conversões do cliente |
|---|---|---|
| Datetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'aaaa-mm-dd hh:mm:ss[.999]' O SQL Server oferece suporte a até três dígitos de fração de segundo para Datetime. |
| Smalldatetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'aaaa-mm-dd hh:hh:ss' Este tipo de dados tem precisão de um minuto. O componente de segundos será zero na saída, sendo arredondado pelo servidor na entrada. |
| Data | SQL_TYPE_DATE SQL_DATE |
'aaaa-mm-dd' |
| Hora | SQL_SS_TIME2 | 'hh:mm:ss[.9999999]' Opcionalmente, podem ser especificadas frações de segundo usando até sete dígitos. |
| Datetime2 | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'yyyy-mm-dd hh:mm:ss[.9999999]' Opcionalmente, podem ser especificadas frações de segundo usando até sete dígitos. |
| DatetimeOFFSET | SQL_SS_TIMESTAMPOFFSET | 'aaaa-mm-dd hh:mm:ss[.9999999] +/- hh:mm' Opcionalmente, podem ser especificadas frações de segundo usando até sete dígitos. |
Não há nenhuma alteração às sequências de escape de ODBC para literais de data/hora.
As frações de segundo nos resultados sempre usam um ponto (.), em vez de dois-pontos (:).
Valores da cadeia de caracteres retornados aos aplicativos têm sempre o mesmo comprimento para uma determinada coluna. Componentes de ano, mês, dia, hora, minuto e segundo são preenchidos com zeros à esquerda até sua largura máxima, e há um espaço entre date e time nos valores de datetime. Também há um espaço entre o deslocamento de time e timezone em um valor de datetimeoffset. Um deslocamento de timezone sempre é precedido por um sinal; quando o deslocamento é zero, este sinal é de mais (+). As frações de segundos são preenchidas com zeros à direita, se necessário, até a precisão definida para a coluna. Para colunas do tipo datetime, há três dígitos para frações de segundo. Para colunas do tipo smalldatetime, não há nenhum dígito de fração de segundo e os segundos sempre serão zero.
Uma cadeia de caracteres vazia não é um literal de data/hora válido e não representa um valor NULL. Uma tentativa de conversão de uma cadeia de caracteres vazia para um valor de data/hora resultará em erro SQLState 22018 e a mensagem "Valor de caractere inválido para a especificação de difusão".
As conversões de parâmetros de cadeia de caracteres esperarão caracteres no mesmo formato, com exceções de que o sinal de um fuso horário com zero horas e zero minutos podem ser mais ou menos, e zeros à direita são permitidos para frações de segundos com, no máximo, nove dígitos. Um componente de hora pode terminar com um ponto decimal e não ter dígitos de fração de segundo.
Atualmente, o driver permite espaço em branco adicional ao redor de caracteres de pontuação e o espaço entre deslocamento de time e timezone é opcional. Porém, isto pode ser alterado em uma versão futura; aplicativos não devem confiar no comportamento atual.
Formatos de dados: estruturas de dados
Nas estruturas descritas a seguir, ODBC especifica as seguintes restrições, que são obtidas do calendário gregoriano:
O intervalo de meses é de 1 a 12.
O intervalo do campo de dias é de 1 ao número de dias do mês e deve ser coerente com os campos de ano e mês, levando em conta os anos bissextos.
O intervalo de horas é de 0 a 23.
O intervalo de minutos é de 0 a 59.
O intervalo de segundos é 0 por 61,9(n). Isso permite até dois segundos bissextos para manter a sincronização com a hora sideral.
Observe que SQL Server não permite segundos bissextos, portanto, valores de segundo maiores que 59 causarão um erro de servidor.
As implementações para os seguintes structs ODBC existentes foram modificadas para dar suporte aos novos tipos de dados de data e hora SQL Server. Porém, as definições não foram alteradas.
DATE_STRUCT
TIME_STRUCT
TIMESTAMP_STRUCT
Também há duas novas estruturas:
SQL_SS_TIME2_STRUCT
SQL_SS_TIMESTAMPOFFSET_STRUCT
SQL_SS_TIME2_STRUCT
Esse struct é preenchido com até 12 bytes nos sistemas operacionais de 32 e 64 bits.
typedef struct tagSS_TIME2_STRUCT {
SQLUSMALLINT hour;
SQLUSMALLINT minute;
SQLUSMALLINT second;
SQLUINTEGER fraction;
} SQL_SS_TIME2_STRUCT;
SQL_SS_TIMESTAMPOFFSET_STRUCT
typedef struct tagSS_TIMESTAMPOFFSET_STRUCT {
SQLSMALLINT year;
SQLUSMALLINT month;
SQLUSMALLINT day;
SQLUSMALLINT hour;
SQLUSMALLINT minute;
SQLUSMALLINT second;
SQLUINTEGER fraction;
SQLSMALLINT timezone_hour;
SQLSMALLINT timezone_minute;
} SQL_SS_TIMESTAMPOFFSET_STRUCT;
Se o timezone_hour for negativo, o timezone_minute deverá ser negativo ou zero. Se o timezone_hour for positivo, o timezone_minute deverá ser positivo ou zero. Se o timezone_hour for zero, o timezone_minute poderá ter qualquer valor no intervalo -59 a +59.
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