SQLColAttribute() - 列属性を取得する

SQLColAttribute() は、結果セット内の列の記述子情報を戻します。記述子情報は、文字ストリング、32 ビットの記述子従属値、または整数値として戻されます。

SQLColAttribute() の ODBC 仕様

表 1. SQLColAttribute() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

SQLRETURN  SQLColAttribute  (SQLHSTMT         StatementHandle,
                            SQLSMALLINT      ColumnNumber,
                            SQLSMALLINT      FieldIdentifier,
                            SQLPOINTER       CharacterAttributePtr,
                            SQLSMALLINT      BufferLength,
                            SQLSMALLINT      *StringLengthPtr,
                            SQLPOINTER       NumericAttributePtr);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLColAttribute() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT ColumnNumber 入力 記述される列番号。列は、左から右へ、1 から順番に番号が付けられています。ゼロの列は定義されない ことがあります。Db2® ODBC 3.0 ドライバーはブックマークをサポートしません。『制約事項』を参照してください。
SQLSMALLINT FieldIdentifier 入力 戻される ColumnNumber 行のフィールド。表 3を参照してください。
SQLPOINTER CharacterAttributePtr 出力 フィールドが文字ストリングの場合、ColumnNumber 行 の FieldIdentifier フィールド内の値を戻す先のバッファーへのポインター。 それ以外の場合は、このフィールドは無視されます。
SQLSMALLINT BufferLength 入力 フィールドが文字ストリングの場合は、引数 *CharacterAttributePtr に 指定したバッファーの長さ (バイト)。 それ以外の場合は、このフィールドは無視されます。
SQLSMALLINT * StringLengthPtr 出力 *CharacterAttributePtr に戻すことができるバイト数の合計 (文字データの NUL 終了文字を除く) を戻す先のバッファーへのポインター。

文字データの場合、戻すことができるバイト数が BufferLength 値以上の場合 、*CharacterAttributePtr 内の記述子情報は BufferLength から NUL 終了文字の長さ (バイト) を引いたものに切り捨てられます。 その後、Db2 ODBC はその値を NUL 終了します。

他のタイプのデータの場合はすべて、BufferLength の値は無視され 、Db2 ODBC は *CharacterAttributePtr のサイズを 32 ビットと想定します。

SQLPOINTER NumericAttributePtr 出力 ColumnNumber 行の FieldIdentifier フィールド内の値を戻す先の 整数バッファーへのポインター (この FieldIdentifier フィールドが SQL_DESC_LENGTH などの 数値記述子タイプである場合)。 それ以外の場合は、このフィールドは無視されます。

使用法

SQLColAttribute() は、*NumericAttributePtr また は *CharacterAttributePtr のいずれかに情報を戻します。 整数情報は *NumericAttributePtr に 32 ビットの符号付き値として戻され、 他の形式の情報はすべて、*CharacterAttributePtr に戻されます。 情報が *NumericAttributePtr に戻された場合 、Db2 ODBC は CharacterAttributePtr、BufferLength、 および StringLengthPtr を無視します。情報が *CharacterAttributePtr に戻された場合 、Db2 ODBC は NumericAttributePtr を無視します。

SQLColAttribute() によって、ANSI ANSI/ISO SQL 規格 (1992) およびデータベース管理システムのベンダー拡張機能で使用可能な、より広範囲な 記述子情報のセットにアクセスすることができます。SQLColAttribute() は、SQLDescribeCol() 関数よりも 拡張可能な代替となる関数ですが、1 回の呼び出しにつき 1 つの属性しか戻すことができません。

Db2 ODBC はそれぞれの記述子タイプごとに値を戻す必要があります。記述子タイプがデータ・ソースに適用されない場合、特に記されていない限り 、Db2 ODBC は *StringLengthPtr に 0 を戻すか、 または *CharacterAttributePtr に空ストリングを戻します。

次の表では、ODBC 3.0 SQLColAttribute() により戻される記述子タイプについて、置き換えまたは名前変更になった ODBC 2.0 SQLColAttributes() の属性値 (括弧内に記載) とともに 示しています。

