SQLDescribeCol() - 列属性を記述する

SQLDescribeCol() は、照会で生成された結果セットの列に関する、共通に使用される記述子情報を戻します。この関数を呼び出す前に、SQLPrepare() または SQLExecDirect() のいずれかを呼び出す必要があります。

SQLDescribeCol() の ODBC 仕様

表 1. SQLDescribeCol() の仕様
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);

関数の引数

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

表 2. SQLDescribeCol() の引数
データ・タイプ 引数 使用法 説明
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 値が許されるかどうかを示します。
  • SQL_NO_NULLS
  • SQL_NULLABLE
注:
  1. 64 ビット・アプリケーションの場合、旧バージョンの Db2® で使用されていたデータ・タイプ SQLUINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLULEN の使用をお勧めします。

使用法

記述子情報 (列名、タイプ、精度、位取り、NULL 可能性) の 1 つの属性のみを必要とする場合、または SQLDescribeCol() が戻さない属性を必要とする場合は、SQLDescribeCol() の代わりに SQLColAttribute() を使用します。

通常は、列をアプリケーション変数にバインドする前に、この関数 (または SQLColAttribute() 関数) を呼び出します。

列は番号で識別され、番号は 1 から始まり左から右へ順番に番号付けされますが、記述の順序は任意です。

いずれかのポインター引数に NULL ポインターが指定されると、Db2 ODBC は、 アプリケーションでは情報を必要としないと見なし、何も戻しません。

列が特殊タイプである場合、SQLDescribeCol() は、組み込みタイプのみを 引数 pfSqlType に戻します。特殊タイプを取得するには、 引数 SQLColAttribute() を SQL_COLUMN_DISTINCT_TYPE に設定 して fDescType を呼び出します。

戻りコード

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

診断

SQLDescribeCol() が SQL_ERROR または SQL_SUCCESS_WITH_INFO のいずれかを戻した場合 は、SQLGetDiagRec() を呼び出して、次の表に リストされている SQLSTATE の 1 つを取得することができます。

表 3. SQLDescribeCol() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 引数 szColName に戻された列名は、 引数 cbColNameMax で指定された値より長い値です。 引数 pcbColName には、完全な列名の長さ (バイト) が含まれて います。(SQLDescribeCol() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します)
07005 ステートメントが結果セットを戻しませんでした。 ステートメント・ハンドルに関連したステートメントが、 結果セットを戻しませんでした。 記述する列が存在しません。(結果セットに何か行があるかどうかを判別するには、 まず SQLNumResultCols() を呼び出してください。)
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • この関数は、SQLPrepare() または SQLExecDirect() の前に、ステートメント・ハンドルで呼び出されました。
  • この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 cbColNameMax で指定された長さが、1 より小さいです。
HYC00 ドライバーは使用できません。 Db2 ODBC は、引数 icol が指定する列の SQL データ・タイプ を認識しません。
HY002 列番号が無効です。 引数 icol が指定する値が 1 より小さいか、 または結果セットの列の数よりも大きい値です。

例

以下の例 は、SQLDescribeCol() を使用して、 表列に関する記述子情報を取り出すアプリケーションを示しています。
図 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 */
/* ... */