SQLDescribeCol() - 列属性を記述する
SQLDescribeCol() は、照会で生成された結果セットの列に関する、共通に使用される記述子情報を戻します。この関数を呼び出す前に、SQLPrepare() または SQLExecDirect() のいずれかを呼び出す必要があります。
SQLDescribeCol() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
31 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLDescribeCol (SQLHSTMT hstmt,
SQLUSMALLINT icol,
SQLCHAR FAR *szColName,
SQLSMALLINT cbColNameMax,
SQLSMALLINT FAR *pcbColName,
SQLSMALLINT FAR *pfSqlType,
SQLUINTEGER FAR *pcbColDef,
SQLSMALLINT FAR *pibScale,
SQLSMALLINT FAR *pfNullable);
64 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLDescribeCol (SQLHSTMT hstmt,
SQLUSMALLINT icol,
SQLCHAR FAR *szColName,
SQLSMALLINT cbColNameMax,
SQLSMALLINT FAR *pcbColName,
SQLSMALLINT FAR *pfSqlType,
SQLULEN FAR *pcbColDef,
SQLSMALLINT FAR *pibScale,
SQLSMALLINT FAR *pfNullable);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドルを指定します。 |
| SQLUSMALLINT | icol | 入力 | 記述する列番号を指定します。 列は、左から右へ、1 から順番に番号が付けられています。 |
| SQLCHAR * | szColName | 出力 | 列名が入るバッファーを指すポインターを指定します。 列名を受け取る必要がない場合は、これに NULL ポインターを設定します。 |
| SQLSMALLINT | cbColNameMax | 入力 | 引数 szColName が指しているバッファーのサイズを指定します。 |
| SQLSMALLINT * | pcbColName | 出力 | 完全な列名に必要なバイト数を戻します。 pcbColName が cbColNameMax 以上である場合、 列名 (szColName) が cbColNameMax - 1 バイトに切り捨てられます。 |
| SQLSMALLINT * | pfSqlType | 出力 | 列の基本 SQL データ・タイプを戻します。特殊タイプが列に関連しているかどうかを 判別するには、fDescType を SQL_COLUMN_DISTINCT_TYPE に 設定して、SQLColAttribute() を呼び出します。 |
| SQLUINTEGER * (31 ビット) または SQLULEN * (64 ビット) 1 | pcbColDef | 出力 | データベースで定義されている列の精度を戻します。 |
| SQLSMALLINT * | pibScale | 出力 | データベースで定義されている列の 位取り (SQL_DECIMAL、SQL_NUMERIC、SQL_TYPE_TIMESTAMP のみに適用される)。 |
| SQLSMALLINT * | pfNullable | 出力 | 次の値を持つ列で NULL 値が許されるかどうかを示します。
|
注:
|
|||
使用法
記述子情報 (列名、タイプ、精度、位取り、NULL 可能性) の 1 つの属性のみを必要とする場合、または SQLDescribeCol() が戻さない属性を必要とする場合は、SQLDescribeCol() の代わりに SQLColAttribute() を使用します。
通常は、列をアプリケーション変数にバインドする前に、この関数 (または SQLColAttribute() 関数) を呼び出します。
列は番号で識別され、番号は 1 から始まり左から右へ順番に番号付けされますが、記述の順序は任意です。
いずれかのポインター引数に NULL ポインターが指定されると、Db2 ODBC は、 アプリケーションでは情報を必要としないと見なし、何も戻しません。
列が特殊タイプである場合、SQLDescribeCol() は、組み込みタイプのみを 引数 pfSqlType に戻します。特殊タイプを取得するには、 引数 SQLColAttribute() を SQL_COLUMN_DISTINCT_TYPE に設定 して fDescType を呼び出します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
SQLDescribeCol() が SQL_ERROR または SQL_SUCCESS_WITH_INFO のいずれかを戻した場合 は、SQLGetDiagRec() を呼び出して、次の表に リストされている SQLSTATE の 1 つを取得することができます。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 引数 szColName に戻された列名は、 引数 cbColNameMax で指定された値より長い値です。 引数 pcbColName には、完全な列名の長さ (バイト) が含まれて います。(SQLDescribeCol() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します) |
| 07005 | ステートメントが結果セットを戻しませんでした。 | ステートメント・ハンドルに関連したステートメントが、 結果セットを戻しませんでした。 記述する列が存在しません。(結果セットに何か行があるかどうかを判別するには、 まず SQLNumResultCols() を呼び出してください。) |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 cbColNameMax で指定された長さが、1 より小さいです。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、引数 icol が指定する列の SQL データ・タイプ を認識しません。 |
| HY002 | 列番号が無効です。 | 引数 icol が指定する値が 1 より小さいか、 または結果セットの列の数よりも大きい値です。 |
例
/* ... */
/*******************************************************************
** process_stmt
** - allocates a statement handle
** - executes the statement
** - determines the type of statement
** - if no result columns exist, therefore non-select statement
** - if rowcount > 0, assume statement was UPDATE, INSERT, DELETE
** else
** - assume a DDL, or Grant/Revoke statement
** else
** - must be a select statement.
** - display results
** - frees the statement handle
*******************************************************************/
int
process_stmt(SQLHENV henv,
SQLHDBC hdbc,
SQLCHAR * sqlstr)
{
SQLHSTMT hstmt;
SQLSMALLINT nresultcols;
SQLINTEGER rowcount;
SQLRETURN rc;
/* Allocate a statement handle */
SQLAllocHandle( SQL_ HANDLE_STMT, hdbc, &hstmt);
/* Execute the SQL statement in "sqlstr" */
rc = SQLExecDirect(hstmt, sqlstr, SQL_NTS);
if (rc != SQL_SUCCESS)
if (rc == SQL_NO_DATA_FOUND) {
printf("¥nStatement executed without error, however,¥n");
printf("no data was found or modified¥n");
return (SQL_SUCCESS);
} else
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc);
rc = SQLNumResultCols(hstmt, &nresultcols);
/* Determine statement type */
if (nresultcols == 0) { /* statement is not a select statement */
rc = SQLRowCount(hstmt, &rowcount);
if (rowcount > 0) { /* assume statement is UPDATE, INSERT, DELETE */
printf("Statement executed,
} else { /* assume statement is GRANT, REVOKE or a DLL
* statement */
printf("Statement completed successful¥n");
}
} else { /* display the result set */
display_results(hstmt, nresultcols);
} /* end determine statement type */
rc = SQLFreeHandle(SQL_HANDLE_STMT, hstmt); /* Free statement handle */
return (0);
} /* end process_stmt */
/*******************************************************************
** display_results
** - for each column
** - get column name
** - bind column
** - display column headings
** - fetch each row
** - if value truncated, build error message
** - if column null, set value to "NULL"
** - display row
** - print truncation message
** - free local storage
*******************************************************************/
display_results(SQLHSTMT hstmt,
SQLSMALLINT nresultcols)
{
SQLCHAR colname[32];
SQLSMALLINT coltype;
SQLSMALLINT colnamelen;
SQLSMALLINT nullable;
SQLINTEGER collen[MAXCOLS];
SQLUINTEGER precision;
SQLSMALLINT scale;
SQLINTEGER outlen[MAXCOLS];
SQLCHAR *data[MAXCOLS];
SQLCHAR errmsg[256];
SQLRETURN rc;
SQLINTEGER i;
SQLINTEGER x;
SQLINTEGER displaysize;
for (i = 0; i < nresultcols; i++) {
SQLDescribeCol(hstmt, i + 1, colname, sizeof(colname),
&colnamelen, &coltype, &precision, &scale, NULL);
collen[i] = precision; /* Note, assignment of unsigned int to signed */
/* Get display length for column */
SQLColAttribute(hstmt, i + 1, SQL_COLUMN_DISPLAY_SIZE, NULL, 0,
NULL, &displaysize);
/*
* Set column length to max of display length, and column name
* length. Plus one byte for null terminator
*/
collen[i] = max(displaysize, strlen((char *) colname)) + 1;
printf("i], collen[i], colname);
/* Allocate memory to bind column */
data[i] = (SQLCHAR *) malloc(collen[i]);
/* Bind columns to program vars, converting all types to CHAR */
rc = SQLBindCol(hstmt, i + 1, SQL_C_CHAR, data[i], collen[i], &outlen[i]);
}
printf("¥n");
/* Display result rows */
while ((rc = SQLFetch(hstmt)) != SQL_NO_DATA_FOUND) {
errmsg[0] = '¥0';
for (i = 0; i < nresultcols; i++) {
/* Build a truncation message for any columns truncated */
if (outlen[i] >= collen[i]) {
sprintf((char *) errmsg + strlen((char *) errmsg),
"%ld chars truncated, col %d¥n",
outlen[i] - collen[i] + 1, i + 1);
sprintf((char *) errmsg + strlen((char *) errmsg),
"Bytes to return = %ld size of buffer¥n",
outlen[i], collen[i]);
}
if (outlen[i] == SQL_NULL_DATA)
printf("i], collen[i], "NULL");
else
printf("i], collen[i], data[i]);
} /* for all columns in this row */
printf("¥n /* print any truncation messages */
} /* while rows to fetch */
/* Free data buffers */
for (i = 0; i < nresultcols; i++) {
free(data[i]);
}
} /* end display_results */
/* ... */