9.195 SET_SESSION_VALUE

注意: 9.1 組み込み関数の規則      利用オプション

この組み込み関数を使用すると、Visual LANSAのセッション値を実行アプリケーションによって動的に変更することができます。

セッション値への変更は、そのセッション(X_RUNコマンド)が実行を完了すると無効になることに注意してください。

詳細は、「標準X_RUNパラメータ」を参照してください。

 

引数

番号 タイプ 必須/任意 記述 最小長 最大長 最小小数桁数 最大小数桁数 1 A 必須 設定またはリセットされるセッション値の名前。現在、この組み込み関数によって次のセッション値を設定またはリセットすることができます。 USER：現在のユーザー - IBM iでは変更できません。USERを設定すると、USEX (サーバーへの接続時のデフォルト・ユーザーID)も設定されます。「セッション値USER=、GUSR=、およびUSEXに関する技術上の注記 」を参照してください。 GUSR：現在のグループ・ユーザー - IBM iでは変更できません。 USER_AUDIT：ユーザー編集スタンプで使用されるユーザー。IBM iで明示的に設定されている必要があります。 Visual LANSAで変更しても、スーパーサーバー・アプリケーション内でIBM iは更新されません。 PRTR：現在のプリンター PPTH：プリンター・ファイル用の現在の完全修飾ディレクトリ JOBPTY：ジョブ待ち行列の優先順位 DBMS_OPTIMIZE：大量のDBMSアクティビティの最適化 CONNECT_PARTITION： CONNECT_SERVER組み込み関数によって使用されるデフォルトの区画 DPTH：エミュレートされたIBM i データ待ち行列が作成/アクセスされるディレクトリ EXPS：オブジェクト・セキュリティ・レコードのインポート時に実行されるアクション HELP：使用するヘルプ・システム HLPF：使用するヘルプ・ファイル HMJB：現在のアプリケーションがホスト・モニターのジョブであるかどうかを識別します。YまたはN。LANSA開発チーム専用に予約されています。 LANG：現在実行中の言語を変更します。このセッション値には、LANSAの内部作業に関する詳しい知識が必要なため、LANSA開発チームによって作成されたアプリケーションだけに使用が制限されます。 ITRO などすべてのトレース・パラメータ。これは、問題が発生したときだけトレースを有効にする場合に役立ちます。これによって、トレース・ファイルのサイズを最小限に抑えることができます。 PSRA =：一次サーバー経路権限。PSRA=Yを設定することによって、権限チェックがサーバーにルーティングされることを示します。 このコマンドを使用して、実行中に値を設定します。値の設定は、接続を定義して確立する前に行ってください(X_RUN パラメータ詳細の「PSRA (プライマリ・サーバー・ルート証明機関)」に記載されている注意点を参照してください)。 PSRR：一次サーバー経路リポジトリ。PSRR=Y(デフォルト)を設定することによって、リポジトリのデータがローカルで取得できない場合、そのデータを取得するために要求がサーバーに送信されることを示します。 このコマンドを使用して、実行中に値を設定します。値の設定は、接続を定義して確立する前に行ってください(X_RUN パラメータ詳細の(a href="depb3_0000.htm")「PSRA (プライマリ・サーバー・ルート証明機関)」に記載されている注意点を参照してください)。 UDEF：スペースを含むユーザー定義の値(最大256バイト)。値にスペースが含まれている場合、または埋め込み引用符を使用する場合は、引用符で囲んでください。この場合、使用可能な長さは254バイトになります。注：埋め込み引用符はすべて一重引用符でなければなりません。二重引用符を使用すると、送信されたジョブが失敗します。 WPEN、 WPPN、WPPS、WPPD、WPFD、WPDF、WPDS、WPFO、WPASなどのWindowsの拡張印刷パラメータをこのパラメータで指定することができます。引数2で指定する値は、コマンド行でWindowsの拡張印刷パラメータを使用する際に適用されるものと同じ規則に従わなければなりません((a href="depb3_0090.htm")「Windows拡張印刷パラメータ」</a>を参照してください)。 XCMD：パスワードなどの特定パラメータ値を隠します。このパラメータは、設定後に送信されたジョブに対してのみアクティブになります。 CIPH： LANSAからOPenSSLを呼び出す際に使用する対称鍵暗号 1 50     2 A 必須 セッション値が設定またはリセットされる値。詳細については、以下の「技術上の注記」を参照してください。 1 256

戻り値

戻り値はありません。

技術上の注記 (全般)

• 指定したセッション値の名前 (例：USER) は、妥当性検査の前に大文字に変換されます。

• 等号を使用しなくても、セッション値を指定することができます。例えば、USER=とUSERは両方とも有効で、同一とみなされます。

• 指定する実際の値は、大文字に変換される場合があります。詳細については、セッション値ごとの注記を参照してください。

