SQLGetDescField 関数

適合 性
導入バージョン:ODBC 3.0 規格準拠:ISO 92

Summary
SQLGetDescField は、記述子レコードの単一のフィールドの現在の設定または値を返します。

構文

  
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が返されます。

SQL_NO_DATAは、 DescriptorHandle がIRDハンドルで文が準備または実行状態にあるが、開いているカーソルがない場合に返されます。

Diagnostics

SQLGetDescFieldがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、SQLGetDiagRecを呼び出してHandleTypeをSQL_HANDLE_STMT、HandleをStatementHandleで呼び出すことで関連するSQLSTATE値を取得できます。 以下の表は 、SQLGetDescField によって一般的に返されるSQLSTATE値を一覧にし、この関数の文脈でそれぞれを説明します。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

アプリケーションは SQLGetDescField を呼び出して、ディスクリプタレコードの単一のフィールドの値を返すことができます。 SQLGetDescFieldを呼び出しることで、ヘッダーフィールド、レコードフィールド、ブックマークフィールドを含む任意のディスクリプタタイプのフィールドの設定を返すことができます。 アプリケーションは、同じまたは異なるディスクリプタの複数のフィールドの設定を、任意の順序で SQLGetDescFieldに繰り返し呼び出しすることで取得できます。 SQLGetDescField は、ドライバー定義のディスクリプタフィールドを返すためにも呼び出すことができます。

パフォーマンスの理由から、アプリケーションは文を実行する前にIRDのために SQLGetDescField を呼び出すべきではありません。

名前、データ型、カラムやパラメータデータの保存を記述する複数のフィールドの設定も、 SQLGetDescRecへの1回の呼び出しで取得できます。 SQLGetStmtAttr は、ディスクリプタヘッダー内の単一のフィールド設定を返すために呼び出せます。これは文属性でもあります。 SQLColAttribute、 SQLDescribeCol、 SQLDescribeParam はレコードまたはブックマークフィールドを返します。

アプリケーションが特定のディスクリプタタイプに対して未定義のフィールドの値を取得するために SQLGetDescField を呼び出すと、関数はSQL_SUCCESSを返しますが、そのフィールドの値は未定義です。 例えば、APDやARDのSQL_DESC_NAMEまたはSQL_DESC_NULLABLEフィールドに対して SQLGetDescField を呼び出すと、そのフィールドの値はSQL_SUCCESS返されますが、その値は定義されていません。

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

関連関数

関連するコンテンツ

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