Dukungan Jenis Data untuk Peningkatan Tanggal dan Waktu ODBC
Berlaku untuk:
SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)
Topik ini menyediakan informasi tentang jenis ODBC yang mendukung jenis data tanggal dan waktu SQL Server.
Pemetaan Jenis Data dalam Parameter dan Hasil
Selain jenis data ODBC (SQL_TYPE_TIMESTAMP dan SQL_TIMESTAMP), dua jenis data baru ditambahkan di SQL Server Native Client ODBC untuk mengekspos jenis server baru:
SQL_SS_TIME2
SQL_SS_TIMESTAMPOFFSET
Tabel berikut ini memperlihatkan pemetaan tipe server lengkap. Perhatikan bahwa beberapa sel tabel berisi dua entri; dalam kasus ini, yang pertama adalah nilai ODBC 3.0 dan yang kedua adalah nilai ODBC 2.0.
| Tipe data SQL Server | Tipe data SQL | Nilai |
|---|---|---|
| Tanggalwaktu | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
| Waktu smalldatetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
| Tanggal | SQL_TYPE_DATE SQL_DATE |
91 (sql.h) 9 (sqlext.h) |
| Waktu | SQL_SS_TIME2 | -154 (SQLNCLI.h) |
| DatetimeOFFSET | SQL_SS_TIMESTAMPOFFSET | -155 (SQLNCLI.h) |
| Tanggalwaktu2 | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
93 (sql.h) 11 (sqlext.h) |
Tabel berikut mencantumkan struktur terkait dan tipe ODBC C. Karena ODBC tidak mengizinkan driver yang ditentukan jenis C, SQL_C_BINARY digunakan untuk waktu dan datetimeoffset sebagai struktur biner.
| Tipe data SQL | Tata letak memori | Tipe data C default | Nilai (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 dan yang lebih lama) |
0x4000 (sqlncli.h) SQL_BINARY (-2) |
| SQL_SS_TIMESTAMPOFFSET | SQL_SS_TIMESTAMPOFFSET_STRUCT | SQL_C_SS_TIMESTAMPOFFSET SQL_C_BINARY (ODBC 3.5 dan yang lebih lama) |
0x4001 (sqlncli.h) SQL_BINARY (-2) |
Ketika SQL_C_BINARY pengikatan ditentukan, pemeriksaan perataan akan dilakukan dan kesalahan yang dilaporkan untuk perataan yang salah. SQLSTATE untuk kesalahan ini adalah IM016, dengan pesan "Perataan struktur yang salah".
Format Data: String dan Literal
Tabel berikut ini memperlihatkan pemetaan antara jenis data SQL Server, jenis data ODBC, dan literal string ODBC.
| Tipe data SQL Server | Tipe data ODBC | Format string untuk konversi klien |
|---|---|---|
| Tanggalwaktu | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'yyyy-mm-dd hh:mm:ss[.999]' SQL Server mendukung hingga tiga digit kedua pecahan untuk Datetime. |
| Waktu smalldatetime | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'yyyy-mm-dd hh:hh:ss' Jenis data ini memiliki akurasi satu menit. Komponen detik akan menjadi nol pada output dan akan dibulatkan oleh server pada input. |
| Tanggal | SQL_TYPE_DATE SQL_DATE |
'yyyy-mm-dd' |
| Waktu | SQL_SS_TIME2 | 'hh:mm:ss[.9999999]' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit. |
| Tanggalwaktu2 | SQL_TYPE_TIMESTAMP SQL_TIMESTAMP |
'yyyy-mm-dd hh:mm:ss[.9999999]' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit. |
| DatetimeOFFSET | SQL_SS_TIMESTAMPOFFSET | 'yyyy-mm-dd hh:mm:ss[.9999999] +/- hh:mm' Detik pecahan dapat ditentukan secara opsional menggunakan hingga tujuh digit. |
Tidak ada perubahan pada urutan escape ODBC untuk literal tanggal/waktu.
Detik pecahan dalam hasil selalu menggunakan titik (.), bukan titik dua (:).
Nilai string yang dikembalikan ke aplikasi selalu memiliki panjang yang sama untuk kolom tertentu. Komponen tahun, bulan, hari, jam, menit, dan kedua diisi dengan nol di depan ke lebar maksimumnya, dan ada satu spasi antara tanggal dan waktu dalam nilai tanggalwaktu. Ada juga satu spasi antara waktu dan offset zona waktu dalam nilai datetimeoffset. Offset zona waktu selalu didahului oleh tanda; ketika offset adalah nol, tanda ini adalah plus (+). Detik pecahan diisi dengan nol berikutnya jika perlu, hingga presisi yang ditentukan untuk kolom. Untuk kolom tanggalwaktu, ada tiga digit detik pecahan. Untuk kolom smalldatetime, tidak ada digit detik pecahan, dan detik akan selalu nol.
String kosong bukan harfiah tanggal/waktu yang valid dan tidak mewakili nilai NULL. Upaya untuk mengonversi string kosong menjadi nilai tanggal/waktu akan mengakibatkan kesalahan SQLState 22018 dan pesan "Nilai karakter tidak valid untuk spesifikasi cast".
Konversi dari parameter string akan mengharapkan string dalam format yang sama, dengan pengecualian bahwa tanda zona waktu dengan nol jam dan nol menit dapat berupa plus atau minus, dan nol berikutnya diizinkan untuk detik pecahan hingga maksimum 9 digit. Komponen waktu dapat berakhir dengan titik desimal dan tidak ada digit detik pecahan.
Saat ini, driver memungkinkan ruang kosong tambahan di sekitar karakter tanda baca dan ruang antara offset waktu dan zona waktu bersifat opsional. Namun, ini mungkin berubah dalam rilis mendatang; aplikasi tidak boleh mengandalkan perilaku saat ini.
Format Data: Struktur Data
Dalam struktur yang dijelaskan di bawah ini, ODBC menentukan batasan berikut, yang 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.
Rentang detik adalah 0 hingga 61,9(n). Ini memungkinkan hingga dua detik lompatan untuk mempertahankan sinkronisasi dengan waktu sampingan.
Perhatikan bahwa SQL Server tidak mengizinkan detik lompatan, sehingga nilai kedua yang lebih besar dari 59 akan menyebabkan kesalahan server.
Implementasi untuk struktur ODBC yang ada berikut telah dimodifikasi untuk mendukung jenis data tanggal dan waktu SQL Server baru. Definisinya, bagaimanapun, tidak berubah.
DATE_STRUCT
TIME_STRUCT
TIMESTAMP_STRUCT
Ada juga dua struktur baru:
SQL_SS_TIME2_STRUCT
SQL_SS_TIMESTAMPOFFSET_STRUCT
SQL_SS_TIME2_STRUCT
Struktur ini diisi hingga 12 byte pada sistem operasi 32-bit dan 64-bit.
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;
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 mungkin memiliki nilai apa pun dalam rentang -59 hingga +59.
Lihat Juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk