SQLGetFunctions() - 関数を取得する
SQLGetFunctions() は、特定の関数がサポートされているかどうかを示します。
SQLGetFunctions() により、さまざまなデータベース・サーバーに接続する場合に、アプリケーションを異なるサポート・レベルに適応させることができます。
SQLGetFunctions() を呼び出す前に、データベース・サーバーへ接続されている状態にしておく必要があります。
SQLGetFunctions() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLGetFunctions (SQLHDBC hdbc,
SQLUSMALLINT fFunction,
SQLUSMALLINT FAR *pfExists);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHDBC | hdbc | 入力 | データベース接続ハンドルを指定します。 |
| SQLUSMALLINT | fFunction | 入力 | 照会される関数を指定します。表 3 は、有効な fFunction 値を示しています。 |
| SQLUSMALLINT * | pfExists | 出力 | この関数が SQL_TRUE または SQL_FALSE を戻すバッファーを指します。 照会する関数がサポートされている場合は、SQL_TRUE がバッファーに戻されます。 関数がサポートされていない場合は、SQL_FALSE がバッファーに戻されます。 |
使用法
表 3 は、引数 fFunction の有効な値と、 対応する関数がサポートされているかどうかを示しています。
引数 fFunction が SQL_API_ALL_FUNCTIONS に設定されている場合、 引数 pfExists は 100 エレメントから成る SQLSMALLINT 配列を指している必要があります。 この配列は、引数 fFunction にある値によって索引が付けられており、 多くの関数を識別するために使用されます。 この配列の一部のエレメントは未使用ですが予約済みです。 引数 fFunction によっては、その値の個数が 100 を超えるため、 関数リストを取得するのに配列方式が使用できない場合があります。引数 fFunction の値の個数が 100 以上の場合は、すべて SQLGetFunctions() 呼び出しを明示的に出す必要があります。 fFunction 値の完全セットは sqlcli1.h に定義されています。
| fFunction | Db2® ODBC が戻す値 |
|---|---|
| SQL_API_SQLALLOCCONNECT | SQL_TRUE |
| SQL_API_SQLALLOCENV | SQL_TRUE |
| SQL_API_SQLALLOCHANDLE | SQL_TRUE |
| SQL_API_SQLALLOCSTMT | SQL_TRUE |
| SQL_API_SQLBINDCOL | SQL_TRUE |
| SQL_API_SQLBINDFILETOCOL | SQL_TRUE |
| SQL_API_SQLBINDFILETOPARAM | SQL_TRUE |
| SQL_API_SQLBINDPARAMETER | SQL_TRUE |
| SQL_API_SQLBROWSECONNECT | SQL_FALSE |
| SQL_API_SQLBULKOPERATIONS | SQL_TRUE |
| SQL_API_SQLCANCEL | SQL_TRUE |
| SQL_API_SQLCLOSECURSOR | SQL_TRUE |
| SQL_API_SQLCOLATTRIBUTE | SQL_TRUE |
| SQL_API_SQLCOLATTRIBUTES | SQL_TRUE |
| SQL_API_SQLCOLUMNPRIVILEGES | SQL_TRUE |
| SQL_API_SQLCOLUMNS | SQL_TRUE |
| SQL_API_SQLCONNECT | SQL_TRUE |
| SQL_API_SQLDATASOURCES | SQL_TRUE |
| SQL_API_SQLDESCRIBECOL | SQL_TRUE |
| SQL_API_SQLDESCRIBEPARAM | SQL_TRUE |
| SQL_API_SQLDISCONNECT | SQL_TRUE |
| SQL_API_SQLDRIVERCONNECT | SQL_TRUE |
| SQL_API_SQLENDTRAN | SQL_TRUE |
| SQL_API_SQLERROR | SQL_TRUE |
| SQL_API_SQLEXECDIRECT | SQL_TRUE |
| SQL_API_SQLEXECUTE | SQL_TRUE |
| SQL_API_SQLEXTENDEDFETCH | SQL_TRUE |
| SQL_API_SQLFETCH | SQL_TRUE |
| SQL_API_SQLFETCHSCROLL | SQL_TRUE |
| SQL_API_SQLFOREIGNKEYS | SQL_TRUE |
| SQL_API_SQLFREECONNECT | SQL_TRUE |
| SQL_API_SQLFREEENV | SQL_TRUE |
| SQL_API_SQLFREEHANDLE | SQL_TRUE |
| SQL_API_SQLFREESTMT | SQL_TRUE |
| SQL_API_SQLGETCONNECTATTR | SQL_TRUE |
| SQL_API_SQLGETCONNECTOPTION | SQL_TRUE |
| SQL_API_SQLGETCURSORNAME | SQL_TRUE |
| SQL_API_SQLGETDATA | SQL_TRUE |
| SQL_API_SQLGETDIAGREC | SQL_TRUE |
| SQL_API_SQLGETENVATTR | SQL_TRUE |
| SQL_API_SQLGETFUNCTIONS | SQL_TRUE |
| SQL_API_SQLGETINFO | SQL_TRUE |
| SQL_API_SQLGETLENGTH | SQL_TRUE |
| SQL_API_SQLGETPOSITION | SQL_TRUE |
| SQL_API_SQLGETSQLCA | SQL_TRUE |
| SQL_API_SQLGETSTMTATTR | SQL_TRUE |
| SQL_API_SQLGETSTMTOPTION | SQL_TRUE |
| SQL_API_SQLGETSUBSTRING | SQL_TRUE |
| SQL_API_SQLGETTYPEINFO | SQL_TRUE |
| SQL_API_SQLMORERESULTS | SQL_TRUE |
| SQL_API_SQLNATIVESQL | SQL_TRUE |
| SQL_API_SQLNUMPARAMS | SQL_TRUE |
| SQL_API_SQLNUMRESULTCOLS | SQL_TRUE |
| SQL_API_SQLPARAMDATA | SQL_TRUE |
| SQL_API_SQLPARAMOPTIONS | SQL_TRUE |
| SQL_API_SQLPREPARE | SQL_TRUE |
| SQL_API_SQLPRIMARYKEYS | SQL_TRUE |
| SQL_API_SQLPROCEDURECOLUMNS | SQL_TRUE |
| SQL_API_SQLPROCEDURES | SQL_TRUE |
| SQL_API_SQLPUTDATA | SQL_TRUE |
| SQL_API_SQLROWCOUNT | SQL_TRUE |
| SQL_API_SQLSETCOLATTRIBUTES | SQL_TRUE |
| SQL_API_SQLSETCONNECTATTR | SQL_TRUE |
| SQL_API_SQLSETCONNECTION | SQL_TRUE |
| SQL_API_SQLSETCONNECTOPTION | SQL_TRUE |
| SQL_API_SQLSETCURSORNAME | SQL_TRUE |
| SQL_API_SQLSETENVATTR | SQL_TRUE |
| SQL_API_SQLSETPARAM | SQL_TRUE |
| SQL_API_SQLSETPOS | SQL_TRUE |
| SQL_API_SQLSETSCROLLOPTIONS | SQL_FALSE |
| SQL_API_SQLSETSTMTATTR | SQL_TRUE |
| SQL_API_SQLSETSTMTOPTION | SQL_TRUE |
| SQL_API_SQLSPECIALCOLUMNS | SQL_TRUE |
| SQL_API_SQLSTATISTICS | SQL_TRUE |
| SQL_API_SQLTABLEPRIVILEGES | SQL_TRUE |
| SQL_API_SQLTABLES | SQL_TRUE |
| SQL_API_SQLTRANSACT | SQL_TRUE |
戻りコード
SQLGetFunctions() は、呼び出された後、次のいずれかの値を戻します。
- SQL_SUCCESS
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | 引数 pfExists は NULL ポインターを指定します。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | SQLGetFunctions() は、データベース接続が確立される前に、呼び出されました。 |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
例
以下の例
は、データベース・サーバーに
接続し、SQLGetFunctions() を使用して、API サポートをチェックするアプリケーションを示しています。
図 1. データベース・サーバーの API サポートをチェックするアプリケーション
/******************************************************************/
/* Execute SQLGetFunctions to verify that APIs required */
/* by application are supported. */
/******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
typedef struct odbc_api
{
SQLUSMALLINT api;
char api_name _40];
} ODBC_API;
/******************************************************************/
/* CLI APIs required by application */
/******************************************************************/
ODBC_API o_api [7] = {
{ SQL_API_SQLBINDPARAMETER, "SQLBindParameter" } ,
{ SQL_API_SQLDISCONNECT , "SQLDisconnect" } ,
{ SQL_API_SQLGETTYPEINFO , "SQLGetTypeInfo" } ,
{ SQL_API_SQLFETCH , "SQLFetch" } ,
{ SQL_API_SQLTRANSACT , "SQLTransact" } ,
{ SQL_API_SQLBINDCOL , "SQLBindCol" } ,
{ SQL_API_SQLEXECDIRECT , "SQLExecDirect" }
} ;
/******************************************************************/
/* Validate that required APIs are supported. */
/******************************************************************/
int main( )
{
SQLHENV hEnv = SQL_NULL_HENV;
SQLHDBC hDbc = SQL_NULL_HDBC;
SQLRETURN rc = SQL_SUCCESS;
SQLINTEGER RETCODE = 0;
int i;
// SQLGetFunctions parameters
SQLUSMALLINT fExists = SQL_TRUE;
SQLUSMALLINT *pfExists = &fExists;
(void) printf ("**** Entering CLIP05.¥n¥n");
/*****************************************************************/
/* Allocate environment handle */
/*****************************************************************/
RETCODE = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Allocate connection handle to DSN */
/*****************************************************************/
RETCODE = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
if( RETCODE != SQL_SUCCESS ) // Could not get a connect handle
goto dberror;
/*****************************************************************/
/* CONNECT TO data source (STLEC1) */
/*****************************************************************/
RETCODE = SQLConnect(hDbc, // Connect handle
(SQLCHAR *) "STLEC1", // DSN
SQL_NTS, // DSN is nul-terminated
NULL, // Null UID
0 ,
NULL, // Null Auth string
0);
if( RETCODE != SQL_SUCCESS ) // Connect failed
goto dberror;
/*****************************************************************/
/* See if DSN supports required ODBC APIs */
/*****************************************************************/
for (i = 0, (*pfExists = SQL_TRUE);
(i < (sizeof(o_api)/sizeof(ODBC_API)) && (*pfExists) == SQL_TRUE);
i++)
{
RETCODE = SQLGetFunctions (hDbc,
o_api[i].api,
pfExists);
if (*pfExists == SQL_TRUE) // if api is supported then print
{
(void) printf ("**** ODBC api %s IS supported.¥n",
o_api[i].api_name);
}
}
if (*pfExists == SQL_FALSE) // a required api is not supported
{
(void) printf ("**** ODBC api %s not supported.¥n",
o_api[i].api_name);
}
/*****************************************************************/
/* DISCONNECT from data source */
/*****************************************************************/
RETCODE = SQLDisconnect(hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Deallocate connection handle */
/*****************************************************************/
RETCODE = SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Free environment handle */
/*****************************************************************/
RETCODE = SQLFreeHandle(SQL_HANDLE_ENV, hEnv);
if (RETCODE == SQL_SUCCESS)
goto exit;
dberror:
RETCODE=12;
exit:
(void) printf("¥n¥n**** Exiting CLIP05.¥n¥n ");
return(RETCODE);
}