SQLSetEnvAttr - 環境属性の設定

SQLSetEnvAttr() は、現在の環境の環境属性を設定します。

構文

接続ハンドルが割り振られている場合、環境属性は設定できません。 属性を CLI 環境全体に適用するためには、その最初の接続を行う前に、環境属性を設定する必要があります。 そうしないと、HY010 エラー・コードが戻されます。

SQLRETURN SQLSetEnvAttr  (SQLHENV      henv,
                          SQLINTEGER   Attribute,
                          SQLPOINTER   Value,
                          SQLINTEGER   StringLength);

関数引数

表 1. SQLSetEnvAttr の引数
データ・タイプ 引数 使用法 説明
SQLHEN henv 入力 環境ハンドル。
SQLINTEGER Attribute 入力 設定する環境属性。詳細については、表 2を参照してください。
SQLPOINTER Value 入力 Attribute に該当する値。
SQLINTEGER StringLength 入力 属性値が文字ストリングの場合、 バイト単位の Value の長さ。 Attribute がストリングでない場合、 DB2® for i CLI は StringLength を無視します。

使用法

現行アプリケーションが CLI を使用する他のアプリケーションと同じジョブに含まれる可能性がある環境では、環境属性の代わりに接続属性を使用します。接続属性を使用せずに環境属性を設定すると、他のアプリケーションが予期しない動作をする恐れがあります。理想としては、SQL_ATTR_ENVHNDL_COUNTER および SQL_ATTR_SERVER_MODE 以外の環境属性は使用しないようにします。

変更の始まり
表 2. 環境属性
属性 内容
SQL_ATTR_DATE_FMT 32 ビット整数値。以下のいずれかになります。
  • SQL_FMT_ISO – 国際標準化機構 (ISO) の日付形式 yyyy-mm-dd を使います。これはデフォルトです。
  • SQL_FMT_USA – 米国の日付形式 mm/dd/yyyy を使います。
  • SQL_FMT_EUR - ヨーロッパ日付形式 dd.mm.yyyy を使います。
  • SQL_FMT_JIS – 日本工業規格の日付形式 yyyy-mm-dd を使います。
  • SQL_FMT_MDY - 日付形式 mm/dd/yy を使います。
  • SQL_FMT_DMY - 日付形式 dd/mm/yy を使います。
  • SQL_FMT_YMD – 日付形式 yy/mm/dd を使います。
  • SQL_FMT_JUL - 年間通算日の形式 yy/ddd を使います。
  • SQL_FMT_JOB – ジョブのデフォルトを使います。
SQL_ATTR_DATE_SEP 32 ビット整数値。以下のいずれかになります。
  • SQL_SEP_SLASH – スラッシュ ( / ) を日付区切り記号に使います。これはデフォルトです。
  • SQL_SEP_DASH – ダッシュ ( - ) を日付区切り記号に使います。
  • SQL_SEP_PERIOD – ピリオド ( . ) を日付区切り記号に使います。
  • SQL_SEP_COMMA – コンマ ( , ) を日付区切り記号に使います。
  • SQL_SEP_BLANK – ブランクを日付区切り記号に使います。
  • SQL_SEP_JOB – ジョブのデフォルトを使います。

区切り記号は以下の SQL_ATTR_DATE_FMT 属性タイプにのみ適用されます。

  • SQL_FMT_MDY
  • SQL_FMT_DMY
  • SQL_FMT_YMD
  • SQL_FMT_JUL
SQL_ATTR_DECIMAL_SEP 32 ビット整数値。以下のいずれかになります。
  • SQL_SEP_PERIOD – ピリオド ( . ) を小数点区切り記号に使います。これはデフォルトです。
  • SQL_SEP_COMMA – コンマ ( , ) を小数点区切り記号に使います。
  • SQL_SEP_JOB – ジョブのデフォルトを使います。
