16.9.12　SQLGetDiagField，SQLGetDiagFieldW

(1)　機能

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

ページの先頭へ

(2)　形式

• SQLGetDiagFieldの場合

  SQLRETURN SQLGetDiagField
  (
    SQLSMALLINT     HandleType,          /* In */
    SQLHANDLE       Handle,              /* In */
    SQLSMALLINT     RecNumber,           /* In */
    SQLSMALLINT     DiagIdentifier,      /* In */
    SQLPOINTER      DiagInfoPtr,         /* Out */
    SQLSMALLINT     BufferLength,        /* In */
    SQLSMALLINT   * StringLengthPtr      /* Out */
  )

• SQLGetDiagFieldWの場合

  SQLRETURN SQLGetDiagFieldW
  (
    SQLSMALLINT     HandleType,          /* In */
    SQLHANDLE       Handle,              /* In */
    SQLSMALLINT     RecNumber,           /* In */
    SQLSMALLINT     DiagIdentifier,      /* In */
    SQLPOINTER      DiagInfoPtr,         /* Out */
    SQLSMALLINT     BufferLength,        /* In */
    SQLSMALLINT   * StringLengthPtr      /* Out */
  )

ページの先頭へ

(3)　引数

HandleType：

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

• SQL_HANDLE_ENV：環境ハンドル

• SQL_HANDLE_DBC：接続ハンドル

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

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

Handle：

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

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

RecNumber：

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

診断ヘッダフィールドの値を取得する（DiagIdentifierに診断ヘッダフィールドを示す値を設定する）場合，この引数の指定は無視されます。

それ以外の場合，この引数には1以上の値を指定します。

DiagIdentifier：

要求診断フィールド識別子を指定します。大きく分けてヘッダフィールドとレコードフィールドの2種類があります。指定できる属性については，「16.18　SQLGetDiagFieldおよびSQLGetDiagFieldWのDiagIdentifierに指定できる属性」を参照してください。

DiagInfoPtr：

診断情報を返すバッファへのポインタを返します。データ型はDiagIdentifierの値によって異なります。

BufferLength：

DiagInfoPtrの長さを指定します。

この長さにNULL終端文字は含まれます。

DiagInfoPtrの種類によって次の値を指定します。

DiagIdentifierの値の種類	DiagInfoPtrの値の種類	BufferLengthに指定する値
「16.18　SQLGetDiagFieldおよびSQLGetDiagFieldWのDiagIdentifierに指定できる属性」に定義されている値	文字列またはバイナリ	DiagInfoPtrの長さ（単位：バイト長） SQL_NTSは指定できません。
	整数	なし（無視される）

StringLengthPtr：

DiagInfoPtrが文字データの場合だけ使用します。

DiagInfoPtrに返す有効な総バイト長を格納するバッファへのポインタを指定します。この総バイト長にNULL終端文字のバイト長は含みません。

重要

ここに格納されたDiagInfoPtrに設定する文字列の総バイト長が，BufferLengthからNULL終端文字分を引いた長さより大きい場合，DiagInfoPtrに格納される文字列はBufferLengthからNULL終端文字分を引いた長さに切り捨てられ，末尾にNULL終端文字が付加されます。

ページの先頭へ

(4)　戻り値

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

戻り値	意味
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	次のエラーのうちのどちらかが発生しました。 取得値に対してDiagInfoPtrのサイズが小さいため，切り捨てが発生しました。BufferLengthとStringLengthPtrを比較することで，切り捨てられたサイズを知ることができます。 文字コード変換時に変換できない文字コードを検出し，指定の文字に置き換えました。
SQL_ERROR	次のエラーのうちのどれかが発生しました。 DiagIdentifierに不正な値が指定されました。 DiagIdentifierに次のうちのどれかが指定されましたが，Handleがステートメントハンドルではありません。 ・SQL_DIAG_CURSOR_ROW_COUNT ・SQL_DIAG_DYNAMIC_FUNCTION ・SQL_DIAG_DYNAMIC_FUNCTION_CODE ・SQL_DIAG_ROW_COUNT DiagIdentifierに診断レコードフィールドを示す値が指定されましたが，RecNumberに0以下の値が指定されました。 要求フィールドのデータ型種別は文字列ですが，BufferLengthが次のすべての条件を満たしています。 ・0より小さい ・SQL_NTSではない ・SQL_LEN_BINARY_ATTR(length)マクロの結果ではない BufferLengthに無効な値（SQL_NTS）が指定されました。
SQL_INVALID_HANDLE	HandleTypeとHandleによって示されるハンドルが有効なハンドルではありません。
SQL_NO_DATA	RecNumberがHandleで指定されたハンドルに存在する診断レコードの数より大きいか，指定されたHandleに読み出しできる診断レコードがありません。

ページの先頭へ

(5)　SQLSTATE

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

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

ページの先頭へ

(6)　注意事項

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

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

ページの先頭へ