Dukungan Jenis Data Klien Asli SQL Server untuk Peningkatan Tanggal dan Waktu OLE DB

Artikel
01/10/2024

Berlaku untuk:SQL Server Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics Analytics Platform System (PDW)

Topik ini menyediakan informasi tentang jenis OLE DB (SQL Server Native Client) yang mendukung jenis data tanggal/waktu SQL Server.

Pemetaan Jenis Data di Kumpulan Baris dan Parameter

OLE DB menyediakan dua jenis data baru untuk mendukung jenis server baru: DBTYPE_DBTIME2 dan DBTYPE_DBTIMESTAMPOFFSET. Tabel berikut ini memperlihatkan pemetaan tipe server lengkap:

Tipe data SQL Server	Jenis data OLE DB	Nilai
datetime	DBTYPE_DBTIMESTAMP	135 (oledb.h)
smalldatetime	DBTYPE_DBTIMESTAMP	135 (oledb.h)
date	DBTYPE_DBDATE	133 (oledb.h)
waktu	DBTYPE_DBTIME2	145 (sqlncli.h)
tanggalwaktulewat	DBTYPE_DBTIMESTAMPOFFSET	146 (sqlncli.h)
tanggalwaktu2	DBTYPE_DBTIMESTAMP	135 (oledb.h)

Format Data: String dan Literal

Tipe data SQL Server	Jenis data OLE DB	Format string untuk konversi klien
datetime	DBTYPE_DBTIMESTAMP	'yyyy-mm-dd hh:mm:ss[.999]' SQL Server mendukung hingga tiga digit kedua pecahan untuk Datetime.
smalldatetime	DBTYPE_DBTIMESTAMP	'yyyy-mm-dd hh:mm:ss' Jenis data ini memiliki akurasi satu menit. Komponen detik akan menjadi nol pada output dan akan dibulatkan oleh server pada input.
date	DBTYPE_DBDATE	'yyyy-mm-dd'
waktu	DBTYPE_DBTIME2	'hh:mm:ss[.9999999]' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit.
tanggalwaktu2	DBTYPE_DBTIMESTAMP	'yyyyy-mm-dd hh:mm:ss[.fffffff]' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit.
tanggalwaktulewat	DBTYPE_DBTIMESTAMPOFFSET	'yyyy-mm-dd hh:mm:ss[.fffffff] +/-hh:mm' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit.

Tidak ada perubahan pada urutan escape untuk literal tanggal/waktu.

Detik pecahan dalam hasil menggunakan titik (.) daripada titik dua (:).

Nilai string yang dikembalikan ke aplikasi akan selalu memiliki panjang yang sama untuk kolom tertentu. Komponen tahun, bulan, hari, jam, menit, dan kedua akan diisi dengan nol di depan ke lebar maksimumnya. Akan ada tepat satu spasi antara tanggal dan waktu dan tepat satu spasi antara waktu dan offset zona waktu. Offset zona waktu akan selalu didahului oleh tanda. Tanda ini akan menjadi plus (+) ketika offset adalah nol. Tidak akan ada spasi kosong antara tanda dan nilai offset. Detik pecahan akan diisi dengan nol berikutnya, jika perlu, hingga presisi yang ditentukan untuk kolom, tetapi tidak lebih lanjut. Untuk kolom tanggalwaktu, akan ada tiga digit detik pecahan. Untuk kolom smalldatetime, tidak akan ada digit detik pecahan dan detik akan selalu nol.

Konversi dari nilai string yang disediakan oleh aplikasi akan lebih fleksibel dan akan memungkinkan nilai komponen kurang dari lebar maksimum. Tahun bisa 1-4 digit. Bulan, hari, jam, menit, dan detik bisa 1 atau 2 digit. Mungkin ada spasi putih arbitrer antara offset tanggal/waktu dan waktu/zona waktu. Tanda offset dengan nol jam dan nol menit dapat ditambah atau dikurangi. Nol berikutnya diperbolehkan untuk detik pecahan hingga maksimum 9 digit. Komponen waktu dapat berakhir dengan titik desimal dan tidak ada digit detik pecahan.

String kosong bukan harfiah tanggal/waktu yang valid dan tidak mewakili nilai NULL. Upaya untuk mengonversi string kosong ke nilai tanggal/waktu akan mengakibatkan kesalahan dengan SQLState 22018 dan pesan "Nilai karakter tidak valid untuk spesifikasi cast".

Format Data: Struktur Data

Dalam struktur khusus OLE DB yang dijelaskan di bawah ini, OLE DB sesuai dengan batasan yang sama dengan ODBC. Ini diambil dari kalender Gregorian:

Rentang bulan adalah 1 hingga 12.
Rentang bidang hari adalah 1 hingga jumlah hari dalam sebulan, dan harus konsisten dengan bidang tahun dan bulan, dengan mempertimbangkan tahun kampung.
Rentang jam adalah 0 hingga 23.
Rentang menit adalah 0 hingga 59.
Detik berkisar antara 0 hingga 59. Ini memungkinkan hingga dua detik lompatan untuk mempertahankan sinkronisasi dengan waktu sampingan.

Implementasi untuk struktur OLE DB yang ada berikut telah dimodifikasi untuk mendukung jenis data tanggal dan waktu SQL Server baru. Definisinya, bagaimanapun, tidak berubah.

