目的
仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLColAttribute() は、結果セット内の列について記述子情報を返します。記述子情報は、文字ストリング、32 ビットの記述子従属値、または整数値として返されます。
構文
SQLRETURN SQLColAttribute ( SQLHSTMT StatementHandle, /* hstmt */ SQLSMALLINT ColumnNumber, /* icol */ SQLSMALLINT FieldIdentifier, /* fDescType */ SQLPOINTER CharacterAttributePtr, /* rgbDesc */ SQLSMALLINT BufferLength, /* cbDescMax */ SQLSMALLINT *StringLengthPtr, /* pcbDesc */ SQLPOINTER NumericAttributePtr); /* pfDesc */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLUSMALLINT | ColumnNumber | 入力 |
フィールド値を検索する IRD の中のレコードの番号。この引き数は、結果データの列番号に対応し、その番号は 1 で始まり、左から右へ連続で順序付けられています。列は任意の順序で記述できます。
列 0 は、このステートメントで指定できますが、SQL_DESC_TYPE と
SQL_DESC_OCTET_LENGTH を除いてすべての値が、未定義の値を返すことになります。
|
SQLSMALLINT | FieldIdentifier | 入力 | 返されることになっている IRD の行 ColumnNumber にあるフィールド (表 34 を参照)。 |
SQLPOINTER | CharacterAttributePtr | 出力 | フィールドが文字ストリングの場合、 IRD の ColumnNumber 行の FieldIdentifier フィールド内の値を返すバッファーを指すポインター。それ以外の場合は、フィールドは未使用になります。 |
SQLINTEGER | BufferLength | 入力 | フィールドが文字ストリングの場合、 CharacterAttributePtr バッファーの長さ。それ以外の場合は、このフィールドは無視されます。 |
SQLSMALLINT | *StringLengthPtr | 出力 |
*CharacterAttributePtr に戻すために使用可能な総バイト数 (文字データのヌル終了バイトを除く) を戻すバッファーを指すポインター。
文字データの場合、戻りに使用できるバイト数が BufferLength 以上であれば、 CharacterAttributePtr 内の記述子情報は BufferLength バイトからヌル終了文字分の長さを差し引いたバイトに切り捨てられ、DB2 CLI によってヌル終了します。
その他のすべてのデータのタイプについては、
BufferLength の値は無視されて、
DB2 CLI は、*CharacterAttributePtr のサイズを 32 ビットと想定します。
|
SQLPOINTER | NumericAttributePtr | 出力 | フィールドが SQL_DESC_COLUMN_LENGTH のような文字ストリングの場合、 IRD の ColumnNumber 行の FieldIdentifier フィールド内の値を返す整数バッファーを指すポインター。それ以外の場合は、フィールドは未使用になります。 |
使用法
SQLColAttribute() は、情報を *NumericAttributePtr または *CharacterAttributePtr に返します。整数情報は、32 ビットの符号付き値として、*NumericAttributePtr に返されます。その他のすべての形式の情報は、*CharacterAttributePtr に返されます。情報が *NumericAttributePtr に返されるとき、DB2 CLI は、 CharacterAttributePtr、BufferLength、および StringLengthPtr を無視します。情報が *CharacterAttributePtr に返されるとき、 DB2 CLI は、NumericAttributePtr を無視します。
SQLColAttribute() は、IRD の記述子フィールドからの値を返します。関数は、記述子ハンドルではなくステートメント・ハンドルを使用して呼び出されます。下記にリストされる FieldIdentifier 値について SQLColAttribute() によって返される値は、適当な IRD ハンドルを使用して SQLGetDescField() を呼び出すことにより取り出すこともできます。
現在定義されている記述子タイプ、そのタイプが (おそらく別の名前で) 導入されている DB2 CLI のバージョン、およびそれについて情報が返される引き数を、以下に示します。さまざまなデータ・ソースを利用するために、より多くの記述子タイプが今後定義される見込みです。
DB2 CLI は、記述子タイプのおのおのについて値を返さなければなりません。記述子タイプがデータ・ソースに適用されない場合、他に断り書きがない限り、 DB2 CLI は、*StringLengthPtr に 0 を返すか、または *CharacterAttributePtr に空ストリングを返します。
次の表には、 SQLColAttribute() によって返される記述子タイプがリストされています。
FieldIdentifier | 情報の戻り先 | 説明 | ||
---|---|---|---|---|
SQL_COLUMN_AUTO_INCREMENT | Numeric AttributePtr | SQL_DESC_AUTO_UNIQUE_VALUE に変更されました。a | ||
SQL_COLUMN_CASE_SENSITIVE | Numeric AttributePtr | SQL_DESC_CASE_SENSITIVE に変更されました。a | ||
SQL_COLUMN_CATALOG_NAME | Character AttributePtr | SQL_DESC_CATALOG_NAME に変更されました。a | ||
SQL_COLUMN_COUNT | Numeric AttributePtr | SQL_DESC_COUNT に変更されました。a | ||
SQL_COLUMN_DISPLAY_SIZE | Numeric AttributePtr | SQL_DESC_DISPLAY_SIZE に変更されました。a | ||
SQL_COLUMN_LABEL | Character AttributePtr | SQL_DESC_LABEL に変更されました。a | ||
SQL_COLUMN_DISTINCT_TYPE | Character AttributePtr | SQL_DESC_DISTINCT_TYPE に変更されました。a | ||
SQL_COLUMN_LENGTH | Numeric AttributePtr | SQL_DESC_OCTET_LENGTH に変更されました。a | ||
SQL_COLUMN_MONEY | Numeric AttributePtr | SQL_DESC_FIXED_PREC_SCALE に変更されました。a | ||
SQL_COLUMN_NAME | Character AttributePtr | SQL_DESC_NAME に変更されました。a | ||
SQL_COLUMN_NULLABLE | Numeric AttributePtr | SQL_DESC_NULLABLE に変更されました。a | ||
SQL_COLUMN_OWNER_NAME | Character AttributePtr | SQL_DESC_SCHEMA_NAME に変更されました。a | ||
SQL_COLUMN_PRECISION | Numeric AttributePtr | SQL_DESC_PRECISION に変更されました。a | ||
SQL_COLUMN_QUALIFIER_NAME | Character AttributePtr | SQL_DESC_CATALOG_NAME に変更されました。a | ||
SQL_COLUMN_SCALE | Numeric AttributePtr | SQL_DESC_SCALE に変更されました。a | ||
SQL_COLUMN_SEARCHABLE | Numeric AttributePtr | SQL_DESC_SEARCHABLE に変更されました。a | ||
SQL_COLUMN_TABLE_NAME | Character AttributePtr | SQL_DESC_TABLE_NAME に変更されました。a | ||
SQL_COLUMN_TYPE | Numeric AttributePtr | SQL_DESC_TYPE に変更されました。a | ||
SQL_COLUMN_TYPE_NAME | Character AttributePtr | SQL_DESC_TYPE_NAME に変更されました。a | ||
SQL_COLUMN_UNSIGNED | Numeric AttributePtr | SQL_DESC_UNSIGNED に変更されました。a | ||
SQL_COLUMN_UPDATABLE | Numeric AttributePtr | SQL_DESC_UPDATABLE に変更されました。a | ||
SQL_DESC_AUTO_UNIQUE_VALUE (DB2 CLI v2) | Numeric AttributePtr | 列データ・タイプが自動増分データ・タイプであるかどうかを示します。
SQL_FALSE は、すべての DB2 SQL データ・タイプについて NumericAttributePtr に返されます。 | ||
SQL_DESC_BASE_COLUMN_NAME (DB2 CLI v5) | Character AttributePtr |
セット列用の基本列名。基本列名が存在しない場合 (列が式になっている場合など) は、この変数には空ストリングが入ります。
この情報は、読取専用フィールドである IRD の SQL_DESC_BASE_COLUMN_NAME レコード・フィールドから返されます。
| ||
SQL_DESC_BASE_TABLE_NAME (DB2 CLI v5) | Character AttributePtr | 列を含む基本表の名前。基本表名が定義できないか適用不能である場合、この変数には空ストリングが入ります。 | ||
SQL_DESC_CASE_SENSITIVE (DB2 CLI v2) | Numeric AttributePtr | 列データ・タイプが大文字小文字の区別があるタイプであるかどうかを示します。
SQL_TRUE または SQL_FALSE のどちらが NumericAttributePtr に返されるかは、データ・タイプに依存します。
大文字小文字の区別は図形データ・タイプには適用されず、SQL_FALSE が返されます。
非文字データ・タイプには SQL_FALSE が返されます。 | ||
SQL_DESC_CATALOG_NAME (DB2 CLI v2) | Character AttributePtr | 列を含む表のカタログが CharacterAttributePtr に返されます。 DB2 CLI は 1 つの表につき 2 つの部分からなる命名しかサポートしないため、空ストリングが返されます。 | ||
SQL_DESC_CONCISE_TYPE (DB2 CLI v5) | Character AttributePtr |
コンサイス・データ・タイプ
日時データ・タイプの場合、このフィールドはコンサイス・データ・タイプ、たとえば、SQL_TYPE_TIME を返します。
この情報は、IRD の
SQL_DESC_CONCISE_TYPE レコード・フィールドから返されます。
| ||
SQL_DESC_COUNT (DB2 CLI v2) | Numeric AttributePtr | 結果セット内の列数が、NumericAttributePtr に返されます。 | ||
SQL_DESC_DISPLAY_SIZE (DB2 CLI v2) | Numeric AttributePtr | 文字形式でデータを表示するのに必要な最大バイト数が、
NumericAttributePtr に返されます。
列タイプのおのおのの表示サイズについては、 表 197 を参照してください。 | ||
SQL_DESC_DISTINCT_TYPE (DB2 CLI v2) | Character AttributePtr | 列のユーザー定義の固有タイプ名が、CharacterAttributePtr に返されます。列が組み込み SQL タイプであってユーザー定義の固有タイプではない場合、空ストリングが返されます。
| ||
SQL_DESC_FIXED_PREC_SCALE (DB2 CLI v2) | Numeric AttributePtr |
SQL_TRUE は、列がデータ・ソース固有の固定精度および非ゼロの位取りを持っている場合です。
SQL_FALSE は、列がデータ・ソース固有の固定精度および非ゼロの位取りを持っていない場合です。
SQL_FALSE は、すべての DB2 SQL データ・タイプについて NumericAttributePtr に返されます。
| ||
SQL_DESC_LABEL (DB2 CLI v2) | Character AttributePtr | 列ラベルが、CharacterAttributePtr に返されます。列にラベルがない場合、列名または列式が返されます。列にラベルがなく、名前もない場合は、空ストリングが返されます。 | ||
SQL_DESC_LENGTH (DB2 CLI v2) | Numeric AttributePtr |
文字ストリングまたは 2 進データ・タイプの最大文字長または実際の文字長のどちらかである数値。これは、固定長データ・タイプの最大文字長であるか、可変長データ・タイプの実際の文字長となります。その値からは常に、文字ストリングの終わりを示すヌル終了バイトが除かれています。
この情報は、IRD の SQL_DESC_LENGTH レコード・フィールドから返されます。
| ||
SQL_DESC_LITERAL_PREFIX (DB2 CLI v5) | Character AttributePtr |
この VARCHAR(128) レコード・フィールドには、
DB2 CLI がこのデータ・タイプのリテラル用の接頭部として認識する文字 (複数を含む) が入っています。リテラルの接頭部が適用不能であるデータ・タイプに対しては、このフィールドに空ストリングが入れられます。
| ||
SQL_DESC_LITERAL_SUFFIX (DB2 CLI v5) | Character AttributePtr | この VARCHAR(128) レコード・フィールドには、 DB2 CLI がこのデータ・タイプのリテラル用の接尾部として認識する文字 (複数を含む) が入っています。リテラルの接尾部が適用不能であるデータ・タイプに対しては、このフィールドに空ストリングが入れられます。 | ||
SQL_DESC_LOCAL_TYPE_NAME (DB2 CLI v5) | Character AttributePtr | この列には、データ・タイプの正規名とは異なる、データ・タイプ用のローカライズされた (ネイティブ言語の) 名前が入ります。ローカライズされた名前がない場合は、空ストリングが返されます。このフィールドは、表示の目的においてのみ使用されます。ストリングの文字セットはロケールに依存しており、通常はサーバーの省略時文字セットです。 | ||
SQL_DESC_NAME (DB2 CLI v2) | Character AttributePtr | 列 ColumnNumber の名前が、CharacterAttributePtr に返されます。列が式である場合は、列番号が返されます。
いずれの場合にも、SQL_DESC_UNNAMED が SQL_NAMED に設定されます。列名または列別名がない場合は、空ストリングが返されて、 SQL_DESC_UNNAMED が SQL_UNNAMED に設定されます。
この情報は、IRD の SQL_DESC_NAME レコード・フィールドから返されます。
列名値は環境属性 SQL_ATTR_USE_LIGHT_OUTPUT_SQLDA の影響を受ける場合があります。詳細については、 SQLSetEnvAttr - 環境属性を設定するを参照してください。 | ||
SQL_DESC_NULLABLE (DB2 CLI v2) | Numeric AttributePtr | ColumnNumber によって識別される列に NULL を入れることができる場合、
SQL_NULLABLE が NumericAttributePtr に返されます。
列が NULL を受け入れないように制約されている場合、 SQL_NO_NULLS が NumericAttributePtr に返されます。
この情報は、 IRD の SQL_DESC_NULLABLE レコード・フィールドから返されます。 | ||
SQL_DESC_NUM_PREX_RADIX (DB2 CLI v5) | Numeric AttributePtr |
| ||
SQL_DESC_OCTET_LENGTH (DB2 CLI v2) | Numeric AttributePtr | 列に関連したデータのバイト 数が、NumericAttributePtr に返されます。これは、SQL_C_DEFAULT が C データ・タイプに指定されているときにこの列の取り出し時または SQLGetData() 実行時に転送されたデータの長さをバイト数で表したものです。
SQL データ・タイプの個々の長さについては、表 196 を参照してください。
ColumnNumber 内で識別される列が、固定長の文字ストリングまたは 2 進ストリング (たとえば、 SQL_CHAR または SQL_BINARY) である場合、実際の長さが返されます。
ColumnNumber 内で識別される列が、可変長の文字ストリングまたは 2 進ストリング (たとえば、 SQL_VARCHAR または SQL_BLOB) である場合、最大長が返されます。 | ||
SQL_DESC_PRECISION (DB2 CLI v2) | Numeric AttributePtr | 列が SQL_DECIMAL、SQL_NUMERIC、
SQL_DOUBLE、SQL_FLOAT、
SQL_INTEGER、SQL_REAL、または SQL_SMALLINT の場合、数値の精度 (有効桁数) が、NumericAttributePtr に返されます。
列が文字 SQL データ・タイプである場合、 NumericAttributePtr に返される精度は、列が保持できる文字 の最大数を示します。
列がグラフィック SQL データ・タイプの場合、 NumericAttributePtr に返される精度は、列が保持できる 2 バイト文字 の最大数を指定します。
SQL データ・タイプの個々の精度については、 表 194 を参照してください。
この情報は、IRD の SQL_DESC_PRECISION レコード・フィールドから返されます。 | ||
SQL_DESC_SCALE (DB2 CLI v2) | Numeric AttributePtr | 列の位取りの属性が返されます。
SQL データ・タイプの個々の位取りについては、表 195 を参照してください。
この情報は、IRD の SCALE レコード・フィールドから返されます。 | ||
SQL_DESC_SCHEMA_NAME (DB2 CLI v2) | Character AttributePtr | 列を含む表のスキーマが、CharacterAttributePtr に返されます。 DB2 CLI がこの属性を判別できないと、空ストリングが返されます。 | ||
SQL_DESC_SEARCHABLE (DB2 CLI v2) | Numeric AttributePtr | 列データ・タイプが検索可能であるかどうかを示します。
| ||
SQL_DESC_TABLE_NAME (DB2 CLI v2) | Character AttributePtr | 列を含む表の名前が、CharacterAttributePtr に返されます。 DB2 CLI がこの属性を判別できないと、空ストリングが返されます。 | ||
SQL_DESC_TYPE (DB2 CLI v2) | Numeric AttributePtr | ColumnNumber で識別される列の SQL データ・タイプが、
NumericAttributePtr に返されます。返される可能性のある値が、表 2 にリストされています。
ColumnNumber が 0 に等しいときは、可変長ブックマークについて SQL_BINARY が返され、固定長ブックマークについて SQL_INTEGER が返されます。
日時データ・タイプの場合、このフィールドは冗長データ・タイプ、たとえば、 SQL_DATETIME を返します。
この情報は、IRD の SQL_DESC_TYPE レコード・フィールドから返されます。 | ||
SQL_DESC_TYPE_NAME (DB2 CLI v2) | Character AttributePtr | 列のタイプ (SQL ステートメントに入力したとおりのもの) が、
CharacterAttributePtr に返されます。
各データ・タイプについては、 データ・タイプとデータ変換の表にある TYPE_NAME 属性を参照してください。 | ||
SQL_DESC_UNNAMED (DB2 CLI v5) | Numeric AttributePtr |
SQL_NAMED または SQL_UNNAMED。 IRD の SQL_DESC_NAME フィールドに列別名または列名が入っている場合、 SQL_NAMED が返されます。列名も列別名も入っていない場合は、SQL_UNNAMED が返されます。
この情報は、IRD の SQL_DESC_UNNAMED レコード・フィールドから返されます。
| ||
SQL_DESC_UNSIGNED (DB2 CLI v2) | Numeric AttributePtr | 列データ・タイプが無符号タイプであるかどうかを示します。
すべての非数値データ・タイプについては、 SQL_TRUE が NumericAttributePtr に返され、すべての数値データ・タイプについては、SQL_FALSE が返されます。 | ||
SQL_DESC_UPDATABLE (DB2 CLI v2) | Numeric AttributePtr | 列のデータ・タイプが更新可能なデータ・タイプであるかどうかを指定します。
DB2 CLI は返しませんが、ODBC は以下の値も定義しています。
| ||
|
この関数は、SQLDescribeCol() の代替として拡張性のあるものです。 SQLDescribeCol() は、ANSI-89 SQL に基づく記述子情報の固定セットを返します。 SQLColAttribute() は、ANSI SQL-92 および DBMS ベンダーの拡張機能で使用可能な、記述子情報のより広範なセットにアクセスできるようになっています。
戻りコード
診断
表 35. SQLColAttribute SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01004 | データが切り捨てられました。 | バッファー *CharacterAttributePtr は、ストリング値全部を返せるほど十分に大きくなかったので、ストリング値が切り捨てられました。 *StringLengthPtr には、切り捨て前のストリング値の長さが戻されます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
07005 | ステートメントが結果セットを返しませんでした。 | StatementHandle に関連したステートメントが結果セットを返しませんでした。記述する列がありませんでした。 |
07009 | 記述子索引が無効です。 | ColumnNumber に指定された値が 0 と同等であり、 SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF でした。引き数 ColumnNumber に指定された値は、0 より小さい値でした。引き数 ColumnNumber に指定された値は、結果セット内の列数より大きい値でした。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY008 | 操作が取り消されました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY010 | 関数の順序エラーです。 | SQLPrepare() または SQLExecDirect() を StatementHandle 用に呼び出す前に、この関数が呼び出されました。
非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
StatementHandle のために SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 BufferLength に指定された値は、0 より小さい値でした。 |
HY091 | 記述子タイプが範囲外です。 | 引き数 FieldIdentifier に指定された値は、定義されている値の 1 つではなく、処理系定義の値でもありませんでした。 |
HYC00 | ドライバーが機能していません。 | 引き数 FieldIdentifier に指定された値は、DB2 CLI でサポートされていませんでした。 |
データ・ソースが StatementHandle に関連した SQL ステートメントを評価する時期に依存して、 SQLPrepare() の後、SQLExecute() の前に呼び出されたときに、 SQLColAttribute() は、 SQLPrepare() または SQLExecute() によって返される任意の SQLSTATE を返すことができます。
パフォーマンス上の理由から、アプリケーションは、ステートメントの実行前に SQLColAttribute() を呼び出さないようにすべきです。
制約
なし。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ /* get display size for column */ sqlrc = SQLColAttribute( hstmt, ( SQLSMALLINT ) ( i + 1 ), SQL_DESC_DISPLAY_SIZE, NULL, 0, NULL, &colDataDisplaySize ) ; STMT_HANDLE_CHECK( hstmt, sqlrc);
参照