Поддержка типов данных для улучшений функций даты и времени ODBC

Статья
01/10/2024

Применимо к:SQL Server Azure SQL DatabaseAzure Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

В этом разделе содержатся сведения о типах ODBC, поддерживающих типы данных даты и времени SQL Server.

Сопоставление типов данных в параметрах и результирующих наборах

Помимо типов данных ODBC (SQL_TYPE_TIMESTAMP и SQL_TIMESTAMP), в ODBC собственного клиента SQL Server были добавлены два новых типа данных, чтобы предоставить новые типы серверов:

SQL_SS_TIME2
SQL_SS_TIMESTAMPOFFSET

В следующей таблице показано полное сопоставление серверных типов данных. Обратите внимание, что некоторые ячейки таблицы содержат по две записи. В таких случаях первая запись — это значение ODBC 3.0, а вторая — значение ODBC 2.0.

Тип данных SQL Server	Тип данных SQL	значение
Дата и время	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	93 (sql.h) 11 (sqlext.h)
Smalldatetime	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	93 (sql.h) 11 (sqlext.h)
Дата	SQL_TYPE_DATE SQL_DATE	91 (sql.h) 9 (sqlext.h)
Time	SQL_SS_TIME2	-154 (SQLNCLI.h)
DatetimeOFFSET	SQL_SS_TIMESTAMPOFFSET	-155 (SQLNCLI.h)
Дата и время2	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	93 (sql.h) 11 (sqlext.h)

В следующей таблице приведены соответствующие структуры и типы ODBC C. Поскольку ODBC не поддерживает типы C, определяемые драйвером, для представления данных time и datetimeoffset в виде двоичных структур используется тип SQL_C_BINARY.

Тип данных SQL	Организация памяти	Тип данных C по умолчанию	Значение (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 и ранее)	0x4000 (sqlncli.h) SQL_BINARY (-2)
SQL_SS_TIMESTAMPOFFSET	SQL_SS_TIMESTAMPOFFSET_STRUCT	SQL_C_SS_TIMESTAMPOFFSET SQL_C_BINARY (ODBC 3.5 и ранее)	0x4001 (sqlncli.h) SQL_BINARY (-2)

Если определена привязка SQL_C_BINARY, будет выполнена проверка выравнивания, и в случае неверного выравнивания будет выдана ошибка. Код SQLSTATE для этой ошибки равен IM016 с сообщением «Неверное выравнивание структуры».

Форматы данных: строки и литералы

В следующей таблице показаны сопоставления между типами данных SQL Server, типами данных ODBC и строковыми литералами ODBC.

Тип данных SQL Server	Тип данных ODBC	Формат строки для клиентских преобразований
Дата и время	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	'гггг-мм-дд чч:мм:сс:[.999]' SQL Server поддерживает до трех дробных секундных цифр для Datetime.
Smalldatetime	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	'yyyy-mm-dd hh:hh:ss' Точность этого типа данных составляет одну минуту. При выводе данных секунды будут равны нулю, а при вводе данных они округляются сервером.
Дата	SQL_TYPE_DATE SQL_DATE	'гггг-мм-дд'
Time	SQL_SS_TIME2	'чч:мм:сс[.9999999]' Дополнительно можно указывать доли секунд до семи цифр.
Дата и время2	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	'гггг-мм-дд чч:мм:сс[.9999999]' Дополнительно можно указывать доли секунд до семи цифр.
DatetimeOFFSET	SQL_SS_TIMESTAMPOFFSET	'yyyy-mm-dd hh:mm:ss[.9999999] +/- hh:mm' Дополнительно можно указывать доли секунд до семи цифр.

В escape-последовательностях ODBC для литералов даты и времени изменений нет.

Для обозначения долей секунды в результатах всегда используется точка (.), а не двоеточие (:).

Возвращаемые приложениям строковые значения всегда имеют одинаковую длину для заданного столбца. Компонентам года, месяца, дня, часов, минут и секунд предшествуют ведущие нули для достижения максимальной длины, а в значениях datetime между датой и временем присутствует один пробел. Также один пробел имеется между временем и сдвигом часового пояса в значении datetimeoffset. Перед сдвигом часового пояса всегда стоит знак. Если сдвиг равен нулю, ставится плюс (+). Доли секунды при необходимости дополняются замыкающими нулями до заданной точности столбца. В столбцах datetime для долей секунды предусмотрены три цифры. В столбцах smalldatetime значение секунд всегда равно нулю, а цифр для долей секунд не предусмотрено.

Пустая строка не является допустимым литералом даты-времени, она не представляет значение NULL. Попытка преобразования пустой строки в значение даты-времени приведет к возникновению ошибки SQLState 22018 с сообщением «Недопустимое символьное значение для приведения».

При преобразовании из строки параметры ожидаются в том же формате. Однако, если часы и минуты, представляющие часовой пояс, равны нулю, то перед элементом может стоять как плюс, так и минус, а для долей секунд разрешено использовать замыкающие нули, дополняющие значение до 9 цифр. Время может завершаться десятичной запятой без указания цифр долей секунды.

В настоящее время драйвер допускает использование дополнительного пробела вокруг знаков препинания, а пробел между временем и часовым поясом является необязательным. Однако, в следующих выпусках это может быть изменено. Приложениям не следует полагаться на текущее поведение драйвера.

Форматы данных: структуры данных

В описанных ниже структурах ODBC определяет следующие ограничения, накладываемые григорианским календарем.

Диапазон месяцев — от 1 до 12 включительно.
Диапазон поля даты — от 1 до количества дней в месяце включительно, он должен быть согласован с полями года и месяца с учетом високосного года.
Диапазон часов — от 0 до 23 включительно.
Диапазон минут — от 0 до 59 включительно.
Диапазон секунд — от 0 до 61.9(...). Это позволяет использовать до двух корректировочных секунд для синхронизации со звездным временем.

Обратите внимание, что SQL Server не разрешает високосные секунды, поэтому второе значение больше 59 приведет к ошибке сервера.

Реализации для следующих существующих структур ODBC были изменены для поддержки новых типов данных даты и времени SQL Server. При этом определения не изменились.

DATE_STRUCT;
TIME_STRUCT;
TIMESTAMP_STRUCT;

Также добавлены две новых структуры.

SQL_SS_TIME2_STRUCT
SQL_SS_TIMESTAMPOFFSET_STRUCT

SQL_SS_TIME2_STRUCT

Эта структура дополняется до 12 байт как в 32-разрядных, так и в 64-разрядных операционных системах.

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;

Если timezone_hour является отрицательным, timezone_minute должен быть отрицательным или нулевым. Если timezone_hour положительный, timezone_minute должен быть положительным или нулевым. Если timezone_hour равно нулю, timezone_minute может иметь любое значение в диапазоне –59–59.

См. также

Улучшения функций даты и времени (ODBC)

Share via