• ブランクまたはNULLを値に指定することはできません。これ以外の値はすべて受け入れられます。この組み込み関数に渡す値の整合性と正しさを確認するのはユーザーの役割です。無効または不適切な値を指定すると、現在のプラットフォームまたは関連するサーバーのプラットフォームでアプリケーション・エラーまたは予測不可能な結果が生じる可能性があります。

• この組み込み関数は、各種設定を行い、実際のアプリケーションに制御を渡す「エントリー・ポイント」ファンクションとして呼び出しスタックで使用するために設計されています。

• セッションの設定が変更されると、その変更はそのセッション (x_runコマンド) が実行を完了するまで有効です。変更されたセッション値は、続いて呼び出されるすべての機能に対して有効です。

• セッション値が変更されても、すでにアクティブになっているファンクション、OAM、通信セッションはその変更を無視する場合があります。次に、「すでにアクティブである」という概念の非常に簡単な例を挙げます。

      define #chguser reffld(#user)

      begin_loop 

         request #chguser 

         use set_session_value with_args('user=' #chguser)

         display #user 

               end_loop

    このファンクションは、変更されたユーザーを表示しません。ファンクションが最初に呼び出されたときの#user(*USERからのデフォルト)を表示します。デフォルトとなるシステム変数*USERは、静的で、ファンクション起動時にのみ初期化されます。

• 以下に示す特定のセッション値に関する技術上の注記では、「特定の使用法」が指示される場合があります。特定の使用法が指示されている場合は、この組み込み関数をそれ以外のコンテキストで使用しないでください。

• この組み込み関数の使用法が無効または不適切な場合、現在のプラットフォームまたは関連するサーバーのプラットフォームでアプリケーション・エラーまたは予測不可能な結果が生じる可能性があります。

セッション値USER=、GUSR=、およびUSEXに関する技術上の注記

• このセッション値は、最上位レベルのエントリー・ポイント・ファンクションで使用します。このセッション値を使用することで、独自の「サイン・オン」ファンクションを設計し、実装することができます。ユーザー・プロファイルが確定された後で、現在のユーザー・プロファイルとグループ・プロファイルの値を変更することができます。

• このセッション値は、実行アプリケーションに点在するユーザーの複数の変更をサポートするためのものではありません。このようなアプローチを使用してアプリケーションを設計または実装しないでください。

• USER =またはGUSR=に指定する値は、x_runコマンドで定義されているルールに従う必要があります。関連するグループ・ユーザーのプロファイルがない場合の正しい値は、*NONEです。

• 指定した値は必ず大文字に変換されます。

• USER を設定すると、USEXも設定されます。値は、大文字/小文字が維持される変数で渡す必要があります。渡した値は、まずUSEXを設定するために使用され、その後、大文字に変換されて、USERが設定されます。
  USEXは、サーバーへの接続を確立する際に使用されるデフォルトのユーザーIDです。一部のサーバーでは、大文字/小文字の区別が重要になるため、USEXを使用することで、1箇所でデフォルトを変更しながら、セキュリティ・アクセスを適切に制御することができます。ユーザーIDがX_RUNに渡されると、この組み込み関数の現在の動作と同じように、正確な大文字/小文字でUSEXパラメータに設定されます。

セッション値USER_AUDITに関する技術上の注記

• このセッション値は、ユーザー編集スタンプで使用されるユーザーを設定するために使用できます。また、すべてのユーザー・ジョブがデフォルトのWebユーザー・プロファイルで実行されるWebジョブなど、現在のユーザーが十分に差別化されない場合に使用することもできます。

• このセッション値は、最上位レベルのエントリー・ポイント・ファンクションで使用します。

• このセッション値は、実行中のアプリケーションに点在するユーザー編集の複数の変更をサポートするためのものではありません。このようなアプローチを使用してアプリケーションを設計または実装しないでください。

• この値は、システム変数*USER_AUDITによって取得できます。

• この値に対して大文字への変換は行われません。

• 事実上、編集ユーザーの設定は、セッションの実行が完了するまで維持されます。

• Visual LANSA (Windows、IBM i RDMLX、およびLinux上)では、セッションは、x-runコマンドが完了するまで存続します。

• IBM i RDMLでは、事実上、セッション値は、ジョブが終了するかLANSA区画が変更されるまで維持されます。

• LANSA の Webジョブでは、ジョブがタイムアウトになり、他のジョブによって要求が処理される可能性があるため、セッション値は、ブラウザーの対話処理ごとに設定する必要があります。

• バッチ・ジョブにより新しいセッションが開始されるため、バッチ・ジョブ・セッションに対して編集ユーザーを設定する必要があります。

• *LONG_USER_AUDIT が ON の場合、監査スタンプで使用する値の設定に、セッション値の 256 文字が使用されます。それ以外は、セッション値の 10 文字がこの値の設定に使用されます。

セッション値PRTR=とPPTH=に関する技術上の注記

• セッション値PRTR=は、レポートが出力される論理プリンターの名前を変更するためにレポート・ファンクションで使用します。

• セッション値PRTR=は、すべてのレポートをファイルに出力する場合のレポート・ファンクションでも使用することができます。特殊な値*PATHを指定し、セッション値PPTH=も使用する必要があります。

• PRTR =に指定する値は、x_runコマンドで定義されているルールに従う必要があります。

• PPTH =に指定する値は、x_runコマンドで定義されているルールに従う必要があります。

• 指定した値は大文字に変換されません。Linuxシステムでは、これを考慮する必要があります。

セッション値JOBPTY=に関する技術上の注記

• このセッション値は、このジョブ(現在実行中のジョブ)から投入されたジョブの待ち行列の優先順位を制御するために使用します。x_run環境が起動している場合、このデフォルトは5に設定されます。この値は、IBM iのバッチ・ジョブ待ち行列とサブシステムのエミュレーションでのみ使用してください。また、これ以外のコンテキストで使用しても意味がありません。

• JOBPTY =に指定する値は、0 -> 9の範囲の整数値である必要があります。最も低いJOBPTY値で投入されたジョブが、エミュレートされたジョブ待ち行列から最初に実行されます。 JOBPTY値が等しいジョブは、到着順に実行されます。

• この機能を使用する前に、『Visual LANSA アプリケーションの配布ガイド』の「IBM i ジョブ待ち行列エミュレーション」をお読みください。

セッション値CONNECT_PARTITION=に関する技術上の注記

• このセッション値は、次のCONNECT_SERVER組み込み関数の呼び出しによってサーバー・システム上で接続される区画識別子を変更するために使用します。このセッション値は、組み込み関数CONNECT_SERVERを呼び出す前に設定する必要があります。設定された値は、X_RUNコマンドが終了するまで、またはこの組み込み関数によって別のCONNECT_PARTITION値が指定されるまでの間有効です。

• 値の引数(引数2)で指定されるこのセッション値は、サーバー・システム上の有効な区画の3文字の識別子である必要があります。

• 指定した値は必ず大文字に変換されます。

セッション値DBMS_OPTIMIZE=に関する技術上の注記

移植性に関する考慮事項

IBM i上で実行されるRDMLXコードでこの組み込み関数を使用する場合は、COMMITを実行して、コミット制御を開始する必要があります。

• セッション値DBMS_OPTIMIZEは、大量または複雑なDBMSトランザクションを最適化する方法を指定するために使用します。
  
  このオプションを適切に使用することによって、大量または複雑なDBMSアクティビティのパフォーマンスを大幅に向上することができます。
  
  この値パラメータは、大文字で指定する必要があり、次のように設定されます。

BEGIN_SYNC_nnnn	複雑なDBMSアクティビティの開始を指定し、DBMS最適化モードをオンに切り替えます。「ハード」コミットは、"nnnn"回の「ソフト」同期ポイントの呼び出しごとに実行されます。
SYNC_POINT	複雑なDBMSアクティビティの「ソフト」同期ポイントを指定します。ソフト同期ポイントは、「最適化された」コミット制御の境界に相当します。
END_SYNC	複雑なDBMSアクティビティの終了を指定し、DBMS最適化モードをオフに切り替えます。

DBMS_OPTIMIZEの使用法は、例をもとに説明します。

次の単純なRDMLファンクションについて考えてみます。

begin_loop from(1) to(2000) 

       insert fields(......) to_file(testfile) 

end_loop

通常の環境では、このファンクションは自動コミットを使用し、1回の挿入ごとにDBMSコミット操作を実行します。

通常、多くのDBMSコミット操作は非常に低速です。コミットは、このようなアプリケーション(すなわち、同じ操作を5回や10回ではなく数千回も繰り返すアプリケーション)のパフォーマンスに非常に大きく影響する可能性があります。

ファンクションを次のように変更します。

use set_session_value ( DBMS_OPTIMIZE BEGIN_SYNC_100 )

begin_loop from(1) to(2000)

   insert fields(......) to_file(testfile)

   use set_session_value ( DBMS_OPTIMIZE SYNC_POINT )

end_loop

use set_session_value ( DBMS_OPTIMIZE END_SYNC )

これによって、このファンクションは以前より速く実行される可能性があります。DBMS_OPTIMIZE操作によって、基となるOAM(オブジェクト・アクセス・モジュール)がトランザクションをより適切に解析し、それによってトランザクションを最適化できるようになります。

パフォーマンスが向上する最大の理由は、「ソフト」SYNC_POINTが100回実行されるごとに、「ハード」、つまり実際のDBMSコミット操作が発行されるためです。このため、BEGIN_SYNC_100という値が使用されています。これによって、DBMSトランザクション全体の処理が速くなります。

もう1つの例として、次の「バッチ」形式のファンクションを挙げます。

select fields(.....) from_file(customer) where(.......)

   select fields(.....) from_file(orders) with_key(customer)

       call *direct calculate

       select fields(.....) from_file(items) with_key(orderno) 

              update fields(.....) in_file(items) 

       endselect 

       update fields(.....) in_file(orders) 

  endselect 

endselect

このバッチ形式のプログラムを次のように変更することによって、そのパフォーマンスを向上させることができます。

use set_session_value ( DBMS_OPTIMIZE BEGIN_SYNC_20 )

 select fields(.....) from_file(customer) where(.......)

   select fields(.....) from_file(orders) with_key(customer) 

     call *direct calculate 

     select fields(.....) from_file(items) with_key(orderno)

           update fields(.....) in_file(items) 

   endselect 

   update fields(.....) in_file(orders) 

 endselect 

use set_session_value ( DBMS_OPTIMIZE SYNC_POINT ) endselect

use set_session_value ( DBMS_OPTIMIZE END_SYNC )

次に、DBMS_OPTIMIZEを使用するときに理解しておく必要がある項目および従う必要があるルールを示します。

BEGIN_SYNC_nnnn

• 大文字で指定する必要があります。

• BEGIN_SYNC_nnnn が現在のジョブですでにアクティブな場合、異常終了します。BEGIN_SYNC_nnnn操作をネストすることはできません。

• 指定された"nnnn"値に同期「トリガー」を設定します。"nnnn"は、1から1000までの有効な整数でなければなりません。
  
  "nnnn"を1に設定すると、パフォーマンスが向上する可能性は低くなります。それは、SYNC_POINTが実行されるごとにコミット操作が発行されるためです。

• 同期ポイントの「カウンター」をゼロに設定します。

• DBMS 最適化モードをオンに切り替えます。

• すべての「自動コミット」オプションをオフに切り替えます。すべてのDBMSテーブルは、そのテーブルの定義に関係なく、完全に手動コミットによって制御されます。手動コミットは、次の場合に発行されます。

• ·SYNC_POINT がトリガー・レベルに到達した場合

• ·END_SYNC が実行された場合

• ·RDML ファンクションによってCOMMIT操作が発行された場合

• DBMS トランザクションの正常終了を示すために必ず実行されるEND_SYNC操作が必要です。

• コミット制御の境界のポイントを指定するSYNC_POINT操作を指定することができます。SYNC_POINTが指定されていない場合、END_SYNC操作が1つのコミット制御の境界として機能します。

• 通常、"nnnn" の値が大きくなるほど、パフォーマンスが向上します(DBMSおよびジャーナルの制限内で)。ただし、500を超える値は一般的ではありません。値が大きくなるほど、保持/ロックされるシステム・リソースが増え、ロールバック・イベントが発生したときに失われるデータの量が増加します。

• コミット境界を確定するため、およびパフォーマンスを最適化するために、単純かつ適切な方法でSYNC_POINTとEND_SYNCを使用してください。BEGIN_SYNC、SYNC_POINT、およびEND_SYNC操作を複数のファンクションにまたがって、複雑な呼び出しスタックで使用することは避けてください。すべての操作を1つのファンクションに限定し、単純で適切に区切られた境界を維持するようにしてください。

• 複数の異なるRDMLファンクションとファンクション呼び出しが伴う複雑な呼び出しスタックで使用しないでください。この主な理由は、呼び出されたファンクションがCOMMITを発行(またはコミットが実行される原因となるアクションを実行)することによって、このオプションによって得ることができるパフォーマンスの利点が失われる可能性が高いためです。

• LANSA SuperServerモードで使用した場合、効果は何もありません。

• 16 個以上のテーブルに同時にアクセスするジョブでは、この機能を使用しないことをお勧めします。

SYNC_POINT

• 大文字で指定する必要があります。

• DBMS 最適化モードが現在オフの場合、異常終了します。

• 同期ポイントの「カウンター」を増やします。

• 同期ポイントの「カウンター」が同期「トリガー」の値以上の場合、DBMSコミット操作が実行され、カウンターはゼロにリセットされます。

• LANSA SuperServerモードで使用された場合でも、コミットを発行します。

END_SYNC

• 大文字で指定する必要があります。

• DBMS 最適化モードが現在オフの場合、異常終了します。

• 無条件にDBMSコミットを発行します。

• 同期ポイントのカウンターをゼロにリセットします。

• 同期トリガーをデフォルトにリセットします。

• DBMS 最適化モードをオフに切り替えます。

LANSA SuperServerモードで使用された場合でも、コミットを発行します。