SQLNativeSql() - ネイティブの SQL テキストを取得する
SQLNativeSql() は Db2® ODBC がベンダー・エスケープ文節を解釈する方法を示します。アプリケーションが渡す元の SQL ストリングにベンダー・エスケープ文節のシーケンスが入っている場合、Db2 ODBC は変換した SQL ストリングをデータ・ソースに渡します。この SQL ストリングは、 変換あるいは破棄されたベンダー・エスケープ文節を使用して渡されます。
SQLNativeSql() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | なし | なし |
構文
SQLRETURN SQLNativeSql (SQLHDBC hdbc,
SQLCHAR FAR *szSqlStrIn,
SQLINTEGER cbSqlStrIn,
SQLCHAR FAR *szSqlStr,
SQLINTEGER cbSqlStrMax,
SQLINTEGER FAR *pcbSqlStr);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHDBC | hdbc | 入力 | 接続ハンドルを指定します。 |
| SQLCHAR * | szSqlStrIn | 入力 | 入力 SQL ストリングを含むバッファーを指します。 |
| SQLINTEGER | cbSqlStrIn | 入力 | 引数 szSqlStrIn が指しているバッファーの長さ (バイト) を指定します。 |
| SQLCHAR * | szSqlStr | 出力 | 変換された出力ストリングのバッファーを指します。 |
| SQLINTEGER | cbSqlStrMax | 入力 | 引数 szSqlStr が指しているバッファーのサイズを指定します。 |
| SQLINTEGER * | pcbSqlStr | 出力 | 完全な出力ストリングが必要とする合計バイト数 (NUL 終止符を除く) を戻す バッファーを指します。 このストリングに必要なバイト数が、引数 cbSqlStrMax の値以上の場合 は、出力ストリングが cbSqlStrMax - 1 バイトに切り捨てられます。 |
使用法
この関数は、Db2 ODBC がデータ・ソースに渡す変換済み SQL ストリングを、 検査または表示する場合に呼び出してください。変換 (マッピング) が行われるのは、SQL ステートメントの入力ストリングにベンダー・エスケープ文節シーケンス が含まれている場合のみです。
Db2 ODBC では、ベンダー・エスケープ文節の構文エラーの検出のみが可能です。 その理由は、Db2 ODBC は変換済み SQL ストリングを準備用にデータ・ソースに渡さず、データベース管理システムが検出した構文エラーは、この時点では入力 SQL ストリング用に生成されないからです。(ステートメント を準備用にデータ・ソースに渡さない理由は、 その準備によってトランザクションが開始される可能性があるためです)
戻りコード
SQLNativeSql() は、呼び出された後、次のいずれかの値を戻します。
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 引数 szSqlStr が指しているバッファーが SQL ストリング全体を収容できる 大きさではないため、出力ストリングは切り捨てられます。 引数 pcbSqlStr には、切り捨てられていない SQL ストリング全体の 長さ (バイト) が入っています。(SQLNativeSql() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 08003 | 接続はクローズされています。 | 引数 hdbc は、オープン状態のデータベース接続を参照していません。 |
| 37000 | SQL 構文が無効です。 | 引数 szSqlStrIn が指定する入力 SQL ストリングには、 エスケープ・シーケンスの構文エラーが含まれています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
例
以下の例は、SQLNativeSql() を使用して、ベンダー・エスケープ文節を含む SQL ステートメントの最終バージョンを印刷するアプリケーション
を示しています。
図 1. 変換されたベンダー・エスケープ文節を印刷するアプリケーション
/* ... */
SQLCHAR in_stmt[1024];
SQLCHAR out_stmt[1024];
SQLSMALLINT pcPar;
SQLINTEGER indicator;
/* ... */
/* Prompt for a statement to prepare */
printf("Enter an SQL statement: ¥n");
gets(in_stmt);
/* prepare the statement */
rc = SQLPrepare(hstmt, in_stmt, SQL_NTS);
SQLNumParams(hstmt, &pcPar);
SQLNativeSql(hstmt, in_stmt, SQL_NTS, out_stmt, 1024, &indicator);
if (indicator == SQL_NULL_DATA)
{ printf("Invalid statement¥n"); }
else
{ printf(" Input Statement: ¥n stmt);
printf("Output Statement: ¥n stmt);
printf("Number of Parameter Markers =
}
rc = SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
/* ... */