Fungsi SQLDataSources
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLDataSources mengembalikan informasi tentang sumber data. Fungsi ini hanya diimplementasikan oleh Driver Manager.
Sintaks
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argumen
EnvironmentHandle
[Input] Penanganan lingkungan.
Arah
[Input] Menentukan sumber data mana yang menampilkan informasi tentang Manajer Driver. Dapat berupa:
SQL_FETCH_NEXT (untuk mengambil nama sumber data berikutnya dalam daftar), SQL_FETCH_FIRST (untuk mengambil dari awal daftar), SQL_FETCH_FIRST_USER (untuk mengambil DSN pengguna pertama), atau SQL_FETCH_FIRST_SYSTEM (untuk mengambil DSN sistem pertama).
Saat Arah diatur ke SQL_FETCH_FIRST, panggilan berikutnya ke SQLDataSources dengan Direction diatur ke SQL_FETCH_NEXT mengembalikan DSN pengguna dan sistem. Saat Arah diatur ke SQL_FETCH_FIRST_USER, semua panggilan berikutnya ke SQLDataSources dengan Direction diatur ke SQL_FETCH_NEXT hanya mengembalikan DSN pengguna. Saat Arah diatur ke SQL_FETCH_FIRST_SYSTEM, semua panggilan berikutnya ke SQLDataSources dengan Direction diatur ke SQL_FETCH_NEXT hanya mengembalikan DSN sistem.
ServerName
[Output] Penunjuk ke buffer untuk mengembalikan nama sumber data.
Jika ServerName NULL, NameLength1Ptr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh ServerName.
BufferLength1
[Input] Panjang buffer *ServerName , dalam karakter; ini tidak perlu lebih panjang dari SQL_MAX_DSN_LENGTH ditambah karakter penghentian null.
NameLength1Ptr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null) yang tersedia untuk dikembalikan di *ServerName. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength1, nama sumber data di *ServerName dipotong menjadi BufferLength1 dikurangi panjang karakter penghentian null.
Deskripsi
[Output] Arahkan ke buffer untuk mengembalikan deskripsi driver yang terkait dengan sumber data. Misalnya, dBASE atau SQL Server.
Jika Deskripsi NULL, NameLength2Ptr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh Deskripsi.
BufferLength2
[Input] Panjang karakter buffer *Deskripsi .
NameLength2Ptr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null) yang tersedia untuk dikembalikan dalam *Deskripsi. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength2, deskripsi driver di *Deskripsi dipotong menjadi BufferLength2 dikurangi panjang karakter penghentian null.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLDataSources 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 SQLDataSources 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 *ServerName tidak cukup besar untuk mengembalikan nama sumber data lengkap. Oleh karena itu, nama itu dipotong. Panjang seluruh nama sumber data dikembalikan dalam *NameLength1Ptr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) (DM) Buffer *Deskripsi tidak cukup besar untuk mengembalikan deskripsi driver lengkap. Oleh karena itu, deskripsi dipotong. Panjang deskripsi sumber data yang tidak terpotong dikembalikan dalam *NameLength2Ptr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| HY000 | Kesalahan umum | (DM) 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. |
| HY103 | Kode pengambilan tidak valid | (DM) Nilai yang ditentukan untuk argumen Arah tidak sama dengan SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM, 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
Karena SQLDataSources diterapkan di Driver Manager, SQLDataSources didukung untuk semua driver terlepas dari kepatuhan standar driver tertentu.
Aplikasi dapat memanggil SQLDataSources beberapa kali untuk mengambil semua nama sumber data. Manajer Driver mengambil informasi ini dari informasi sistem. Ketika tidak ada lagi nama sumber data, Manajer Driver mengembalikan SQL_NO_DATA. Jika SQLDataSources dipanggil dengan SQL_FETCH_NEXT segera setelah kembali SQL_NO_DATA, SQLDataSources akan mengembalikan nama sumber data pertama. Untuk informasi tentang cara aplikasi menggunakan informasi yang dikembalikan oleh SQLDataSources, lihat Memilih Sumber Data atau Driver.
Jika SQL_FETCH_NEXT diteruskan ke SQLDataSources saat pertama kali dipanggil, itu akan mengembalikan nama sumber data pertama.
Driver menentukan bagaimana nama sumber data dipetakan ke sumber data aktual.
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 |
| Menyambungkan ke sumber data menggunakan string koneksi atau kotak dialog | Fungsi SQLDriverConnect |
| Mengembalikan deskripsi dan atribut driver | Fungsi SQLDrivers |