Fungsi SQLGetFunctions
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLGetFunctions mengembalikan informasi tentang apakah driver mendukung fungsi ODBC tertentu. Fungsi ini diimplementasikan di Driver Manager; itu juga dapat diimplementasikan pada driver. Jika driver menerapkan SQLGetFunctions, Driver Manager memanggil fungsi di driver. Jika tidak, ia menjalankan fungsi itu sendiri.
Sintaks
SQLRETURN SQLGetFunctions(
SQLHDBC ConnectionHandle,
SQLUSMALLINT FunctionId,
SQLUSMALLINT * SupportedPtr);
Argumen
ConnectionHandle
[Input] Handel koneksi.
FunctionId
[Input] Nilai #define yang mengidentifikasi fungsi minat ODBC; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS digunakan oleh aplikasi ODBC 3*.x* untuk menentukan dukungan ODBC 3*.x* dan fungsi sebelumnya. SQL_API_ALL_FUNCTIONS digunakan oleh aplikasi ODBC 2*.x* untuk menentukan dukungan ODBC 2*.x* dan fungsi sebelumnya.
Untuk daftar nilai #define yang mengidentifikasi fungsi ODBC, lihat tabel di "Komentar."
DidukungPtr
[Output] Jika FunctionId mengidentifikasi satu fungsi ODBC, SupportedPtr menunjuk ke satu nilai SQLUSMALLINT yang SQL_TRUE jika fungsi yang ditentukan didukung oleh driver, dan SQL_FALSE jika tidak didukung.
Jika FunctionId SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr menunjuk ke array SQLSMALLINT dengan sejumlah elemen yang sama dengan SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Array ini diperlakukan oleh Driver Manager sebagai bitmap 4.000-bit yang dapat digunakan untuk menentukan apakah fungsi ODBC 3*.x* atau sebelumnya didukung. Makro SQL_FUNC_EXISTS dipanggil untuk menentukan dukungan fungsi. (Lihat "Komentar.") Aplikasi ODBC 3*.x* dapat memanggil SQLGetFunctions dengan SQL_API_ODBC3_ALL_FUNCTIONS terhadap driver ODBC 3*.x* atau ODBC 2*.x*.
Jika FunctionId SQL_API_ALL_FUNCTIONS, SupportedPtr menunjuk ke array SQLUSMALLINT dari 100 elemen. Array diindeks oleh nilai #define yang digunakan oleh FunctionId untuk mengidentifikasi setiap fungsi ODBC; beberapa elemen array tidak digunakan dan dicadangkan untuk digunakan di masa mendatang. Elemen SQL_TRUE jika mengidentifikasi odbc 2*.x* atau fungsi sebelumnya yang didukung oleh driver. Ini SQL_FALSE jika mengidentifikasi fungsi ODBC yang tidak didukung oleh driver atau tidak mengidentifikasi fungsi ODBC.
Array yang dikembalikan dalam *DidukungPtr menggunakan pengindeksan berbasis nol.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLGetFunctions mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DBC dan Handle of ConnectionHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLGetFunctions 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 | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 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 | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY010 | Kesalahan urutan fungsi | (DM) SQLGetFunctions dipanggil sebelum SQLConnect, SQLBrowseConnect, atau SQLDriverConnect. (DM) SQLBrowseConnect dipanggil untuk ConnectionHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum SQLBrowseConnect mengembalikan SQL_SUCCESS_WITH_INFO atau SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk ConnectionHandle 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. |
| HY095 | Tipe fungsi di luar rentang | (DM) Nilai FunctionId yang tidak valid ditentukan. |
| 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. |
| HYT01 | Kesalahan waktu habis koneksi kedaluwarsa | Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
Komentar
SQLGetFunctions selalu mengembalikan bahwa SQLGetFunctions, SQLDataSources, dan SQLDrivers didukung. Ini dilakukan karena fungsi-fungsi ini diimplementasikan di Manajer Driver. Driver Manager akan memetakan fungsi ANSI ke fungsi Unicode yang sesuai jika fungsi Unicode ada dan akan memetakan fungsi Unicode ke fungsi ANSI yang sesuai jika fungsi ANSI ada. Untuk informasi tentang cara aplikasi menggunakan SQLGetFunctions, lihat Tingkat Kesuaian Antarmuka.
Berikut ini adalah daftar nilai yang valid untuk FunctionId untuk fungsi yang sesuai dengan tingkat kepatuhan standar ISO 92:
| Nilai FunctionId | Nilai FunctionId |
|---|---|
| SQL_API_SQLALLOCHANDLE | SQL_API_SQLGETDESCFIELD |
| SQL_API_SQLBINDCOL | SQL_API_SQLGETDESCREC |
| SQL_API_SQLCANCEL | SQL_API_SQLGETDIAGFIELD |
| SQL_API_SQLCLOSECURSOR | SQL_API_SQLGETDIAGREC |
| SQL_API_SQLCOLATTRIBUTE | SQL_API_SQLGETENVATTR |
| SQL_API_SQLCONNECT | SQL_API_SQLGETFUNCTIONS |
| SQL_API_SQLCOPYDESC | SQL_API_SQLGETINFO |
| SQL_API_SQLDATASOURCES | SQL_API_SQLGETSTMTATTR |
| SQL_API_SQLDESCRIBECOL | SQL_API_SQLGETTYPEINFO |
| SQL_API_SQLDISCONNECT | SQL_API_SQLNUMRESULTCOLS |
| SQL_API_SQLDRIVERS | SQL_API_SQLPARAMDATA |
| SQL_API_SQLENDTRAN | SQL_API_SQLPREPARE |
| SQL_API_SQLEXECDIRECT | SQL_API_SQLPUTDATA |
| SQL_API_SQLEXECUTE | SQL_API_SQLROWCOUNT |
| SQL_API_SQLFETCH | SQL_API_SQLSETCONNECTATTR |
| SQL_API_SQLFETCHSCROLL | SQL_API_SQLSETCURSORNAME |
| SQL_API_SQLFREEHANDLE | SQL_API_SQLSETDESCFIELD |
| SQL_API_SQLFREESTMT | SQL_API_SQLSETDESCREC |
| SQL_API_SQLGETCONNECTATTR | SQL_API_SQLSETENVATTR |
| SQL_API_SQLGETCURSORNAME | SQL_API_SQLSETSTMTATTR |
| SQL_API_SQLGETDATA |
Berikut ini adalah daftar nilai yang valid untuk FunctionId untuk fungsi yang sesuai dengan tingkat kepatuhan standar Grup Terbuka:
| Nilai FunctionId | Nilai FunctionId |
|---|---|
| SQL_API_SQLCOLUMNS | SQL_API_SQLSTATISTICS |
| SQL_API_SQLSPECIALCOLUMNS | SQL_API_SQLTABLES |
Berikut ini adalah daftar nilai yang valid untuk FunctionId untuk fungsi yang sesuai dengan tingkat kepatuhan standar ODBC.
| Nilai FunctionId | Nilai FunctionId |
|---|---|
| SQL_API_SQLBINDPARAMETER | SQL_API_SQLNATIVESQL |
| SQL_API_SQLBROWSECONNECT | SQL_API_SQLNUMPARAMS |
| SQL_API_SQLBULKOPERATIONS[1] | SQL_API_SQLPRIMARYKEYS |
| SQL_API_SQLCOLUMNPRIVILEGES | SQL_API_SQLPROCEDURECOLUMNS |
| SQL_API_SQLDESCRIBEPARAM | SQL_API_SQLPROCEDURES |
| SQL_API_SQLDRIVERCONNECT | SQL_API_SQLSETPOS |
| SQL_API_SQLFOREIGNKEYS | SQL_API_SQLTABLEPRIVILEGES |
| SQL_API_SQLMORERESULTS |
[1] Saat bekerja dengan driver ODBC 2*.x*, SQLBulkOperations akan dikembalikan sebagai didukung hanya jika kedua hal berikut ini benar: driver ODBC 2*.x* mendukung SQLSetPos, dan jenis informasi SQL_POS_OPERATIONS mengembalikan bit SQL_POS_ADD sebagaimana ditetapkan.
Berikut ini adalah daftar nilai yang valid untuk FunctionId untuk fungsi yang diperkenalkan dalam ODBC 3.8 atau yang lebih baru:
| Nilai FunctionId |
|---|
| SQL_API_SQLCANCELHANDLE [2] |
[2] SQLCancelHandle akan dikembalikan sebagai didukung hanya jika driver mendukung SQLCancel dan SQLCancelHandle. Jika SQLCancel didukung tetapi SQLCancelHandle tidak, aplikasi masih dapat memanggil SQLCancelHandle pada handel pernyataan, karena akan dipetakan ke SQLCancel.
Makro SQL_FUNC_EXISTS
Makro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) digunakan untuk menentukan dukungan ODBC 3*.x* atau fungsi sebelumnya setelah SQLGetFunctions dipanggil dengan argumen FunctionId SQL_API_ODBC3_ALL_FUNCTIONS. Aplikasi memanggil SQL_FUNC_EXISTS dengan argumen SupportedPtr yang diatur ke SupportedPtr yang diteruskan dalam SQLGetFunctions, dan dengan argumen FunctionID diatur ke #define untuk fungsi tersebut. SQL_FUNC_EXISTS mengembalikan SQL_TRUE jika fungsi didukung, dan SQL_FALSE sebaliknya.
Catatan
Saat bekerja dengan driver ODBC 2*.x*, Driver Manager ODBC 3*.x* akan mengembalikan SQL_TRUE untuk SQLAllocHandle dan SQLFreeHandle karena SQLAllocHandle dipetakan ke SQLAllocEnv, SQLAllocConnect, atau SQLAllocStmt, dan karena SQLFreeHandle dipetakan ke SQLFreeEnv, SQLFreeConnect, atau SQLFreeStmt. SQLAllocHandle atau SQLFreeHandle dengan argumen HandleType SQL_HANDLE_DESC tidak didukung, namun, meskipun SQL_TRUE dikembalikan untuk fungsi, karena tidak ada fungsi ODBC 2*.x* untuk dipetakan dalam kasus ini.
Contoh Kode
Tiga contoh berikut menunjukkan bagaimana aplikasi menggunakan SQLGetFunctions untuk menentukan apakah driver mendukung SQLTables, SQLColumns, dan SQLStatistics. Jika driver tidak mendukung fungsi-fungsi ini, aplikasi akan terputus dari driver. Contoh pertama memanggil SQLGetFunctions sekali untuk setiap fungsi.
SQLUSMALLINT TablesExists, ColumnsExists, StatisticsExists;
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
retcodeTables = SQLGetFunctions(hdbc, SQL_API_SQLTABLES, &TablesExists);
retcodeColumns = SQLGetFunctions(hdbc, SQL_API_SQLCOLUMNS, &ColumnsExists);
retcodeStatistics = SQLGetFunctions(hdbc, SQL_API_SQLSTATISTICS, &StatisticsExists);
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.
if (retcodeTables == SQL_SUCCESS && TablesExists == SQL_TRUE &&
retcodeColumns == SQL_SUCCESS && ColumnsExists == SQL_TRUE &&
retcodeStatistics == SQL_SUCCESS && StatisticsExists == SQL_TRUE)
{
// Continue with application
}
SQLDisconnect(hdbc);
Dalam contoh kedua, aplikasi ODBC 3.x memanggil SQLGetFunctions dan meneruskannya array di mana SQLGetFunctions mengembalikan informasi tentang semua odbc 3.x dan fungsi sebelumnya.
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
SQLUSMALLINT fExists[SQL_API_ODBC3_ALL_FUNCTIONS_SIZE];
retcode = SQLGetFunctions(hdbc, SQL_API_ODBC3_ALL_FUNCTIONS, fExists);
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.
if (reccode == SQL_SUCCESS &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLTABLES) == SQL_TRUE &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLCOLUMNS) == SQL_TRUE &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLSTATISTICS) == SQL_TRUE)
{
// Continue with application
}
SQLDisconnect(hdbc);
Contoh ketiga adalah aplikasi ODBC 2.x memanggil SQLGetFunctions dan meneruskannya array 100 elemen di mana SQLGetFunctions mengembalikan informasi tentang semua ODBC 2.x dan fungsi sebelumnya.
#define FUNCTIONS 100
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
SQLUSMALLINT fExists[FUNCTIONS];
retcode = SQLGetFunctions(hdbc, SQL_API_ALL_FUNCTIONS, fExists);
/* SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver. */
if (retcode == SQL_SUCCESS &&
fExists[SQL_API_SQLTABLES] == SQL_TRUE &&
fExists[SQL_API_SQLCOLUMNS] == SQL_TRUE &&
fExists[SQL_API_SQLSTATISTICS] == SQL_TRUE)
{
/* Continue with application */
}
SQLDisconnect(hdbc);
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengembalikan pengaturan atribut koneksi | Fungsi SQLGetConnectAttr |
| Mengembalikan informasi tentang driver atau sumber data | Fungsi SQLGetInfo |
| Mengembalikan pengaturan atribut pernyataan | Fungsi SQLGetStmtAttr |