ジョブ･アカウンティングおよびジャーナル・エントリー取得用API
IBM i上のアクティビティ、リソース割り当て、セキュリティまたは監査に関連したイベントを監視、登録したい場合は、出口ポイント、履歴ログ、システム・メッセージ・キュー、システム・ジャーナルなど多くの選択肢があります。これらの機能はいずれも、関連する情報をフィルタリングして提示する以上の追加の費用を必要とせずシステム上ですぐに利用できます。実運用環境において負荷が最大の状態で稼働しているIBM iシステムは山のような情報を生成しているので、貴重な知識を収集しIBM iシステムを適切に管理するのに必要な制御にはAPIプログラマのスキルが必要かもしれません。
本稿では、Retrieve Journal Entries (QjoRetrieveJournalEntries) APIを使用してシステム・アカウンティング・ジャーナルQACGJRNからジョブ・リソース情報を即座に取得して選択する方法について説明します。この演習の要点にはQjoRetrieveJournalEntries APIについて例で説明する部分と、取得したシステム情報をCLコマンド・インタフェースとユーザー・インタフェース・マネージャ(UIM)リスト・パネルを介してアクセス可能で有用なものにする方法の例を提供する部分とがあります。そのためにAnalyze Job Accounting Journal (ANZJOBACG)コマンドを作ってみました。
ジョブ・アカウンティングの設定
ジョブ・アカウンティングを設定するには以下の手順を実行し、コマンドライン・インタフェースを使って指定されたコマンドを入力します。
- ジャーナル・レシーバーを作成 レシーバーの名前には数字の接尾辞を付けて(たとえばACGJRN0001)、追加のレシーバー(たとえばACGJRN0002、ACGJRN0003)をCHGJRN JRNRCV(*GEN)コマンドで作成できるようにしておくことをお勧めします。
- ジョブ･アカウンティング･ジャーナルを作成しQSYS/QACGJRNという名前をつける QSYSライブラリにオブジェクトを追加できる権限を所有していなければなりません。
ジャーナル･レシーバーは上記ステップ1で作成したレシーバーと同じものでなければなりません。*EXCLUDE権限を使用すると収集されたデータを使ってリソースを使用するユーザーに課金できるので、*EXCLUDE権限をお勧めします。 - ジャーナル･アカウンティング情報(QACGLVL)システム値を変更 この値をジャーナル・ジョブ・アカウンティング情報、またはプリンター情報、もしくはその両方にセットすることができます。*JOBはジョブ(JB)ジャーナル・エントリーを生成するのに対して、*PRINTは直接印刷(DP)ジャーナル・エントリーまたはスプール印刷(SP)ジャーナル・エントリーを生成します。
- 各ユーザー・プロファイル用のアカウンティング・コード・パラメーターACGCDEを設定 アカウンティング・コードには15文字までの長さの任意の英数字を設定することができます。
Change Job Description (CHGJOBD)コマンドまたはCreate Job Description (CRTJOBD)コマンドを使用するとユーザーのグループ用のアカウンティング・コードを指定することもできます。
ジョブ記述用のデフォルトのアカウンティング・コードは＊USRPRFで、ジョブ記述がジョブのユーザー・プロファイルからのアカウンティング・コードを使用することを意味します。ジョブ記述中の値が＊USRPRF以外の時は、ユーザー・プロファイルで指定されているアカウンティング・コードよりも優先してその値が使用されます。
*JOBタイプのジョブ・アカウンティングを有効にした後は、システム上でジョブが終了するたびにジャーナル・エントリーがジョブ・アカウンティング・ジャーナルに記録されます。ジョブ・アカウンティング・ジャーナル・エントリーにはジョブの処理や使用したリソースについての情報が格納されています。この情報にはジョブ・エントリー、開始および終了のタイムスタンプ、完了コード、ルーティング・ステップ、対話型トランザクション、CPU処理時間、外部同期入出力、外部非同期入出力、データベース入出力操作、関連するアカウンティング・コードなどが含まれます。ジョブ・アカウンティング情報はジャーナル・エントリーのエントリー固有データ・フィールド(JOESD)に格納されています。
ジャーナル・エントリーの取得
Analyze Job Accountingコマンド処理プログラム(CPP)は、QjoRetrieveJournalEntries APIを使用して要求されたジャーナル・エントリーをQACGJRNジャーナルから取得します。
QjoRetrieveJournalEntriesのパラメーター・リストを図1に示します。
ここでReceiver variableは、APIの3番目のパラメーターQualified journal nameで指定したジャーナルから取得したジャーナル・エントリー・データをAPIが返す場所です。2番目のAPIパラメーターLength of receiver variableは、ジャーナル・エントリー・データを返す空間の大きさをAPIに指示しています。Format nameパラメーターは返されたジャーナル・エントリー・データのフォーマットを定義します。現時点ではRJNE0100とRJNE0200の 2種類のフォーマットがサポートされています(私は後者を使用しました)。
5番目のパラメーターはOptions(*OMIT)と同様に省略可能ですが、複雑なデータ構造をしており、興味の対象となっているジャーナル・エントリーの位置付けと選択をする際に使用する基準を指定することができます。サポートされているパラメーターはDisplay Journal (DSPJRN)コマンドが提供するパラメーターに対応していますが、データ構造のフォーマットはコマンド・プロンプトと比べてきわめて異なるものになっています。私は(IBM i 7.1上の)CPPで最初の16個のパラメーター・サブ構造を定義して含めましたが、APIは全部で23個の基準をサポートしています。パラメーター構造フォーマット(RPG IVでのFROMTIMEおよびTOTIME基準のようなもの)の例を図2に示します。
ジャーナル・エントリー取得の開始と終了を示したタイムスタンプをCPPが計算した後は、QjoRetrieveJournalEntries APIを呼び出す前に以下の2つのパラメーターを設定します。
要求されたジャーナル・エントリーを全て取得するプロセスには潜在的に次の2つのステップが含まれます。
- 開始点の確立 位置付けパラメーターには開始ジャーナル・レシーバーと、日付と時刻を表す値かまたはジャーナル・エントリーが要求されたオフセットを示すジャーナル・エントリーの通し番号のどちらかが含まれています。
- ジャーナル・エントリーの継続取得 レシーバー変数が格納できる以上のジャーナル・エントリーが存在する場合は、APIは継続したジャーナル・レシーバーとジャーナル・エントリーの通し番号を返します。次にこの値を次回のAPI呼び出しの際に対応するパラメーターにジャーナル・エントリー取得オフセットとして渡します。
この方法は、QjoRetrieveJournalEntries APIを最初に呼び出すときに、Starting date and time (FROMTIME)パラメーター(JrnVarR03)を指定した方が良いということを示唆しています。そうすることで、ステップ2のように、以後のAPI呼び出しでこのパラメーターをStarting sequence number (FROMENT)パラメーター(JrnVarR02)で置き換えてくれます。
ANZJOBACGコマンド
図3にANZJOBACGコマンドのプロンプトを示します。DSPJRNコマンドから認識されるもっとも重要なパラメーターの一部を明らかにするだけでなく、処理対象のジャーナル･エントリーの主要なスコープを指摘することで、ジャーナル･エントリーのエントリー固有データ部分にあるジョブ・アカウンティング・データに関連するいくつかの選択基準も追加しました。このパラメーターは、ジョブ・タイプ、アカウンティング・コード、ジョブ完了コード、およびCPU消費時間、対話型トランザクション、実行された外部入出力操作などといったジョブ処理統計に基づいてジャーナル・エントリーの選択を絞り込んでいきます。
次に示す例は、ANZJOBACGコマンドがユーザー・プロファイルCARSTENによって2012年9月22日から2012年9月29日までの週に実行された対話型ジョブを探しています。
システム・アカウンティング・ジャーナル・レシーバーの保持期間をCLEANUPメニューのオプション1 、Change cleanup optionsで制御することができる点に注意してください。図4のプロンプトでは、アカウンティング・ジャーナル(および他のシステムのジャーナル)のレシーバーを維持したい日数を指定します。この設定で影響を受けるすべてのジャーナルがヘルプ・テキストで説明されています。アカウンティング・ジャーナルに格納されている情報の重要度(つまり、部門に請求される実際の費用、監査回復の可能性)に応じて、システム・アカウンティング・ジャーナル・レシーバーを日次のバックアップに含めることも検討した方が良いでしょう。
図5はAnalyze Job Accounting Journalリスト・パネルで、ANZJOBACGコマンドの実行結果を示しています。このパネルで利用可能なリストのオプションにはDisplay entry details、Print entry details、Display Job、Work with User profile、Display journalなどがあります。
F8キーを押すとシステム・アカウンティング・ジャーナルQACGJRNに対してWork with Journal Attributesオプションが実行され、F11を押すと3つのリスト・ビューを切り替えることができ、F22を押すとアカウンティング・コードがリスト行の幅を超えたときにアカウンティング・コードの値全体を表示してくれます。詳細についてはオンライン・ヘルプを参照してください。Display Job Accounting Journal Entryパネルの例を図6に示します。ここでもカーソルに反応するヘルプ・テキストが利用可能で、ディスプレイ・パネル中の全てのセクションとフィールドについての説明が利用可能です。