SQL_ATTR_DEFAULT_LIB 未修飾のファイル参照を解決するのに使われるデフォルト・ライブラリーを指示する文字値。
SQL_ATTR_ENVHNDL_COUNTER 32 ビット整数値。以下のいずれかになります。
  • SQL_FALSE – DB2 for i CLI は、 環境ハンドルが割り振られる回数をカウントしません。 したがって、最初の呼び出しによって、環境ハンドルとそれに関連したすべてのリソースが解放されます。
  • SQL_TRUE – DB2 for i CLI は、環境ハンドルが割り振られる回数のカウンターを保存します。 環境ハンドルの解放ごとに、カウンターは減ります。 カウンターがゼロに達して初めて DB2 for i CLI は、ハンドルとそれに関連したリソースを実際に解放します。 そのため、CLI を使ってプログラムに対して、 CLI 環境ハンドルの割り振りと解放のためのネストされた呼び出しを行うことができます。
SQL_ATTR_ESCAPE_CHAR SQLColumns( ) または SQLTables( ) に検索パターンを指定する のに使用するエスケープ文字を指示する文字値。

SQL_ATTR_ESCAPE_CHAR は、接続属性 SQL_ATTR_OLD_MTADTA_BEHAVIOR が SQL_TRUE に設定されている場合にのみ尊重されます。
SQL_ATTR_FOR_FETCH_ONLY 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – カーソルは読み取り専用で、位置指定更新または削除操作には使用できません。これはデフォルトです。
  • SQL_FALSE – カーソルを位置指定更新または削除操作に使用できます。

また、SQLSetStmtAttr() を使って、 個々のステートメントごとに属性 SQL_ATTR_FOR_FETCH_ONLY を設定することもできます。
SQL_ATTR_INCLUDE_NULL_IN_LEN 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – ヌル終止符が存在する場合は、出力文字情報について戻される長さの値にヌル終止符を含めます。実際の出力ストリングにヌル終止符を含める場合は、環境属性 SQL_ATTR_OUTPUT_NTS を SQL_TRUE に設定する必要があります。これはデフォルトです。
  • SQL_FALSE – ヌル終止符が存在しても、出力文字情報について戻される長さの値にヌル終止符を含めません。
SQL_ATTR_JOB_SORT_SEQUENCE 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – DB2 for i CLI は、ジョブ用に設定されているソート・シーケンスを使います。
  • SQL_FALSE – DB2 for i CLI は、デフォルトのソート・シーケンス (*HEX) を使います。
SQL_ATTR_NON_HEXCCSID 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – DB2 for i CLI は、ジョブ CCSID が 65535 に設定されている場合にはジョブ CCSID をジョブのデフォルト CCSID に設定します。
  • SQL_FALSE – DB2 for i CLI は、ジョブ CCSIDを変更しません。これはデフォルトです。
SQL_ATTR_OUTPUT_NTS 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – DB2 for i CLI は、NULL 終了文字を使用して、出力文字ストリングの長さを指示します。 これはデフォルトです。
  • SQL_FALSE – DB2 for i CLI は、NULL 終了文字を使用しません。

この環境 (およびこの環境で割り振られたすべての接続) に呼び出される CLI 関数のうち、文字ストリング・パラメーターを持つすべての CLI 関数は、この属性の影響を受けます。
SQL_ATTR_REQUIRE_PROFILE 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – サーバー・モードにおいて、SQLConnect() および SQLDriverConnect() 関数の実行時にプロファイルとパスワードを要求します。
  • SQL_FALSE – SQLConnect() または SQLDriverConnect() 関数でプロファイルが省略された場合は、現行のユーザー・プロファイルを使用して接続が作成されます。これはデフォルトです。
