SQLGetFunctions 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92

まとめ
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 値の一覧については、「コメント」の表を参照してください。

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

FunctionId がSQL_API_ODBC3_ALL_FUNCTIONSの場合、SupportedPtr は、SQL_API_ODBC3_ALL_FUNCTIONS_SIZEと等しい要素の数を持つ SQLSMALLINT 配列を指します。 この配列は、ODBC 3*.x* 以前の関数がサポートされているかどうかを判断するために使用できる 4,000 ビット ビットマップとしてドライバー マネージャーによって扱われます。 関数のサポートを決定するために、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 配列を指します。 配列は、各 ODBC 関数 を 識別するために FunctionId によって使用される#define値によってインデックスが作成されます。配列の一部の要素は未使用であり、将来使用するために予約されています。 ドライバーでサポートされている ODBC 2*.x* 以前の関数を識別する場合、要素はSQL_TRUEされます。 ドライバーでサポートされていない ODBC 関数を識別するか、ODBC 関数を識別しない場合にSQL_FALSEされます。

*SupportedPtr で返される配列は、0 から始まるインデックス作成を使用します。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLGetFunctions がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_DBCの HandleType と ConnectionHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLGetFunctions によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
08S01 通信リンクエラー ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010 関数シーケンス エラー (DM) SQLGetFunctions は、SQLConnect、SQLBrowseConnect、または SQLDriverConnect の前に呼び出されました。

(DM) ConnectionHandle に対して SQLBrowseConnect が呼び出され、SQL_NEED_DATAが返されました。 この関数は、 SQLBrowseConnect がSQL_SUCCESS_WITH_INFOまたはSQL_SUCCESSを返す前に呼び出されました。

(DM) ConnectionHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY095 関数の種類が範囲外 (DM) 無効な FunctionId 値が指定されました。
HY117 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。

説明

SQLGetFunctions は 、 SQLGetFunctions、 SQLDataSources、および SQLDrivers がサポートされていることを常に返します。 これは、これらの関数がドライバー マネージャーに実装されているためです。 ドライバー マネージャーは、Unicode 関数が存在する場合は、対応する Unicode 関数に ANSI 関数をマップし、ANSI 関数が存在する場合は、対応する ANSI 関数に Unicode 関数をマップします。 アプリケーションで SQLGetFunctions を使用する方法については、「 インターフェイス準拠レベル」を参照してください。

ISO 92 標準コンプライアンス レベルに準拠する関数の FunctionId の有効な値の一覧を次に示します。

FunctionId 値 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

Open Group 標準コンプライアンス レベルに準拠する関数の FunctionId の有効な値の一覧を次に示します。

FunctionId 値 FunctionId 値
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

ODBC 標準準拠レベルに準拠する関数の FunctionId の有効な値の一覧を次に示します。

FunctionId 値 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] ODBC 2*.x* ドライバーを使用する場合、 SQLBulkOperations は、次の両方が true の場合にのみサポートとして返されます。ODBC 2*.x* ドライバーは SQLSetPos をサポートし、情報の種類SQL_POS_OPERATIONSはSQL_POS_ADD ビットをセットとして返します。

ODBC 3.8 以降で導入された関数の FunctionId の有効な値の一覧を次に示します。

FunctionId 値
SQL_API_SQLCANCELHANDLE [2]

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

SQL_FUNC_EXISTS マクロ

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

Note

ODBC 2*.x* ドライバーを使用する場合、ODBC 3*.x* Driver Manager は SQLAllocHandle と SQLFreeHandle のSQL_TRUEを返します。SQLAllocHandle は SQLAllocEnv、SQLAllocConnect、または SQLAllocStmt にマップされ、SQLFreeHandle は SQLFreeEnv、SQLFreeConnect、または SQLFreeStmt にマップされるためです。 ただし、SQL_HANDLE_DESCの HandleType 引数を持つ SQLAllocHandle または SQLFreeHandle はサポートされていません。ただし、この場合にマップする ODBC 2*.x* 関数がないため、関数に対してSQL_TRUEが返される場合でもサポートされません。

コード例

次の 3 つの例は、アプリケーションが SQLGetFunctions を使用して、ドライバーが SQLTables、 SQLColumns、および SQLStatistics をサポートしているかどうかを判断する方法を示しています。 ドライバーがこれらの関数をサポートしていない場合、アプリケーションはドライバーから切断されます。 最初の例では、関数ごとに SQLGetFunctions を 1 回呼び出します。

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

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

#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);
対象 解決方法については、
接続属性の設定を返す SQLGetConnectAttr 関数
ドライバーまたはデータ ソースに関する情報を返す SQLGetInfo 関数
ステートメント属性の設定を返す SQLGetStmtAttr 関数

参照

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