Bagikan melalui


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);  
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

Lihat Juga

Referensi API ODBC
File Header ODBC