SQLGetFunctions() - 関数を取得する

SQLGetFunctions() は、特定の関数がサポートされているかどうかを示します。

SQLGetFunctions() により、さまざまなデータベース・サーバーに接続する場合に、アプリケーションを異なるサポート・レベルに適応させることができます。 SQLGetFunctions() を呼び出す前に、データベース・サーバーへ接続されている状態にしておく必要があります。

SQLGetFunctions() の ODBC 仕様

表 1. SQLGetFunctions() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLGetFunctions  (SQLHDBC           hdbc,
                              SQLUSMALLINT      fFunction,
                              SQLUSMALLINT FAR  *pfExists);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetFunctions() の引数
データ・タイプ 引数 使用法 説明
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 に定義されています。

表 3. SQLGetFunctions() 関数および値
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 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLGetFunctions() の 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);
}