SQLSetColAttributes() - 列属性を設定する

SQLSetColAttributes() は、結果セットの列に、 データ・ソース結果記述子 (列名、タイプ、精度、位取り、および NULL 可能性) を設定します。 データ・ソース結果記述子を設定しておけば、 Db2® ODBC が データベース管理システム・サーバーから記述子情報を取得する必要はありません。

SQLSetColAttributes() の ODBC 仕様

表 1. SQLSetColAttributes() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし なし なし

構文

SQLRETURN  SQLSetColAttributes (SQLHSTMT        hstmt,
                              SQLUSMALLINT      icol,
                              SQLCHAR     FAR   *pszColName,
                              SQLSMALLINT       cbColName,
                              SQLSMALLINT       fSqlType,
                              SQLUINTEGER       cbColDef,
                              SQLSMALLINT       ibScale,
                              SQLSMALLINT       fNullable);

関数の引数

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

表 2. SQLSetColAttributes() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLUSMALLINT icol 入力 1 から始まり、左から右へ順番に番号が付けられた結果データの列番号。
SQLCHAR * szColName 入力 列名を指すポインター。 列に名前がないか、列が式の場合、このポインターを NULL に設定するか、 または空ストリングを使用することができます。
SQLSMALLINT cbColName 入力 szColName バッファーの長さ (バイト)。
SQLSMALLINT fSqlType 入力 列の SQL データ・タイプ。 以下の値が示されます。
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BLOB
  • SQL_CHAR
  • SQL_CLOB
  • SQL_DBCLOB
  • SQL_DECFLOAT
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_GRAPHIC
  • SQL_INTEGER
  • SQL_LONGVARBINARY
  • SQL_LONGVARCHAR
  • SQL_LONGVARGRAPHIC
  • SQL_NUMERIC
  • SQL_REAL
  • SQL_ROWID
  • SQL_SMALLINT
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
  • SQL_VARBINARY
  • SQL_VARCHAR
  • SQL_VARGRAPHIC
  • SQL_XML
SQLUINTEGER cbColDef 入力 データ・ソース上の列の精度。fSqlType が SQL_XML の場合、ODBC は cbColDef を無視します。
SQLSMALLINT ibScale 入力 データ・ソースの列の位取り。これは、SQL_DECIMAL、 SQL_NUMERIC、SQL_TYPE_TIMESTAMP 以外のすべてのデータ・タイプの場合は無視されます。
SQLSMALLINT fNullable 入力 この列で NULL 値が許されているかどうかを示します。これは、次いずれかの値でなければなりません。
  • SQL_NO_NULLS : この列で NULL 値を使用できません。
  • SQL_NULLABLE : この列で NULL 値を使用できます。

使用法

この関数は、アプリケーションが極端に多くの列を含む結果セットを フェッチする場合、ネットワーク・トラフィックを削減するのに役立つ ように設計されています。このアプリケーションが 結果セットの記述子情報特性について高度に知っていると (つまり、 列の正確な個数、列名、データ・タイプ、NULL 可能性、精度、または位取りを知っていると)、 データベースから Db2 ODBC に情報を取得させる のではなく、このアプリケーションが、Db2 ODBC にこの情報を通知でき、それによって ネットワーク・トラフィックが削減されます。

一般に、アプリケーションは、SQLPrepare() 呼び出しの後、かつ SQLExecute() に対する 関連した呼び出しの前に、SQLSetColAttributes() を呼び出します。 また、アプリケーションは、SQLExecDirect() 呼び出しの前に SQLSetColAttributes() を 呼び出すこともできます。 このステートメント・ハンドルのステートメント属性 SQL_NODESCRIBE を SQL_NODESCRIBE_ON に 設定した後でのみ、この関数は有効です。

SQLSetColAttributes() は、後続の照会の実行で生成される列名、タイプ、および長さを Db2 ODBC に通知します。この情報により、Db2 ODBC は、結果がアプリケーションに戻されたときに データ変換が必要かどうかを判別できるようになります。

推奨事項: この関数は、結果セットの性質を正確に把握している場合にのみ 使用してください。

アプリケーションは、結果セットのすべての列に関する結果記述子情報を提供する必要があります。 そのようにしておかないと、後続のフェッチの際にエラー (SQLSTATE 07002) が 生じます。 結果セットできわめて大量の (数百もの) 列を処理するアプリケーションの場合のみ、 この関数を使用すると役に立ちます。それ以外の場合は、効果はほとんどありません。

戻りコード

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

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLSetColAttributes() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 引数 szColName に、長すぎる列名が含まれています。 列名の最大長を得るには、InfoType SQL_MAX_COLUMN_NAME_LEN を 用いて SQLGetInfo を呼び出します。
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 ステートメント・ハンドルでカーソルがオープン状態です。
HY000 一般エラー。 具体的な SQLSTATE のない、しかもインプリメンテーションの定義で SQLSTATE が 定義されていないエラーが発生しました。SQLGetDiagRec() の引数 szErrorMsg で戻される エラー・メッセージは、エラーとその原因を記述しています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY004 SQL データ・タイプが無効です。 引数 fSqlType に指定された値が有効な SQL データ・タイプ ではありません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 cbColName に指定された値は 0 より小さく、SQL_NTS と等しくありません。
HY099 NULL 可能タイプが範囲外です。 fNullable に指定した値は無効です。
HY104 精度値が無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • fSqlType に指定された値が SQL_DECIMAL または SQL_NUMERIC であり、 かつ cbColDef に指定された値が 1 より小さい。もしくは、ibScale に 指定された値が 0 より小さいか、あるいは引数 cbColDef (精度) の値より大きい。
  • 変更の始まりfSqlType に指定する値が SQL_TYPE_TIMESTAMP で、ibScale の 値が 0 より小さいか、12 より大きい。変更の終わり
HY002 列番号が無効です。 引数 icol に指定された値が 1 より小さいか、サーバーで サポートされる列の最大数より大きい値です。

例

以下の例は、SQLSetColAttributes() を使用して、 データ・ソース結果記述子を設定するアプリケーションを示しています。
図 1. データ・ソース結果記述子を設定するアプリケーション
/* ... */
    SQLCHAR         stmt[] =
    { "Select id, name from staff" };
/* ... */
  /* Tell DB2 ODBC not to get column attribute from the server for this hstmt */
    rc = SQLSetStmtAttr(hstmt,SQL_ATTR,NODESCRIBE,(void *)SQL_NODESCRIBE_ON, 0);
    rc = SQLPrepare(hstmt, stmt, SQL_NTS);
/* Provide the columns attributes to DB2 ODBC for this hstmt */
    rc = SQLSetColAttributes(hstmt, 1, "-ID-", SQL_NTS, SQL_SMALLINT,
                             5, 0, SQL_NO_NULLS);
    rc = SQLSetColAttributes(hstmt, 2, "-NAME-", SQL_NTS, SQL_CHAR,
                             9, 0, SQL_NULLABLE);
    rc = SQLExecute(hstmt);
    print_results(hstmt); /* Call sample function to print column attributes
                             and fetch and print rows.  */
    rc = SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
    rc = SQLEndTran( SQL_HANDLE, DBC, hdbc, SQL_COMMIT);
    printf("Disconnecting .....¥n");
    rc = SQLDisconnect(hdbc);
    rc = SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    if (rc != SQL_SUCCESS)
        return (terminate(henv, rc));
    rc = SQLFreeHandle(SQL_HANDLE_ENV, henv);
    if (rc != SQL_SUCCESS)
        return (terminate(henv, rc));
    return (SQL_SUCCESS);
}                               /* end main */