COMMAND

モニター・プログラムで COMMAND 機能を使用して、計測機能インターフェース (IFI) からコマンドを発行することができます。

プログラム固有のプログラミング・インターフェース情報の開始
以下のトレース・コマンドを含む、Db2® コマンドを実行依頼できます。
  • START TRACE
  • STOP TRACE
  • DISPLAY TRACE
  • MODIFY TRACE

コマンドは、非同期に実行することも、同期して実行することもできます。 IFCA でビットを設定して、IFI でのコマンドの実行方法を指定することができます。これによって影響を受けるコマンドは以下のとおりです。

  • ALTER BUFFERPOOL
  • SET LOG
  • STOP DATABASE
  • SET SYSPARM

許可

処理の 1 次許可 ID または 2 次許可 ID のいずれかに、コマンドを発行するための適切な許可が必要です。この許可がないと、要求は拒否されます。アプリケーション・プログラムが Db2 コマンドを出す許可を持っていても、READA 要求を 出す許可は持っていないという場合もあります。

データ共用グループでは、コマンドが IFI インターフェースを介して発行され、コマンドを発行したメンバーとは異なるデータ共用メンバーで実行される場合、そのコマンドは、IFI 呼び出しを発行したアプリケーション処理のユーザー ID で実行されます。

構文とオプション

COMMAND 機能の呼び出し構文は以下のとおりです。

CALL DSNWLI,('COMMAND ',ifca,return-area,output-area,buffer-info .),VL
ifca

IFCA (計測機能連絡域) は、戻りコードおよび理由コードを入れる ストレージ域です。IFCA は次の情報を示します。

  • 要求の成功または失敗
  • コマンドを実行した Db2 コンポーネントからの診断情報
  • 戻り域に移動されたバイト数
  • 戻り域に収まらなかったメッセージ・セグメントの バイト数

一部のコマンドでは、非ゼロの戻りコードまたは理由コードにもかかわらず、 有効な情報を戻す場合があります。例えば、DISPLAY DATABASE コマンドでは、許容された量 より多くの情報が戻された可能性があることを示す場合があります。

複数のエラーが発生した場合には、最後のエラーが呼び出し元に戻されます。 例えば、コマンドに エラーが発生しておりエラー・メッセージがこのエリアに収まらない場合は、エラー戻りコードおよび理由コードは、 戻り域が小さ過ぎることを示します。

モニター・プログラムが START TRACE を発行した場合には、IFCA の所有権 トークン (IFCAOWNR) により、非同期バッファーの所有者が判別されます。 バッファーの所有者だけが、後続の READA 要求を実行することによって データを獲得する処理を行えます。

return-area
実行されたコマンドが処理を終了すると、そのコマンドは メッセージ (存在する場合) を戻り域に入れます。 メッセージは可変長レコードとして保管され、レコードの総バイト数 が IFCA の IFCABM (移動されたバイト数) フィールドに保管されます。 戻り域が小さ過ぎると、保管できるだけのメッセージ・レコードが戻り域に 保管されます。

モニター・プログラムで、コマンド機能が戻したメッセージを 分析する必要があります。

output-area
可変長コマンドが入ります。
buffer-info
このパラメーターは、OP バッファーに対するトレースを開始する場合に必要です。 それ以外の場合は、不要です。 このパラメーターは、COMMAND 要求でのみ使用されます。 このパラメーターは、割り当てられていない OPn 宛先バッファー への IFI 呼び出しによりトレースが始動されるとき、処理オプションに関する 情報が含まれるエリアを指します。 OPn 宛先バッファーは、モニター・プログラムにより所有されていない 場合は、割り当てられていないものと見なされます。

OPn 宛先バッファーが割り当てられていると、 バッファー情報域は、その OPn 宛先に対する 後続の START または MODIFY TRACE コマンドでは使用されません。

START TRACE に buffer-info を指定する場合は、 モニター・プログラム ECB に対しポストされる前にバッファーに 入れることができるバイト数を指定することができます。 収集されたトレース・データ量がバイト・カウント・フィールドに指定されている 値に達すると、ECB に対しポストされます。バイト・カウント・フィールドは、バッファー情報域の中でも指定されます。

次の表は、バッファー情報域のフィールドを要約したものです。

表 1. バッファー情報域のフィールド. このエリアは、アセンブラー・マッピング・マクロ DSNDWBUF によりマップされます。
名前 16 進オフセット データ・タイプ 説明
WBUFLEN 0 符号付き 2 バイトの整数 バッファー情報域の長さ + 4。ゼロは、このエリアが存在していない ことを示します。
  2 符号付き 2 バイトの整数 予約済み
WBUFEYE 4 文字、4 バイト ブロックの目印 (WBUF)
WBUFECB 8 アドレス バッファーがバイト・カウント指定 (WBUFBC) に達したときにポスト処理を実行する ECB アドレス。ECB は、モニター・キー機構のストレージに常駐していなければなりません。

ゼロは、モニター・プログラムへのポストを行わないことを示します。 この場合、モニター・プログラムは自身のタイマーを使用し、READA 要求を 出す時期を決定する必要があります。

WBUFBC C 符号付き 4 バイトの整数 計測機能に渡されるレコード数は、ECB に対してポストされる前に、 この値に達していなければなりません。 この数字がゼロで、ECB が存在している場合は、バッファーが いっぱいになった時点でポストされます。

COMMAND 機能の呼び出し例

以下の例では、MONITOR クラス 1 について Db2 START TRACE コマンドが 出されています。

図 1. IFI によるトレースの始動
CALL DSNWLI,('COMMAND ',IFCAAREA,RETAREA,OUTAREA,BUFAREA),VL
⋮
COMMAND DC CL8 'COMMAND '
************************************************************************
* Function parameter declaration                                       *
************************************************************************
* Storage of LENGTH(IFCA) and properly initialized                     *
************************************************************************
IFCAAREA  DS       0CL180
⋮
************************************************************************
* Storage for length and returned info.                                *
************************************************************************
RETAREA   DS      CL608
************************************************************************
* Storage for length and Db2 Command                                   *
************************************************************************
OUTAREA   DS      0CL42
OUTLEN    DC      X'002A0000'
OUTCMD    DC      CL38'-STA TRAC(MON) DEST(OPX) BUFSIZE(1024)'
************************************************************************
* Storage of LENGTH(WBUF) and properly initialized                     *
************************************************************************
BUFAREA  DS       0CL16
⋮

プログラム固有のプログラミング・インターフェース情報の終了