SQLGetEnvAttr() - 環境属性の現行設定値を戻す

SQLGetEnvAttr() は、環境属性の現行設定値を戻します。SQLSetEnvAttr() 関数を使用しても、これらの属性を設定できます。

SQLGetEnvAttr() の ODBC 仕様

表 1. SQLGetEnvAttr() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

SQLRETURN  SQLGetEnvAttr (SQLHENV           EnvironmentHandle,
                          SQLINTEGER        Attribute,
                          SQLPOINTER        ValuePtr,
                          SQLINTEGER        BufferLength,
                          SQLINTEGER        *StringLengthPtr); 

関数の引数

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

表 2. SQLGetEnvAttr() の引数
データ・タイプ 引数 使用法 説明
SQLHENV EnvironmentHandle 入力 環境ハンドルを指定します。
SQLINTEGER 属性 入力 取り出す属性を指定します。 環境属性とその説明のリストが、関数 SQLSetEnvAttr() の下に説明されています。
SQLPOINTER ValuePtr 出力 引数 Attribute に関連した現行値が戻されるバッファーを指しています。 戻される値のタイプは、引数 Attribute が指定するものによって異なります。
SQLINTEGER BufferLength 入力 引数 ValuePtr が指しているバッファーの最大サイズを指定します。 この引数には、以下の条件が適用されます。
  • ValuePtr が文字ストリングを指す場合、この引数ではバッファー長 (バイト)、または NUL 終了ストリングの場合は SQL_NTS の値を指定する必要があります。SQL_NTS を指定した 場合、ドライバーは、戻されるストリングの長さ は SQL_MAX_OPTIONS_STRING_LENGTH バイト (NUL 終止符を除く) であると想定します。
  • ValuePtr が整数を指す場合、引数 BufferLength は無視されます。
SQLINTEGER * StringLengthPtr 出力 ValuePtr 引数に関連した合計バイト数を格納するバッファーを指します。この数には、NUL 終了文字のバイト数は含まれません。ValuePtr が NULL ポインターの場合、長さは戻されません。 属性値が文字ストリングであり、さらに戻すことのできるバイト数が引数 BufferLength 以上の場合は、ValuePtr のデータは BufferLength から NUL 終止文字を引いた長さに 切り捨てられます。 その後、Db2® ODBC はその値を NUL 終了します。

引数 Attribute がストリングを示していない場合、Db2 ODBC は、 引数 BufferLength を無視し、StringLengthPtr が指している バッファーに値を設定しません。

使用法

SQLGetEnvAttr() は、環境ハンドルの割り振りから解放までの間、いつでも呼び出すことができます。 この関数は、環境属性の現行値を取得します。

戻りコード

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

診断

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

表 3. SQLGetEnvAttr() の SQLSTATE
SQLSTATE 説明 説明
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。
HY092 オプションのタイプが範囲外です。 引数 Attribute に無効な値が指定されています。

例

次の例では、環境属性の現行値を印刷します。SQLGetEnvAttr() は、属性 SQL_ATTR_OUTPUT_NTS の 現行値を取り出します。
SQLINTEGER output_nts,autocommit;
rc = SQLGetEnvAttr(henv, SQL_ATTR_OUTPUT_NTS, &output_nts, 0, 0);
CHECK_HANDLE( SQL_HANDLE_ENV, henv, rc );
printf("¥nNull Termination of Output strings is: ");
if (output_nts == SQL_TRUE)
 printf("True¥n");
else
 printf("False¥n");