CLI の手引きおよび解説書

SQLGetDescField - 記述子レコードの単一フィールド設定を入手する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

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

構文

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

関数引き数

表 98. SQLGetDescField 引き数
データ・タイプ 引き数 使用法 説明
SQLHDESC DescriptorHandle 入力 記述子ハンドル。
SQLSMALLINT RecNumber 入力 アプリケーションが情報を求める記述子レコードを指定します。記述子レコードは 0 から数え、レコード番号 0 がブックマーク・レコードになります。 FieldIdentifier 引き数が記述子ヘッダー・レコードのフィールドを指定する場合、 RecNumber は 0 でなければなりません。 RecNumber が SQL_DESC_COUNT より小さく、行に列またはパラメーターのデータが含まれない場合、 SQLGetDescField() の呼び出しはフィールドの省略時値を返します。詳しくは、『記述子フィールドの初期設定』SQLSetDescField() を参照してください。
SQLSMALLINT FieldIdentifier 入力 値を返す記述子のフィールドを指定します。詳しくは、『FieldIdentifier 引き数』SQLSetDescField() を参照してください。
SQLPOINTER ValuePtr 出力 記述子情報を返す先のバッファーを指すポインターです。データ・タイプは、FieldIdentifier の値により異なります。
SQLINTEGER BufferLength 入力
  • ValuePtr が文字ストリングを指す場合、この引き数の長さは *ValuePtr になります。
  • ValuePtr がポインターであるが、ストリングではない場合、 BufferLength の値は SQL_IS_POINTER になります。
  • ValuePtr がポインターではない場合、 BufferLength の値は SQL_IS_NOT_POINTER になります。
  • *ValuePtr の値が Unicode データ・タイプである場合、 BufferLength 引き数は偶数でなければなりません。

SQLSMALLINT *StringLengthPtr 出力 *ValuePtr 内に戻すために使用できる総バイト数 (ヌル終了文字に必要なバイト数を除く) を指すポインター。

使用法

アプリケーションは、SQLGetDescField() を呼び出して、記述子レコードの単一フィールドの値を返すことができます。 SQLGetDescField() への呼び出しでは、ヘッダー・フィールド、レコード・フィールド、およびブックマーク・フィールドを含むすべての記述子タイプのどのフィールドの設定でも返すことができます。 SQLGetDescField() を繰り返し呼び出すなら、アプリケーションは同じ記述子または異なる記述子にある複数のフィールドの設定を、任意の順序で獲得することができます。 SQLGetDescField() を呼び出して DB2 CLI 定義済み記述子フィールドを返すこともできます。

パフォーマンス上の理由で、ステートメントを実行する前にアプリケーションは IRD の SQLGetDescField() を呼び出すことはできません。

名前、データ・タイプ、および列またはパラメーター・データの記憶域を記述できる複数のフィールドの設定を、 SQLGetDescRec() への単一呼び出しで検索することもできます。 SQLGetStmtAttr() を呼び出して、記述子ヘッダー (ステートメント属性でもある) にある単一のフィールドの設定を返すことができます。

特定の記述子タイプが未定義になっているフィールドの値を検索するためにアプリケーションが SQLGetDescField() を呼び出すとき、この関数は SQLSTATE HY091 (無効な記述子フィールド識別子) を返します。特定の記述子タイプ用に定義済みフィールドの値を検索するためにアプリケーションが SQLGetDescField() を呼び出したものの、省略時値がなく、まだ設定されていないときには、この関数は SQL_SUCCESS を返しますがフィールドに返される値は未定義です。詳しくは、『記述子フィールドの初期設定』SQLSetDescField() を参照してください。

SQL_DESC_ALLOC_TYPE ヘッダー・フィールドは、読み取り専用として使用可能です。このフィールドは、すべてのタイプの記述子に定義されます。

以下のレコード・フィールドは、読み取り専用として使用可能です。これらのフィールドそれぞれは、IRD 専用か、または IRD と IPD の両方のどちらかに定義されます。

SQL_DESC_AUTO_UNIQUE_VALUE    SQL_DESC_LITERAL_SUFFIX
SQL_DESC_BASE_COLUMN_NAME     SQL_DESC_LOCAL_TYPE_NAME
SQL_DESC_CASE_SENSITIVE       SQL_DESC_SCHEMA_NAME
SQL_DESC_CATALOG_NAME         SQL_DESC_SEARCHABLE
SQL_DESC_DISPLAY_SIZE         SQL_DESC_TABLE_NAME
SQL_DESC_FIXED_PREC_SCALE     SQL_DESC_TYPE_NAME
SQL_DESC_LABEL                SQL_DESC_UNSIGNED
SQL_DESC_LITERAL_PREFIX       SQL_DESC_UPDATABLE

