SQLSetColAttributes() - 列属性を設定する
SQLSetColAttributes() は、結果セットの列に、 データ・ソース結果記述子 (列名、タイプ、精度、位取り、および NULL 可能性) を設定します。 データ・ソース結果記述子を設定しておけば、 Db2® ODBC が データベース管理システム・サーバーから記述子情報を取得する必要はありません。
SQLSetColAttributes() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。 |
| SQLUSMALLINT | icol | 入力 | 1 から始まり、左から右へ順番に番号が付けられた結果データの列番号。 |
| SQLCHAR * | szColName | 入力 | 列名を指すポインター。 列に名前がないか、列が式の場合、このポインターを NULL に設定するか、 または空ストリングを使用することができます。 |
| SQLSMALLINT | cbColName | 入力 | szColName バッファーの長さ (バイト)。 |
| SQLSMALLINT | fSqlType | 入力 | 列の SQL データ・タイプ。 以下の値が示されます。
|
| SQLUINTEGER | cbColDef | 入力 | データ・ソース上の列の精度。fSqlType が SQL_XML の場合、ODBC は cbColDef を無視します。 |
| SQLSMALLINT | ibScale | 入力 | データ・ソースの列の位取り。これは、SQL_DECIMAL、 SQL_NUMERIC、SQL_TYPE_TIMESTAMP 以外のすべてのデータ・タイプの場合は無視されます。 |
| SQLSMALLINT | fNullable | 入力 | この列で NULL 値が許されているかどうかを示します。これは、次いずれかの値でなければなりません。
|
使用法
この関数は、アプリケーションが極端に多くの列を含む結果セットを フェッチする場合、ネットワーク・トラフィックを削減するのに役立つ ように設計されています。このアプリケーションが 結果セットの記述子情報特性について高度に知っていると (つまり、 列の正確な個数、列名、データ・タイプ、NULL 可能性、精度、または位取りを知っていると)、 データベースから Db2 ODBC に情報を取得させる のではなく、このアプリケーションが、Db2 ODBC にこの情報を通知でき、それによって ネットワーク・トラフィックが削減されます。
一般に、アプリケーションは、SQLPrepare() 呼び出しの後、かつ SQLExecute() に対する 関連した呼び出しの前に、SQLSetColAttributes() を呼び出します。 また、アプリケーションは、SQLExecDirect() 呼び出しの前に SQLSetColAttributes() を 呼び出すこともできます。 このステートメント・ハンドルのステートメント属性 SQL_NODESCRIBE を SQL_NODESCRIBE_ON に 設定した後でのみ、この関数は有効です。
SQLSetColAttributes() は、後続の照会の実行で生成される列名、タイプ、および長さを Db2 ODBC に通知します。この情報により、Db2 ODBC は、結果がアプリケーションに戻されたときに データ変換が必要かどうかを判別できるようになります。
推奨事項: この関数は、結果セットの性質を正確に把握している場合にのみ 使用してください。
アプリケーションは、結果セットのすべての列に関する結果記述子情報を提供する必要があります。 そのようにしておかないと、後続のフェッチの際にエラー (SQLSTATE 07002) が 生じます。 結果セットできわめて大量の (数百もの) 列を処理するアプリケーションの場合のみ、 この関数を使用すると役に立ちます。それ以外の場合は、効果はほとんどありません。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 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 が戻されます。
|
| HY002 | 列番号が無効です。 | 引数 icol に指定された値が 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 */

