ODBC 日期和時間改善的資料類型支援

發行項
01/10/2024

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)

本主題提供支援 SQL Server 日期和時間資料類型之 ODBC 類型的相關資訊。

參數和結果集中的資料類型對應

除了 ODBC 資料類型（SQL_TYPE_TIMESTAMP 和 SQL_TIMESTAMP），SQL Server Native Client ODBC 中新增了兩個新的資料類型，以公開新的伺服器類型：

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）
Date	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）
Datetime2	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	93 （sql.h） 11 （sqlext.h）

下表列出對應的結構和 ODBC C 類型。因為 ODBC 不允許驅動程式定義的 C 型別，SQL_C_BINARY用於時間和 datetimeoffset 做為二進位結構。

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	'yyyy-mm-dd hh:mm:ss[.999]' 針對 Datetime，SQL Server 最多支援三個毫秒位數。
Smalldatetime	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	'yyyy-mm-dd hh：hh：ss' 此資料類型的精確度為 1 分鐘。輸出時，秒數元件為零，而在輸入時，將會由伺服器捨去。
Date	SQL_TYPE_DATE SQL_DATE	'yyyy-mm-dd'
Time	SQL_SS_TIME2	'hh:mm:ss[.9999999]' 您最多可以使用七位數選擇性地指定小數秒。
Datetime2	SQL_TYPE_TIMESTAMP SQL_TIMESTAMP	'yyyy-mm-dd hh：mm：ss[.9999999]' 您最多可以使用七位數選擇性地指定小數秒。
DatetimeOFFSET	SQL_SS_TIMESTAMPOFFSET	'yyyy-mm-dd hh：mm：ss[.9999999] +/- hh：mm' 您最多可以使用七位數選擇性地指定小數秒。

日期/時間常值沒有 ODBC 逸出序列的變更。

結果中的小數秒一律使用點（.），而不是冒號（:)。

傳回給應用程式的字串值一律是指定資料行的相同長度。 Year、month、day、hour、minute 和 second 元件會填補前置零到其最大寬度，而且日期時間值中的日期和時間之間有一個空格。 datetimeoffset 值中時間與時區位移之間也有一個空格。時區位移一律在符號前面;當位移為零時，此正負號為加號（+）。如有必要，小數秒會以尾端零填補，最多會填補資料行定義的有效位數。對於 datetime 資料行，有三個小數秒位數。對於 Smalldatetime 資料行，沒有小數秒的數位，而秒一律為零。

空字串不是有效的日期/時間常值，而且它不代表 NULL 值。嘗試將空字串轉換成日期/時間值會導致 SQLState 22018 錯誤和訊息「轉換規格的字元值無效」。

字串參數的轉換會預期字串的格式相同，但例外狀況是，具有零小時和零分鐘之時區的正負號可以是加號或減號，而尾端零則最多允許 9 位數的小數秒。時間元件可以利用一個小數點 (沒有小數秒位數) 結束。

目前，驅動程式允許在標點符號字元周圍加上額外的空白字元，以及時間與時區位移之間的空間是選擇性的。不過，這可能會在未來版本中變更;應用程式不應該依賴目前的行為。

資料格式：資料結構

在以下所述的結構中，ODBC 會指定下列條件約束，這些條件約束取自西曆：

月份的範圍由 1 至 12。
日期欄位範圍為 1 至該月份的天數，而且如果是潤年，則必須與年和月欄位一致。
小時的範圍由 0 至 23。
分鐘的範圍由 0 至 59。
秒數範圍為 0 到 61.9（n）。這可讓最多兩個潤秒與恆星時間保持同步。

請注意，SQL Server 不允許閏秒，因此大於 59 的第二個值會造成伺服器錯誤。

已修改下列現有 ODBC 結構的實作，以支援新的 SQL Server 日期和時間資料類型。不過，定義尚未變更。

DATE_STRUCT
TIME_STRUCT
TIMESTAMP_STRUCT

另外還有兩個新的結構：

SQL_SS_TIME2_STRUCT
SQL_SS_TIMESTAMPOFFSET_STRUCT

SQL_SS_TIME2_STRUCT

此結構在 32 位元和 64 位元作業系統上會填補到 12 個位元組。

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）