上記のフィールドの説明と、記述子ヘッダーまたはレコードに設定可能なフィールドの説明については、 SQLSetDescField() のセクションを参照してください。記述子の詳細については、記述子の使用を参照してください。

戻りコード

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

DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済み状態にあるが、それと関連するオープン・カーソルがない場合、SQL_NO_DATA が返されます。

診断

表 99. SQLGetDescField SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
HY013 予期しないメモリーのハンドル・エラーが起きました。 HandleType 引き数が SQL_HANDLE_DBC、 SQL_HANDLE_STMT、または SQL_HANDLE_DESC であり、基礎メモリー・オブジェクトにアクセスできない (メモリー不足が原因と考えられる) ため、関数呼び出しを処理できませんでした。
HY021 記述子情報が不整合です。 整合性検査時に検査された記述子情報は、整合性がとれていませんでした。詳細については、『整合性検査』SQLSetDescField() を参照してください。
01004 データが切り捨てられました。 バッファー *ValuePtr には記述子フィールド全体を返すのに十分な大きさがなかったため、フィールドが切り捨てられました。切り捨てられていない記述子フィールドの長さが、StringLengthPtr に返されます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
07009 記述子索引が無効です。 RecNumber 引き数に指定された値は 1 より小さく、 SQL_ATTR_USE_BOOKMARK ステートメント属性は SQL_UB_OFF であり、フィールドはヘッダー・フィールドまたは DB2 CLI 定義済みフィールドではありませんでした。

FieldIdentifier 引き数はレコード・フィールドであり、 RecNumber 引き数は 0 でした。

RecNumber 引き数は 0 より小さく、フィールドはヘッダー・フィールドまたは DB2 CLI 定義済みフィールドではありませんでした。

08S01 通信リンクに障害が起きました。 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY007 関連したステートメントが準備されていません。 DescriptorHandle は IRD と関連付けられており、関連付けられているステートメント・ハンドルが準備済みまたは実行済みの状態にはありません。
HY010 関数の順序エラーです。 DescriptorHandle が関連付けられていた StatementHandle に対して、非同期的に実行されるある関数 (この関数ではない) が呼び出され、この関数が呼び出された時点でまだ実行中でした。

DescriptorHandle に関連する StatementHandle に対して SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が返されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY090 ストリングまたはバッファー長が無効です。 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。
HY091 記述子タイプが範囲外です。 DescriptorHandle には FieldIdentifier が定義されていません。

SQL_DESC_COUNT フィールド内の値よりも大きい値が RecNumber 引き数に指定されました。

制約

なし。

CLI サンプル dbuse.c

(ここで完全サンプル dbuse.c を使用することもできます 。)

/* From the CLI sample DBUSE.C */
/* ... */
    /* bind the file-parameter
    /* see how the header field SQL_DESC_ALLOC_TYPE is set. */
    sqlrc = SQLGetDescField( hIPD,
                             0, /* ignored for header fields */
                             SQL_DESC_ALLOC_TYPE,
                             &descFieldAllocType, /* The result */
                             SQL_IS_SMALLINT,
                             NULL ); /* ignored */
    STMT_HANDLE_CHECK( hstmt, sqlrc); 
    
/* ... */
    /* see how the field SQL_DESC_PARAMETER_TYPE is set. */
    sqlrc = SQLGetDescField( hIPD,
                             1, /* Look at the parameter */
                             SQL_DESC_PARAMETER_TYPE,
                             &descFieldParameterType, /* The result */
                             SQL_IS_SMALLINT,
                             NULL ); /* ignored */
    STMT_HANDLE_CHECK( hstmt, sqlrc);    
    
/* ... */
        /* see how the descriptor record field SQL_DESC_TYPE_NAME is set */
        rc = SQLGetDescField( hIRD,
                              (SQLSMALLINT)colCount, 
                              SQL_DESC_TYPE_NAME, /* record field */ 
                              descFieldTypeName, /* The result */
                              25,
                              NULL ); /* ignored */
        STMT_HANDLE_CHECK( hstmt, sqlrc);
        
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]