SQLDescribeCol - 列の属性セットの戻し

目的

仕様: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLDescribeCol() は、照会によって生成される結果セットに、指定した 列に関する一般的に使用される記述子情報 (列名、タイプ、精度、位取り、 ヌル指定の可否) のセットを戻します。

この関数の呼び出し前に、SQLPrepare() また は SQLExecDirect() を呼び出す必要があります。

この関数は通常、バインディング列関数 (SQLBindCol()) の前に呼び出 され、列をアプリケーション変数にバインディングする前、列の属性を判別します。

構文 

SQLRETURN   SQLDescribeCol   (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLUSMALLINT      ColumnNumber,      /* icol */
                SQLCHAR      *FAR ColumnName,        /* szColName */
                SQLSMALLINT       BufferLength,      /* cbColNameMax */
                SQLSMALLINT  *FAR NameLengthPtr,     /* pcbColName */
                SQLSMALLINT  *FAR DataTypePtr,       /* pfSqlType */
                SQLUINTEGER  *FAR ColumnSizePtr,     /* pcbColDef */
                SQLSMALLINT  *FAR DecimalDigitsPtr,  /* pibScale */
                SQLSMALLINT  *FAR NullablePtr);      /* pfNullable */

関数の引き数

表 38. SQLDescribeCol の引き数

データ・タイプ 引き数 用途 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT ColumnNumber 入力 記述する列番号。列には、1 から始まり、左から右へ順に番号が付けられる。
SQLCHAR * ColumnName 出力 列名バッファーへのポインター。これは、列名を判別できない場合 には NULL に設定される。
SQLSMALLINT BufferLength 入力 ColumnName バッファーのサイズ。
SQLSMALLINT * NameLengthPtr 出力 ColumnName 引き数の値を戻すことができるバイト数。 NameLengthPtr が BufferLength バイト以上の場合、 列名 (ColumnName) の BufferLength - 1 バイトへの切り捨てが行われる。
SQLSMALLINT * DataTypePtr 出力 列のベース SQL データ・タイプ。
SQLUINTEGER * ColumnSizePtr 出力 データベース内に定義された列の精度。
SQLSMALLINT * DecimalDigitsPtr 出力 データベース内に定義された列の位取り (SQL_DECIMAL にのみ適用される)。
SQLSMALLINT * NullablePtr 出力 この列に NULL が許可されるかどうかを示す。 以下のいずれか。

SQL_NO_NULLS

SQL_NULLABLE

使用法

列は番号によって識別され、左から右へ順番に番号が付けられるので、任意の順序で 記述できます。列番号は 1 から始まります。

ポインター引き数のいずれかにヌル・ポインターを指定した場合、DB2 CLI は、 アプリケーションが情報を必要としていないと見なし、何も戻しません。

戻りコード

診断

SQLDescribeCol() が SQL_ERROR または SQL_SUCCESS_WITH_INFO を戻した場合 、SQLError() 関数を呼び出すことによって以下の SQLSTATE を入手できます。

表 39. SQLDescribeCol の SQLSTATE

SQLSTATE 説明 解説
01004 データが切り捨てられた。 引き数 ColumnName に戻された列名が、引き数 BufferLength に 指定した値より長い。引き数 NameLengthPtr に、列名全体の長さが 入っている。(関数は、SQL_SUCCESS_WITH_INFO を戻す。)
07005 ステートメントが結果セットを戻さなかった。 StatementHandle に関連するステートメントが結果セットを戻さなかった。 記述する列がなかった。(最初に SQLNumResultCols() を呼び出して、 結果セット内に行があるかどうかを判別する。)
07009 無効な記述子索引。 ColumnNumber に指定した値が 0 以下である。 引き数 ColumnNumber に指定した値が、結果セット内の列数より大きい。
40003 08S01 通信リンク障害。 関数の完了前に、アプリケーションとデータ・ソース間の通信リンクに障害が生じた。
58004 予期しないシステム障害。 回復不能なシステム・エラー。
HY001 メモリーの割り振りの失敗。 DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを 割り当てることができない。
HY002 無効な列番号。 引き数 ColumnNumber に指定した値が 1 より小さい。 または、引き数 ColumnNumber に指定した値が、結果セット内の列数より大きい。
HY090 無効なストリング長またはバッファー長。 引き数 BufferLength に指定した長さが 1 より小さい。
HY010 関数のシーケンス・エラー。 StatementHandle に対して、SQLPrepare() または SQLExecDirect() が呼び出される前に関数が呼び出された。
HY013 予期しないメモリー処理エラー。 DB2 CLI が、関数の実行または完了のサポートに必要なメモリーに アクセスできない。
HYC00 ドライバーが使用不可である。 列 ColumnNumber の SQL データ・タイプが DB2 CLI によって認識されない。

制約事項

DB2 Everyplace は以下の ODBC 定義のデータ・タイプしかサポートしません。

関連した解説