SQL_ATTR_SERVER_MODE 32 ビット整数値。以下のいずれかになります。
  • SQL_FALSE – DB2 for i CLI は、同じジョブ内のすべての接続の SQL ステートメントを処理します。 すべての変更が、1 つのトランザクションを構成します。 これが、デフォルトの処理モードです。
  • SQL_TRUE – DB2 for i CLI は、別のジョブ内の各接続の SQL ステートメントを処理します。 すると、同じデータ・ソースに対して、それぞれの接続ごとに別々のユーザー ID で、 複数の接続を確立することができます。 また、それぞれの接続ハンドルで行われた変更を分離して、 自身のトランザクションに入れます。 すると、他の接続ハンドルのもとで行われた保留中の変更内容に影響を与えずに、 各接続ハンドルをコミットまたはロールバックさせることができます。 詳細については、サーバー・モードでの DB2 for i CLI の実行を参照してください。
SQL_ATTR_SYS_NAMING 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – DB2 for i CLI は i5/OS® システム命名モードを使います。ファイルは、斜線区切り文字 (/) を使って修飾されます。 修飾されていないファイルは、 ジョブ用のライブラリー・リストを使って解決されます。
  • SQL_FALSE - DB2 for i CLI は、デフォルトの命名モード (SQL 命名) を使います。 ファイルは、ピリオド (.) 区切り文字を使って修飾されます。修飾されていないファイルは、 デフォルト・ライブラリーまたは現在のユーザー ID を使って解決されます。
SQL_ATTR_TIME_FMT 32 ビット整数値。以下のいずれかになります。
  • SQL_FMT_ISO – 国際標準化機構 (ISO) の時刻形式 hh.mm.ss を使います。これはデフォルトです。
  • SQL_FMT_USA – 米国の時刻形式 hh:mmxx を使います。xx は a.m. または p.m. を表します。
  • SQL_FMT_EUR – ヨーロッパの時刻形式 hh.mm.ss を使います。
  • SQL_FMT_JIS – 日本工業規格の時刻形式 hh:mm:ss is を使います。
  • SQL_FMT_HMS – hh:mm:ss 形式を使います。
SQL_ATTR_TIME_SEP 32 ビット整数値。以下のいずれかになります。
  • SQL_SEP_COLON – コロン ( : ) を時刻区切り記号に使います。これはデフォルトです。
  • SQL_SEP_PERIOD – ピリオド ( . ) を時刻区切り記号に使います。
  • SQL_SEP_COMMA – コンマ ( , ) を時刻区切り記号に使います。
  • SQL_SEP_BLANK – ブランクを時刻区切り記号に使います。
  • SQL_SEP_JOB – ジョブのデフォルトを使います。
SQL_ATTR_TRUNCATION_RTNC 32 ビット整数値。以下のいずれかになります。
  • SQL_TRUE – 切り捨てが発生したとき、CLI は SQLFetch()、SQLExtendedFetch()、 および SQLFetchScroll() 戻りコードで SQL_SUCCESS_WITH_INFO を戻します。
  • SQL_FALSE – 切り捨てが発生したとき、CLI は SQLFetch()、SQLExtendedFetch()、 および SQLFetchScroll() 戻りコードで SQL_SUCCESS_WITH_INFO を戻しません。これはデフォルトです。
SQL_ATTR_UTF8 32 ビット整数値。以下のいずれかになります。
  • SQL_FALSE – 文字データは、デフォルトのジョブ・コード化文字セット ID (CCSID) の文字データとして扱われます。これはデフォルトです。
  • SQL_TRUE – 文字データは UTF–8 CCSID (1208) の文字データとして扱われます。
変更の終わり

戻りコード

診断

表 3. SQLSetEnvAttr SQLSTATE
SQLSTATE 説明 解説
HY009 パラメーター値が無効 指定された Attribute は DB2 for i CLI でサポートされていません。

指定された Attribute 値が与えられましたが、 引数 Value に指定されている値はサポートされていません。

引数 pValue が NULL ポインターになっています。
HY010 関数シーケンス・エラー 接続ハンドルがすでに割り振られています。
親トピック: DB2 for i CLI 関数