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 input 接続ハンドルを指定します。
SQLCHAR * szSqlStrIn input 入力 SQL ストリングを含むバッファーを指します。
SQLINTEGER cbSqlStrIn input 引数 szSqlStrIn が指しているバッファーの長さ (バイト) を指定します。
SQLCHAR * szSqlStr 出力 変換された出力ストリングのバッファーを指します。
SQLINTEGER cbSqlStrMax input 引数 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 説明 説明
01 0 04 データが切り捨てられました。 引数 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 %s \n", in_stmt);
       printf("Output Statement: \n %s \n", out_stmt);
       printf("Number of Parameter Markers = %ld\n", pcPar);
    }
    rc = SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
/* ... */