SQLGetDescField 関数

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

まとめ
SQLGetDescField は 、記述子レコードの 1 つのフィールドの現在の設定または値を返します。

構文

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

引数

DescriptorHandle
[入力]記述子ハンドル。

RecNumber
[入力]アプリケーションが情報をシークする記述子レコードを示します。 記述子レコードには 0 から番号が付けられます。レコード番号 0 はブックマーク レコードです。 引数 FieldIdentifier がヘッダー フィールドを示す場合、RecNumber は無視されます。 RecNumber がSQL_DESC_COUNT以下で、行に列またはパラメーターのデータが含まれていない場合、SQLGetDescField を呼び出すとフィールドの既定値が返されます。 (詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください)。

FieldIdentifier
[入力]値が返される記述子のフィールドを示します。 詳細については、「SQLSetDescField」の「FieldIdentifier Argument」セクションを参照してください。

ValuePtr
[出力]記述子情報を返すバッファーへのポインター。 データ型は 、FieldIdentifier の値によって異なります。

ValuePtr が整数型の場合、アプリケーションは SQLULEN のバッファーを使用し、この関数を呼び出す前に値を 0 に初期化する必要があります。これは、一部のドライバーがバッファーの下位 32 ビットまたは 16 ビットのみを書き込み、上位ビットを変更せずに残すことがあるためです。

ValuePtr が NULL の場合でも、StringLengthPtr は、ValuePtr が指すバッファーで返すために使用できるバイトの合計数 (文字データの null 終端文字を除く) を返します。

BufferLength
[入力] FieldIdentifier が ODBC で定義されたフィールドで 、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さである必要があります。 FieldIdentifier が ODBC 定義フィールドで、*ValuePtr が整数の場合、BufferLength は無視されます。 *ValuePtr の値が Unicode データ型の場合 (SQLGetDescFieldW を呼び出すとき)、BufferLength 引数は偶数である必要があります。

FieldIdentifier がドライバー定義フィールドの場合、アプリケーションは BufferLength 引数を設定して、フィールドの性質をドライバー マネージャーに示します。 BufferLength には、次の値を指定できます。

• *ValuePtr が文字列へのポインターである場合、BufferLength は文字列またはSQL_NTSの長さになります。

• *ValuePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に配置します。 これにより 、BufferLength に負の値が配置されます。

• *ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、BufferLength には値SQL_IS_POINTER必要があります。

• *ValuePtr に固定長データ型が含まれている場合、BufferLength はSQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT、またはSQL_IS_USMALLINTのいずれかになります。

StringLengthPtr
[出力]*ValuePtr で返すために使用できる合計バイト数 (null 終了文字に必要なバイト数を除く) を返すバッファーへのポインター。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA、またはSQL_INVALID_HANDLE。

RecNumber が現在の記述子レコード数より大きい場合、SQL_NO_DATAが返されます。

DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済みの状態にあるが、開いているカーソルが関連付けられていない場合は、SQL_NO_DATAが返されます。

診断

SQLGetDescField がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLGetDescField によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。

説明

アプリケーションは SQLGetDescField を呼び出して、記述子レコードの 1 つのフィールドの値を返すことができます。 SQLGetDescField を呼び出すと、ヘッダー フィールド、レコード フィールド、ブックマーク フィールドなど、任意の記述子型の任意のフィールドの設定を返すことができます。 アプリケーションは、 SQLGetDescField を繰り返し呼び出すことで、同じ記述子または異なる記述子内の複数のフィールドの設定を任意の順序で取得できます。 SQLGetDescField を 呼び出して、ドライバー定義の記述子フィールドを返すこともできます。

パフォーマンス上の理由から、アプリケーションはステートメントを実行する前に、IRD に対して SQLGetDescField を呼び出さないでください。

列またはパラメーター データの名前、データ型、ストレージを記述する複数のフィールドの設定は、 SQLGetDescRec の 1 回の呼び出しでも取得できます。 SQLGetStmtAttr を呼び出して、ステートメント属性でもある記述子ヘッダー内の 1 つのフィールドの設定を返すことができます。 SQLColAttribute、 SQLDescribeCol、 および SQLDescribeParam の戻り値レコードまたはブックマーク フィールド。

アプリケーションが SQLGetDescField を呼び出して、特定の記述子型に対して未定義のフィールドの値を取得すると、関数は SQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 たとえば、APD または ARD の SQL_DESC_NAME フィールドまたは SQL_DESC_NULLABLE フィールドに対して SQLGetDescField を呼び出すと、SQL_SUCCESSが返されますが、フィールドの値は未定義になります。

アプリケーションが SQLGetDescField を呼び出して、特定の記述子型に対して定義されているが、既定値がなく、まだ設定されていないフィールドの値を取得すると、関数は SQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 記述子フィールドの初期化とフィールドの説明の詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください。 記述子の詳細については、「 記述子」を参照してください。

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル