Fungsi SQLDrivers
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 2.0: ODBC
Ringkasan
SQLDrivers mencantumkan deskripsi driver dan kata kunci atribut driver. Fungsi ini hanya diimplementasikan oleh Driver Manager.
Sintaks
SQLRETURN SQLDrivers(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * DriverDescription,
SQLSMALLINT BufferLength1,
SQLSMALLINT * DescriptionLengthPtr,
SQLCHAR * DriverAttributes,
SQLSMALLINT BufferLength2,
SQLSMALLINT * AttributesLengthPtr);
Argumen
EnvironmentHandle
[Input] Penanganan lingkungan.
Arah
[Input] Menentukan apakah Manajer Driver mengambil deskripsi driver berikutnya dalam daftar (SQL_FETCH_NEXT) atau apakah pencarian dimulai dari awal daftar (SQL_FETCH_FIRST).
DriverDescription
[Output] Arahkan ke buffer untuk mengembalikan deskripsi driver.
Jika DriverDescription adalah NULL, DescriptionLengthPtr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang diarahkan oleh DriverDescription.
BufferLength1
[Input] Panjang buffer *DriverDescription , dalam karakter.
DescriptionLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null) yang tersedia untuk dikembalikan dalam *DriverDescription. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength1, deskripsi driver di *DriverDescription dipotong menjadi BufferLength1 dikurangi panjang karakter penghentian null.
DriverAttributes
[Output] Arahkan ke buffer untuk mengembalikan daftar pasangan nilai atribut driver (lihat "Komentar").
Jika DriverAttributes adalah NULL, AttributesLengthPtr masih akan mengembalikan jumlah total byte (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh DriverAttributes.
BufferLength2
[Input] Panjang buffer *DriverAttributes , dalam karakter. Jika nilai *DriverDescription adalah string Unicode (saat memanggil SQLDriversW), argumen BufferLength harus berupa angka genap.
AttributesLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total byte (tidak termasuk byte penghentian null) yang tersedia untuk dikembalikan dalam *DriverAttributes. Jika jumlah byte yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength2, daftar pasangan nilai atribut dalam *DriverAttributes dipotong menjadi BufferLength2 dikurangi panjang karakter null-termination.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLDrivers mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_ENV dan Handle of EnvironmentHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLDrivers dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATEs yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.
| SQLSTATE | Kesalahan | Deskripsi |
|---|---|---|
| 01000 | Peringatan umum | (DM) Pesan informasi khusus Manajer Driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 01004 | Data string, terpotong kanan | (DM) Buffer *DriverDescription tidak cukup besar untuk mengembalikan deskripsi driver lengkap. Oleh karena itu, deskripsi dipotong. Panjang deskripsi driver lengkap dikembalikan dalam *DescriptionLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) (DM) Buffer *DriverAttributes tidak cukup besar untuk mengembalikan daftar lengkap pasangan nilai atribut. Oleh karena itu, daftar dipotong. Panjang daftar pasangan nilai atribut yang tidak terpotong dikembalikan dalam *AttributesLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLGetDiagRec di buffer *MessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | (DM) Manajer Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY010 | Kesalahan urutan fungsi | (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY090 | String atau panjang buffer tidak valid | (DM) Nilai yang ditentukan untuk argumen BufferLength1 kurang dari 0. (DM) Nilai yang ditentukan untuk argumen BufferLength2 kurang dari 0 atau sama dengan 1. |
| HY103 | Kode pengambilan tidak valid | (DM) Nilai yang ditentukan untuk argumen Arah tidak sama dengan SQL_FETCH_FIRST atau SQL_FETCH_NEXT. |
| HY117 | Koneksi ditangguhkan karena status transaksi yang tidak diketahui. Hanya fungsi putuskan sambungan dan baca-saja yang diizinkan. | (DM) Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran. |
Komentar
SQLDrivers mengembalikan deskripsi driver di buffer *DriverDescription . Ini mengembalikan informasi tambahan tentang driver di buffer *DriverAttributes sebagai daftar pasangan kata kunci-nilai. Semua kata kunci yang tercantum dalam informasi sistem untuk driver akan dikembalikan untuk semua driver, kecuali untuk CreateDSN, yang digunakan untuk meminta pembuatan sumber data dan oleh karena itu bersifat opsional. Setiap pasangan dihentikan dengan byte null, dan daftar lengkap dihentikan dengan byte null (yaitu, dua byte null menandai akhir daftar). Misalnya, driver berbasis file yang menggunakan sintaks C mungkin mengembalikan daftar atribut berikut ("\0" mewakili karakter null):
FileUsage=1\0FileExtns=*.dbf\0\0
Jika *DriverAttributes tidak cukup besar untuk menyimpan seluruh daftar, daftar dipotong, SQLDrivers mengembalikan SQLSTATE 01004 (Data terpotong), dan panjang daftar (tidak termasuk byte penghentian null akhir) dikembalikan dalam *AttributesLengthPtr.
Kata kunci atribut driver ditambahkan dari informasi sistem ketika driver diinstal. Untuk informasi selengkapnya, lihat Menginstal Komponen ODBC.
Aplikasi dapat memanggil SQLDrivers beberapa kali untuk mengambil semua deskripsi driver. Manajer Driver mengambil informasi ini dari informasi sistem. Ketika tidak ada lagi deskripsi driver, SQLDrivers mengembalikan SQL_NO_DATA. Jika SQLDrivers dipanggil dengan SQL_FETCH_NEXT segera setelah kembali SQL_NO_DATA, SQLDrivers mengembalikan deskripsi driver pertama. Untuk informasi tentang cara aplikasi menggunakan informasi yang dikembalikan oleh SQLDrivers, lihat Memilih Sumber Data atau Driver.
Jika SQL_FETCH_NEXT diteruskan ke SQLDrivers saat pertama kali dipanggil, SQLDrivers mengembalikan nama sumber data pertama.
Karena SQLDrivers diterapkan di Driver Manager, SQLDrivers didukung untuk semua driver terlepas dari kepatuhan standar driver tertentu.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Menemukan dan mencantumkan nilai yang diperlukan untuk menyambungkan ke sumber data | Fungsi SQLBrowseConnect |
| Menyambungkan ke sumber data | Fungsi SQLConnect |
| Mengembalikan nama sumber data | Fungsi SQLDataSources |
| Menyambungkan ke sumber data menggunakan string koneksi atau kotak dialog | Fungsi SQLDriverConnect |