表 3. SQLColAttribute() のフィールド ID
フィールド ID 引数に戻される情報 説明
SQL_DESC_AUTO_UNIQUE_VALUE (SQL_COLUMN_AUTO_INCREMENT)1 NumericAttributePtr 列データ・タイプが自動増分タイプであるかどうかを示します。Db2 SQL データ・タイプの場合はすべて 、NumericAttributePtr に SQL_FALSE が戻されます。
SQL_DESC_BASE_COLUMN_NAME CharacterAttributePtr セットになった列の場合、基本の列名。 基本の列名が存在しない場合 (例えば、式である列)、この変数は空ストリングを含みます。
SQL_DESC_BASE_TABLE_NAME CharacterAttributePtr 列を含む基本表の名前。基本表名を定義できない、または該当しない場合、 この変数は空ストリングを含みます。
SQL_DESC_CASE_SENSITIVE (SQL_COLUMN_CASE_SENSITIVE1 NumericAttributePtr 列データ・タイプが大/小文字を区別するかどうかを示します。 データ・タイプにより 、SQL_TRUE または SQL_FALSE が NumericAttributePtr に戻されます。 大/小文字の区別はグラフィック・データ・タイプには適用されません。 SQL_FALSE が、非文字データ・タイプおよび XML データ・タイプに対して戻ります。
SQL_DESC_CATALOG_NAME (SQL_COLUMN_CATALOG_NAME)1 (SQL_COLUMN_QUALIFIER_NAME)1 CharacterAttributePtr 列を含むカタログ表の名前。Db2 ODBC は、表に対して 2 部構成の名前をサポートしているため、 空ストリングが戻されます。
SQL_DESC_CONCISE_TYPE CharacterAttributePtr 簡便データ・タイプ。 日時データ・タイプの場合、このフィールドは 簡便データ・タイプ (SQL_TYPE_TIME など) を戻します。
SQL_DESC_COUNT (SQL_COLUMN_COUNT)1 NumericAttributePtr 結果セット内の列数。
SQL_DESC_DISPLAY_SIZE (SQL_COLUMN_DISPLAY_SIZE)1 NumericAttributePtr 文字形式でデータを表示するのに必要な最大バイト数。
SQL_DESC_DISTINCT_TYPE (SQL_COLUMN_DISTINCT_TYPE)1 CharacterAttributePtr

列で使用される特殊タイプ名。列が組み込み SQL タイプであって特殊タイプではない場合、 空ストリングが戻されます。

IBM® 固有: これは、ODBC が定義した記述子属性のリストに 対する IBM 定義の拡張です。

SQL_DESC_FIXED_PREC_SCALE (SQL_COLUMN_MONEY)1 NumericAttributePtr

列が、データ・ソース特有の固定精度とゼロ以外の位取りの場合は SQL_TRUE。 列が、データ・ソース特有の固定精度とゼロ以外の位取りではない場合は SQL_FALSE。

Db2 SQL データ・タイプの場合はすべて 、NumericAttributePtr に SQL_FALSE が戻されます。

SQL_DESC_LABEL (SQL_COLUMN_LABEL)1 CharacterAttributePtr 列ラベル。列にラベルがない場合は、列名または列式が戻されます。 列にラベルや名前が付いていない場合は、空ストリングが戻されます。
SQL_DESC_LENGTH NumericAttributePtr 文字ストリングまたはバイナリー・データ・タイプの最大長もしくは実際の長さ (バイト) の数値。 固定長データ・タイプの場合は最大長であり、可変長データ・タイプの場合は実際の長さです。 この値では、文字ストリングを終了させる NUL 終了文字は、常に除外されています。 この値は、XML データ・タイプに対しては 0 です。
SQL_DESC_LITERAL_PREFIX CharacterAttributePtr Db2 ODBC がこのデータ・タイプのリテラルの接頭部として認識した文字 (1 つ以上) を 含む VARCHAR(128) レコード・フィールド。このデータ・タイプにリテラル接頭部が該当しない場合、このフィールドは空ストリングを含みます。
SQL_DESC_LITERAL_SUFFIX CharacterAttributePtr Db2 ODBC がこのデータ・タイプのリテラルの接尾部として認識した文字 (1 つ以上) を 含む VARCHAR(128) レコード・フィールド。このデータ・タイプにリテラル接尾部が該当しない場合、このフィールドは空ストリングを含みます。
SQL_DESC_LOCAL_TYPE_NAME CharacterAttributePtr データ・タイプの通常の名前とは異なる場合がある、 ローカライズされた (ネイティブ言語の) 名前を含む VARCHAR(128) レコード・フィールド。 ローカライズされた名前が存在しない場合は、空ストリングが戻されます。 このフィールドは表示専用です。 ストリングの文字セットはロケーションに依存しており、 一般的にはサーバーのデフォルト文字セットです。
SQL_DESC_NAME (SQL_COLUMN_NAME)1 CharacterAttributePtr ColumnNumber で指定された列の名前。列が式である場合、列番号が戻されます。

いずれの場合も、SQL_DESC_UNNAMED は SQL_NAMED に設定されます。 列に名前がないか、別名を持たない場合は、空ストリングが戻され 、SQL_DESC_UNNAMED は SQL_UNNAMED に設定されます。

SQL_DESC_NULLABLE (SQL_COLUMN_NULLABLE)1 NumericAttributePtr ColumnNumber によって示される列が NULL 値を含むことができる場合 は、SQL_NULLABLE が戻されます。列が NULL 値を受け入れることができない場合 は、SQL_NO_NULLS が戻されます。
SQL_DESC_NUM_PREC_RADIX NumericAttributePtr 数値における数字の精度。 一般には、以下の値が戻されます。
  • SQL_DESC_TYPE フィールド内のデータ・タイプが近似データ・タイプの 場合、SQL_DESC_PRECISION フィールドにはビット数値が入るため、 この SQLINTEGER フィールドは 2 という値になります。
  • SQL_DESC_TYPE フィールドのデータ・タイプが厳密な数値データ・タイプの場合 、SQL_DESC_PRECISION フィールドは 10 進数字が入るため、このフィールドは 10 という値になります。
  • 非数値データ・タイプの場合はすべて、このフィールドは 0 に設定されます。
SQL_DESC_OCTET_LENGTH (SQL_COLUMN_LENGTH)1 NumericAttributePtr 列に関連したデータのバイト数。 SQL_C_DEFAULT が C データ・タイプとして指定されている場合、 この列のフェッチまたは SQLGetData() で転送されるデータの長さ (バイト)。

ColumnNumber で示される列が固定長の文字または バイナリー・ストリング (例えば、SQL_CHAR または SQL_BINARY) の場合、実際の長さが戻されます。

ColumnNumber で示される列が可変長の文字または バイナリー・ストリング (例えば、SQL_VARCHAR または SQL_BLOB) の場合、最大長が戻されます。

SQL_DESC_PRECISION (SQL_COLUMN_PRECISION)1 NumericAttributePtr 列が以下の場合、数字単位の精度。
  • SQL_BIGINT
  • SQL_DECIMAL
  • SQL_NUMERIC
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_DECFLOAT
  • SQL_INTEGER
  • SQL_REAL
  • SQL_SMALLINT

列が文字 SQL データ・タイプの場合、戻される精度は、列が保持できる文字の最大数を示します。

列がグラフィック SQL データ・タイプの場合、精度は、列が保持できる 2 バイト文字の最大数 を示します。

列が XML データ・タイプの場合、精度は 0 です。

SQL_DESC_SCALE (SQL_COLUMN_SCALE)1 NumericAttributePtr 列の位取りの属性。
SQL_DESC_SCHEMA_NAME (SQL_COLUMN_OWNER_NAME)1 CharacterAttributePtr 列を含む表のスキーマ。Db2 がこの属性を判別できない場合は、空ストリングが戻されます。
SQL_DESC_SEARCHABLE (SQL_COLUMN_SEARCHABLE)1 NumericAttributePtr 列データ・タイプが検索可能であるかどうかを示します。
  • SQL_PRED_NONE (ODBC 2.0 では SQL_UNSEARCHABLE): 列を WHERE 文節で使用できない場合。
  • SQL_PRED_CHAR (ODBC 2.0 では SQL_LIKE_ONLY): LIKE 述部を指定した場合にかぎり、WHERE 文節 で列を使用できる場合。
  • SQL_PRED_BASIC (ODBC 2.0 では SQL_ALL_EXCEPT_LIKE): LIKE を除くすべての 比較演算子を使用して、WHERE 文節内で列を使用できる場合。
  • SQL_SEARCHABLE : どの比較演算子を指定しても WHERE 文節の中で列を使用できる場合。
SQL_DESC_TABLE_NAME (SQL_COLUMN_TABLE_NAME)1 CharacterAttributePtr 列を含む表の名前。 Db2 ODBC がこの属性を判別できない場合は、空ストリングが戻されます。
SQL_DESC_TYPE (SQL_COLUMN_TYPE)1 NumericAttributePtr 列の SQL データ・タイプ。 日時データ・タイプの場合、このフィールドは冗長データ・タイプ (SQL_DATETIME など) を戻します。
SQL_DESC_TYPE_NAME (SQL_COLUMN_TYPE_NAME)1 CharacterAttributePtr 列のタイプ (SQL ステートメントで指定されたもの)。
SQL_DESC_UNNAMED NumericAttributePtr SQL_NAMED または SQL_UNNAMED を戻します。SQL_DESC_NAME に列名が含まれる場合 、SQL_NAMED が戻されます。列に名前がない場合は、SQL_UNNAMED が戻されます。
SQL_DESC_UNSIGNED (SQL_COLUMN_UNSIGNED)1 NumericAttributePtr 列データ・タイプが符号なしタイプであるかどうかを示します。 非数値データ・タイプの場合はすべて SQL_TRUE が NumericAttributePtr に 戻されます。数値データ・タイプの場合はすべて SQL_FALSE が戻されます。
SQL_DESC_UPDATABLE (SQL_COLUMN_UPDATABLE)1 NumericAttributePtr 列データ・タイプが、更新可能なデータ・タイプであるかどうかを示します。
  • Db2 SQL データ・タイプの場合はすべて 、NumericAttributePtr に SQL_ATTR_READWRITE_UNKNOWN が戻されます。
  • 列をカタログ関数呼び出しから取得した場合には、SQL_ATTR_READONLY が戻され ます。ODBC は以下の値も定義していますが 、Db2 ODBC はこれらの値は戻しません。
    • SQL_DESC_UPDATABLE
    • SQL_UPDT_WRITE
注:
  1. これらの記述子 (引数 fDescType の値) は、 「使用すべきでない」ODBC 2.0 SQLColAttributes() API 用です。SQLColAttribute() およ び SQLColAttributes() は両方ともこれらの値をサポートしています。

戻りコード

SQLColAttribute() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_INVALID_HANDLE
  • SQL_ERROR

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLColAttribute() の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(SQLColAttribute() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
01004 データが切り捨てられました。 引数 CharacterAttributePtr が指しているバッファーは、 ストリング値全体を戻すだけの十分な大きさがないため、ストリング値は切り捨てられました。 引数 StringLengthPtr が指しているバッファーに切り捨てられなかったストリング値 の長さ (バイト) が戻されます。(SQLColumnAttribute() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
07005 ステートメントが結果セットを戻しませんでした。 引数 StatementHandle に関連したステートメントが、結果セットを戻しませんでした。 記述する列がありません。
HY000 一般エラー。 具体的な SQLSTATE が存在しないエラーが起こりました。 引数 MessageText が指しているバッファーに SQLGetDiagRec() が戻す エラー・メッセージに、このエラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。
HY002 列番号が無効です。 引数 ColumnNumber に指定された値が 0 より小さいか、 または結果セットの列の数よりも大きい値です。
HY010 関数シーケンス・エラーが発生しました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • この関数は、引数 StatementHandle が指定するステートメント・ハンドル で、SQLPrepare() または SQLExecDirect() の前に呼び出されました。
  • SQLExecute() または SQLExecDirect() は、引数 StatementHandle が指定 するステートメント・ハンドルで呼び出され、SQL_NEED_DATA を戻し ます。SQLColAttribute() が、すべての実行時データ・パラメーターまたは列にデータが送られる前に呼び出されました。
HY090 ストリングまたはバッファーの長さが無効です。 引数 BufferLength に指定された値は 0 より小さい値です。
HY091 記述子のタイプが範囲外です。 引数 FieldIdentifier に指定された値は、定義済みのいずれの値でもなく、 インプリメンテーションで定義された値でもありません。
HYC00 ドライバーは使用できません。 Db2 ODBC は、引数 FieldIdentifier に指定された値をサポートしていません。

制約事項

ColumnNumber ゼロは定義できません。Db2 ODBC 3.0 ドライバーはブックマークをサポートしません。

例

関連例については、SQLColAttribute() を参照してください。この例では、SQLColAttribute() は列の表示上の長さを取り出します。