DBTYPE_DATE (Ini adalah jenis TANGGAL otomatisasi. Ini secara internal direpresentasikan sebagai ganda. Seluruh bagian adalah jumlah hari sejak 30 Desember 1899 dan bagian pecahan adalah pecahan sehari. Jenis ini memiliki akurasi 1 detik, sehingga memiliki skala efektif 0.)
DBTYPE_DBDATE
DBTYPE_DBTIME
DBTYPE_DBTIMESTAMP (bidang pecahan didefinisikan oleh OLE DB sebagai jumlah miliaran detik (nanodetik) dan berkisar antara 0-999.999.999)
DBTYPE_FILETIME

DBTYPE_DBTIME2

Struktur ini diisi hingga 12 byte pada sistem operasi 32-bit dan 64-bit.

typedef struct tagDBTIME2 {  
    USHORT hour;  
    USHORT minute;  
    USHORT second;  
    ULONG fraction;  
    } DBTIME2;

DBTYPE_ DBTIMESTAMPOFFSET

typedef struct tagDBTIMESTAMPOFFSET {  
    SHORT year;  
    USHORT month;  
    USHORT day;  
    USHORT hour;  
    USHORT minute;  
    USHORT second;  
    ULONG fraction;  
    SHORT timezone_hour;  
    SHORT timezone_minute;  
    } DBTIMESTAMPOFFSET;

Jika timezone_hour negatif, timezone_minute harus negatif atau nol. Jika timezone_hour positif, timezone minute harus positif atau nol. Jika timezone_hour nol, timezone minute dapat menahan nilai antara -59 dan +59.

SSVARIANT

Struktur ini sekarang mencakup struktur baru, DBTYPE_DBTIME2 dan DBTYPE_DBTIMESTAMPOFFSET, dan menambahkan skala detik pecahan untuk jenis yang sesuai.

struct SSVARIANT {  
   SSVARTYPE vt;  
   DWORD dwReserved1;  
   DWORD dwReserved2;  
   union {  
// ...  
      DBTIMESTAMP tsDateTimeVal;  
      DBDATE dDateVal;  
      struct _Time2Val {  
         DBTIME2 tTime2Val;  
         BYTE bScale;  
      } Time2Val;  
      struct _DateTimeVal {  
         DBTIMESTAMP tsDateTimeVal;  
         BYTE bScale;  
      } DateTimeVal;  
      struct _DateTimeOffsetVal {   
         DBTIMESTAMPOFFSET tsoDateTimeOffsetVal;  
         BYTE bScale;  
      } DateTimeOffsetVal;  
// ...  
   };  
};

Selain itu, enum yang terkait dengan pengodean jenis SSVARIANT, yang menentukan jenis enum, akan diperpanjang sebagai berikut:

enum SQLVARENUM {  
// ...  
   // Datetime  
   VT_SS_DATETIME      = DBTYPE_DBTIMESTAMP,  
   VT_SS_SMALLDATETIME = 206,  
  
   VT_SS_DATE = DBTYPE_DBDATE,  
   VT_SS_TIME2 = DBTYPE_DBTIME2,  
   VT_SS_DATETIME2 = 212  
   VT_SS_DATETIMEOFFSET = DBTYPE_DBTIMESTAMPOFFSET  
};

Aplikasi yang bermigrasi ke SQL Server Native Client yang menggunakan sql_variant dan mengandalkan presisi terbatas tanggalwaktu harus diperbarui jika skema yang mendasarinya diperbarui untuk menggunakan datetime2 daripada tanggalwaktu.

Makro akses untuk SSVARIANT juga telah diperluas dengan penambahan berikut:

#define V_SS_DATETIME2(X)       V_SS_UNION(X, DateTimeVal)  
#define V_SS_TIME2(X)           V_SS_UNION(X, Time2Val)  
#define V_SS_DATE(X)            V_SS_UNION(X, dDateVal)  
#define V_SS_DATETIMEOFFSET(X)  V_SS_UNION(X, DateTimeOffsetVal)

Pemetaan Tipe Data di ITableDefinition::CreateTable

Pemetaan jenis berikut digunakan dengan struktur DBCOLUMNDESC yang digunakan oleh ITableDefinition::CreateTable:

Tipe data OLE DB (wType)	Tipe data SQL Server	Catatan
DBTYPE_DBDATE	date
DBTYPE_DBTIMESTAMP	datetime2(p)	Penyedia SQL Server Native Client OLE DB memeriksa anggota bScale DBCOLUMDESC untuk menentukan presisi detik pecahan.
DBTYPE_DBTIME2	time(p)	Penyedia SQL Server Native Client OLE DB memeriksa anggota bScale DBCOLUMDESC untuk menentukan presisi detik pecahan.
DBTYPE_DBTIMESTAMPOFFSET	datetimeoffset(p)	Penyedia SQL Server Native Client OLE DB memeriksa anggota bScale DBCOLUMDESC untuk menentukan presisi detik pecahan.

Ketika aplikasi menentukan DBTYPE_DBTIMESTAMP dalam wType, aplikasi dapat mengambil alih pemetaan ke datetime2 dengan menyediakan nama jenis di pwszTypeName. Jika tanggalwaktu ditentukan, bScale harus 3. Jika smalldatetime ditentukan, bScale harus 0. Jika bScale tidak konsisten dengan wType dan pwszTypeName, DB_E_BADSCALE dikembalikan.

Lihat Juga

Peningkatan Tanggal dan Waktu (OLE DB)

Bagikan melalui