SQLColAttribute() - 列属性を取得する
SQLColAttribute() は、結果セット内の列の記述子情報を戻します。記述子情報は、文字ストリング、32 ビットの記述子従属値、または整数値として戻されます。
SQLColAttribute() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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() の属性値 (括弧内に記載) とともに 示しています。
| フィールド 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_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 データ・タイプの場合、戻される精度は、列が保持できる文字の最大数を示します。 列がグラフィック 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_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 | 列データ・タイプが、更新可能なデータ・タイプであるかどうかを示します。
|
| 注:
|
||
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 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 が戻されます。
|
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 BufferLength に指定された値は 0 より小さい値です。 |
| HY091 | 記述子のタイプが範囲外です。 | 引数 FieldIdentifier に指定された値は、定義済みのいずれの値でもなく、 インプリメンテーションで定義された値でもありません。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、引数 FieldIdentifier に指定された値をサポートしていません。 |
制約事項
ColumnNumber ゼロは定義できません。Db2 ODBC 3.0 ドライバーはブックマークをサポートしません。
例
関連例については、SQLColAttribute() を参照してください。この例では、SQLColAttribute() は列の表示上の長さを取り出します。