16.9.13　SQLGetDiagRec，SQLGetDiagRecW

(1)　機能

ハンドルに関連づけられているエラー，警告，ステータスなどの情報を含む診断データ構造体のレコードフィールドに現在設定されている値を返します。

ページの先頭へ

(2)　形式

• SQLGetDiagRecの場合

  SQLRETURN SQLGetDiagRec
  (
    SQLSMALLINT     HandleType,        /* In */
    SQLHANDLE       Handle,            /* In */
    SQLSMALLINT     RecNumber,         /* In */
    SQLCHAR       * SQLState,          /* Out */
    SQLINTEGER    * NativeErrorPtr,    /* Out */
    SQLCHAR       * MessageText,       /* Out */
    SQLSMALLINT     BufferLength,      /* In */
    SQLSMALLINT   * TextLengthPtr      /* Out */
  )

• SQLGetDiagRecWの場合

  SQLRETURN SQLGetDiagRecW
  (
    SQLSMALLINT     HandleType,        /* In */
    SQLHANDLE       Handle,            /* In */
    SQLSMALLINT     RecNumber,         /* In */
    SQLWCHAR      * SQLState,          /* Out */
    SQLINTEGER    * NativeErrorPtr,    /* Out */
    SQLWCHAR      * MessageText,       /* Out */
    SQLSMALLINT     BufferLength,      /* In */
    SQLSMALLINT   * TextLengthPtr      /* Out */
  )

ページの先頭へ

(3)　引数

HandleType：

次のどれかのハンドルの種類を指定します。

• SQL_HANDLE_ENV：環境ハンドル

• SQL_HANDLE_DBC：接続ハンドル

• SQL_HANDLE_STMT：ステートメントハンドル

• SQL_HANDLE_DESC：ディスクリプタハンドル

Handle：

ハンドルの値を指定します。

この関数を実行する前にSQLAllocHandleの*OutputHandlePtrで出力された値を指定します。

RecNumber：

アプリケーションが情報を取得する診断情報（ステータスレコード）番号を指定します。

この引数には1以上の値を指定します。

SQLState：

RecNumberが示す診断レコードに関係するSQLSTATEコードを返すバッファへのポインタです。「クラス（2文字）＋サブクラス（3文字）」の5文字で構成されます。

この情報はSQL_DIAG_SQLSTATE診断フィールドに格納されている情報が返されます。

このパラメタにNULLが指定された場合は何も設定しません。

NativeErrorPtr：

データソースに固有のネイティブエラーコードを返すバッファへのポインタです。

この情報はSQL_DIAG_NATIVE診断フィールドに格納されている情報が返されます。

このパラメタにNULLが指定された場合は何も設定しません。

MessageText：

診断メッセージテキスト文字列を返すバッファへのポインタです。

この情報はSQL_DIAG_MESSAGE_TEXT診断フィールドに格納されている情報が返されます。

このパラメタにNULLが指定された場合は何も設定しません。

BufferLength：

MessageTextバッファの長さ^※です。

診断メッセージテキストには最大長の定義はありませんが，必ず512バイト以上の値を指定してください。

この長さにNULL終端文字は含まれます。SQL_NTSは指定できません。

TextLengthPtr：

MessageTextに返す有効な長さ^※の合計を返すバッファへのポインタを指定します。この長さにNULL終端文字は含まれません。

重要

ここに格納された長さ^※が，BufferLengthからNULL終端文字分を引いた長さ^※より大きい場合，MessageTextに格納される文字列はBufferLengthからNULL終端文字分を引いた長さ^※に切り捨てられ，末尾にNULL終端文字が付加されます。

注※

長さの単位は，SQLGetDiagRecの場合はバイト長，SQLGetDiagRecWの場合は文字数となります。

ページの先頭へ

(4)　戻り値

SQL_SUCCESS，SQL_SUCCESS_WITH_INFO，SQL_ERROR，SQL_INVALID_HANDLE，またはSQL_NO_DATAが返されます。この関数ではSQLSTATEを設定しない代わりに，戻り値に次の実行結果を示します。

戻り値	意味
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	次のエラーのうちのどちらかが発生しました。 診断メッセージテキストに対して，MessageTextのサイズが小さいため，切り捨てが発生しました。BufferLengthとTextLengthPtrを比較することで，切り捨てられたサイズを知ることができます。 文字コード変換時に変換できない文字コードを検出し，指定の文字に置き換えました。
SQL_ERROR	次のエラーのどれかが発生しました。 RecNumberに0以下の値が指定されました。 BufferLengthに0より小さい値が指定されました。 BufferLengthに無効な値（SQL_NTS）が指定されました。
SQL_INVALID_HANDLE	HandleTypeとHandleによって示されるハンドルが有効なハンドルではありません。
SQL_NO_DATA	RecNumberがHandleで指定されたハンドルに存在する診断レコードの数より大きいか，指定Handleに読み出しできる診断レコードがありません。

ページの先頭へ

(5)　SQLSTATE

この関数ではSQLSTATEを返しません。

エラーの詳細はすべて「(4)　戻り値」に定義している値で通知します。

ページの先頭へ

(6)　注意事項

• エラーの詳細情報については，「15.4　エラー発生時に返却される情報」を参照してください。

• NativeErrorPtrにはSQLCODEが設定されます。SQLCODEについては，マニュアルHADB　メッセージのSQLCODEの見方を参照してください。

• 診断情報は返しません。

ページの先頭へ