Поддержка типов данных для улучшений функций даты и времени ODBC
Применимо: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure 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 | Значение |
---|---|---|
Datetime | 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) |
Время | 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 | Формат строки для клиентских преобразований |
---|---|---|
Datetime | 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 |
'гггг-мм-дд' |
Время | 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.