SQLGetFunctions 関数

適合 性
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

Summary
SQLGetFunctions は、ドライバが特定のODBC関数をサポートしているかどうかの情報を返します。 この機能はドライバーマネージャーで実装されています。また、ドライバーにも実装可能です。 もしドライバが SQLGetFunctionsを実装している場合、ドライバマネージャーはそのドライバ内の関数を呼び出します。 そうでなければ、その関数自体を実行します。

構文

  
SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

引数

ConnectionHandle
[入力] 接続ハンドル。

FunctionID
[入力]関心のあるODBC関数を識別する #define の値; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS。 SQL_API_ODBC3_ALL_FUNCTIONS はODBC 3*.x*アプリケーションでODBC 3*.x*およびそれ以前の機能のサポートを判断するために使われます。 SQL_API_ALL_FUNCTIONS はODBC 2*.x*アプリケーションでODBC 2*.x*およびそれ以前の機能のサポートを判断するために使われます。

ODBC関数を識別する #define 値の一覧については、「コメント」の表を参照してください。

サポートされたPtr
[出力] FunctionId が単一のODBC関数を識別した場合、 SupportedPtr は単一のSQLUSMALLINT値を指し示し、指定された関数がドライバーでサポートされている場合はSQL_TRUE、サポートされていない場合はSQL_FALSEを示します。

FunctionIdがSQL_API_ODBC3_ALL_FUNCTIONSの場合、SupportedPtr はSQL_API_ODBC3_ALL_FUNCTIONS_SIZEの要素数を持つSQLSMALLINT配列を示します。 この配列はドライバーマネージャーによって4,000ビットのビットマップとして扱われ、ODBC 3*.x*以前の機能がサポートされているかどうかを判断するために使われます。 関数サポートを決定するためにSQL_FUNC_EXISTSマクロが呼び出されます。 (「コメント」参照)ODBC 3*.x*アプリケーションは、ODBC 3*.x*またはODBC 2*.x*ドライバに対してSQL_API_ODBC3_ALL_FUNCTIONS付きの SQLGetFunctions を呼び出すことができます。

FunctionIdがSQL_API_ALL_FUNCTIONSの場合、SupportedPtr は100要素のSQLUSMALLINT配列を指し示します。 配列はFunctionIdが各ODBC関数を識別するために使用する #define 値でインデックス付けされます。配列の一部要素は未使用で将来の使用のために予約されています。 要素がドライバでサポートされているODBC 2*.x*以前の関数を識別する場合、その要素がSQL_TRUEされます。 ドライバーがサポートしていないODBC関数を識別する場合や、ODBC関数を識別できない場合はSQL_FALSEされます。

*SupportedPtr で返される配列はゼロベースのインデックスを使用しています。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

Diagnostics

SQLGetFunctionsがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、SQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_DBC、HandleをConnectionHandleとして呼び出すことで、関連するSQLSTATE値を取得できます。 以下の表は 、SQLGetFunctions が一般的に返すSQLSTATE値と、それぞれをこの関数の文脈で説明しています。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

SQLGetFunctions は常に SQLGetFunctions、 SQLDataSources、 SQLDrivers がサポートされていることを返します。 これは、これらの機能がドライバーマネージャーで実装されているためです。 ドライバーマネージャーは、UNICODE関数が存在する場合に対応するUnicode関数にANSI関数をマッピングし、ANSI関数が存在する場合はUnicode関数を対応するANSI関数にマッピングします。 アプリケーションがどのように SQLGetFunctionsを使用するかについては、 インターフェース適合レベルをご覧ください。

以下は、ISO 92標準準拠レベルに準拠した関数の有効な FunctionId 値の一覧です。

以下は、Open Group標準準拠レベルに準拠した関数の有効な FunctionID 値の一覧です。

以下は、ODBC標準準拠レベルに準拠した関数の FunctionId の有効な値の一覧です。

[1] ODBC 2*.x*ドライバを扱う場合、 SQLBulkOperations は以下の両方が正しい場合にのみサポート済みとして返されます:ODBC 2*.x*ドライバが SQLSetPosをサポートし、情報タイプSQL_POS_OPERATIONSが設定したSQL_POS_ADDビットを返します。

以下は、ODBC 3.8以降で導入された関数に対する FunctionId の有効な値の一覧です。

[2] SQLCancelHandle は、ドライバーが SQLCancel と SQLCancelHandleの両方をサポートしている場合のみサポートとして返されます。 SQLCancelがサポートされていてSQLCancelHandleがサポートされていない場合でも、アプリケーションは文ハンドルに対してSQLCancelHandleを呼び出すことができます。なぜなら、その文はSQLCancelにマッピングされるためです。

SQL_FUNC_EXISTSマクロ

SQL_FUNC_EXISTS(SupportedPtr, FunctionID)マクロは、 SQLGetFunctions が FunctionId 引数SQL_API_ODBC3_ALL_FUNCTIONSで呼び出された後、ODBC 3*.x*以前の関数のサポートを決定するために使用されます。 アプリケーションはSupportedPtr引数をSQLGetFunctionsで渡したSupportedPtr に設定し、FunctionID引数を関数の #define に設定してSQL_FUNC_EXISTS呼び出しします。 SQL_FUNC_EXISTSは、その関数がサポートされている場合はSQL_TRUE返し、そうでなければSQL_FALSE返します。

コード例

以下の3つの例は、アプリケーションが SQLGetFunctions を使ってドライバが SQLTables、 SQLColumns、 SQLStatisticsをサポートしているかどうかを判定する方法を示しています。 もしドライバーがこれらの機能をサポートしていない場合、アプリケーションはドライバーから切断されます。 最初の例では、各関数に対して SQLGetFunctions を一度呼び出します。

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

2つ目の例では、ODBC 3.xアプリケーションが SQLGetFunctions を呼び出し、 SQLGetFunctions がODBC 3.xおよびそれ以前のすべての関数に関する情報を返す配列を渡します。

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 (retcode == 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);  

3つ目の例は、ODBC 2.xアプリケーションが SQLGetFunctions を呼び出し、100要素からなる配列を渡し、 SQLGetFunctions がODBC 2.x以前のすべての関数に関する情報を返すものです。

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

関連関数

関連するコンテンツ

• ODBC API リファレンス
• ODBC ヘッダー ファイル