SQLNativeSql() - ネイティブの SQL テキストを取得する

SQLNativeSql() は Db2® ODBC がベンダー・エスケープ文節を解釈する方法を示します。アプリケーションが渡す元の SQL ストリングにベンダー・エスケープ文節のシーケンスが入っている場合、Db2 ODBC は変換した SQL ストリングをデータ・ソースに渡します。この SQL ストリングは、 変換あるいは破棄されたベンダー・エスケープ文節を使用して渡されます。

SQLNativeSql() の ODBC 仕様

表 1. SQLNativeSql() の仕様
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);

関数の引数

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

表 2. SQLNativeSql() の引数
データ・タイプ 引数 使用法 説明
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 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLNativeSql() の 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 が戻されます。
  • 引数 szSqlStrIn は NULL ポインターです。
  • 引数 szSqlStr は NULL ポインターです。
HY090 ストリングまたはバッファーの長さが無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 引数 cbSqlStrIn に指定された値は 0 より小さく、SQL_NTS と等しくありません。
  • 引数 cbSqlStrMax は 0 より小さい値を指定しています。

例

以下の例は、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);
/* ... */