仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLDescribeCol() は、照会で生成された結果セット内の指定された列に関する共通に使用される記述子情報 (列名、タイプ、精度、位取り、ヌル可) を返します。
この情報は、IRD のフィールドでも使用可能です。
アプリケーションが記述子情報の属性を 1 つだけ必要としているか、または SQLDescribeCol() によっては返されない属性を必要とする場合には、 SQLDescribeCol() の代わりに SQLColAttribute() 関数を使用することができます。詳細については、SQLColAttribute - 列属性を返すを参照してください。
この関数を呼び出す前に、 SQLPrepare() または SQLExecDirect() を呼び出す必要があります。
この関数 (または SQLColAttribute()) は通常、バインド列関数 (SQLBindCol()、SQLBindFileToCol()) の前に呼び出され、アプリケーション変数にバインドする前に列の属性を判別します。
構文
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 */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル |
SQLUSMALLINT | ColumnNumber | 入力 | 記述される列番号。列は、1 を最初の番号として順次左から右へ番号が付けられます。また、0 に設定してブックマークを記述することもできます。 |
SQLCHAR * | ColumnName | 出力 | 列名バッファーを指すポインター。この値は、IRD の SQL_DESC_NAME フィールドから読み取られます。列名が不明なときは、これをヌル (null) に設定してください。
列名値は環境属性 SQL_ATTR_USE_LIGHT_OUTPUT_SQLDA の影響を受ける場合があります。詳細については、 SQLSetEnvAttr - 環境属性を設定するを参照してください。 |
SQLSMALLINT | BufferLength | 入力 | ColumnName バッファーのサイズ。 |
SQLSMALLINT * | NameLengthPtr | 出力 | ColumnName 引き数について返すために使用できるバイト。 NameLengthPtr がBufferLength 以上である場合、列名 (ColumnName) が BufferLength - 1 バイトに切り捨てられます。 |
SQLSMALLINT * | DataTypePtr | 出力 | 列の基本 SQL データ・タイプ。列に関連付けられているユーザー定義タイプがあるかどうかを判別するには、 fDescType を SQL_COLUMN_DISTINCT_TYPE に設定して、SQLColAttribute() を呼び出してください。サポートされるデータ・タイプについては、 表 2 の「記号 SQL データ・タイプ」列を参照してください。 |
SQLUINTEGER * | ColumnSizePtr | 出力 | データベースで定義されている列の精度。
fSqlType が図形または DBCLOB SQL データ・タイプを指示する場合、この変数は列が保持できる 2 バイト文字 の最大数を示します。 |
SQLSMALLINT * | DecimalDigitsPtr | 出力 | データベースで定義されている列の位取り (SQL_DECIMAL、 SQL_NUMERIC、 SQL_TIMESTAMP だけに適用される)。各 SQL データ・タイプの位取りについては、表 195 を参照してください。 |
SQLSMALLINT * | NullablePtr | 出力 | この列に NULL が使用できるかどうかを示します。
|
使用法
列は、順次左から右へ割り当てられた番号で識別されます。記述はどの順序でも行うことができます。
ポインター引き数についてヌル・ポインターを指定すると、 DB2 CLI はアプリケーションが情報を要求していないとみなし、何も返されません。
列がユーザー定義タイプの場合、 SQLDescribeCol は DataTypePtr に組み込みタイプだけを返します。ユーザー定義タイプを入手するには、fDescType を SQL_COLUMN_DISTINCT_TYPE に設定して、 SQLColAttribute() を呼び出してください。
戻りコード
診断
SQLDescribeCol() が SQL_ERROR または L_SUCCESS_WITH_INFO を返した場合、
SQLError() 関数を呼び出して以下の SQLSTATE のうちの 1 つを取得することができます。
SQLSTATE | 説明 | 解説 |
---|---|---|
01004 | データが切り捨てられました。 | 引き数 ColumnName 内に返された列名が、引き数 BufferLength 内で指定された値より長い値でした。引き数 NameLengthPtr には、完全列名の長さが含まれています。 (関数は、SQL_SUCCESS_WITH_INFO を返します。) |
07005 | ステートメントが結果セットを返しませんでした。 | StatementHandle に関連したステートメントが結果セットを返しませんでした。記述する列がありませんでした。 (結果セット内に行があるかどうかを判別するには、まず SQLNumResultCols() を呼び出します。) |
07009 | 無効な記述子索引 | ColumnNumber に指定された値が 0 と同等であり、 SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF でした。引き数 ColumnNumber に指定された値は、0 より小さい値でした。引き数 ColumnNumber に指定された値は、結果セット内の列数より大きい値でした。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY002 | 列の番号が無効です。 | 引き数 ColumnNumber に指定された値は、1 より小さい値でした。
引き数 ColumnNumber に指定された値は、結果セット内の列数より大きい値でした。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY090 | ストリングまたはバッファー長が無効です。 | 1 より小さい、引き数 BufferLength で指定された長さ。 |
HY010 | 関数の順序エラーです。 | StatementHandle の SQLPrepare() または SQLExecDirect() を呼び出す前に、この関数を呼び出しました。
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HYC00 | ドライバーが機能していません。 | 列 ColumnNumber の SQL データ・タイプは、DB2 CLI では認識されません。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
以下の ODBC 定義のデータ・タイプはサポートされていません。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ sqlrc = SQLDescribeCol( hstmt, ( SQLSMALLINT ) ( i + 1 ), colName, sizeof(colName), &colNameLen, &colType, &colSize, &colScale, NULL ) ;
参照