ToolTalk ttsession トレースは、ToolTalk パターンを ttsession にある各メッセージと一致させ配信する方法を示します。本リリースの ToolTalk トレースは次のことを行います。
単一クライアントの ToolTalk との対話を表示します。この機能により、実行者は 1 つのクライアントだけをトレースできます。
ttsession トレースを、たとえばメッセージ型、送信者、または受信者ごとといったフィルタに通します。
本リリースで新規のコマンドである tttrace は、主に ToolTalk トレースへのアクセスに使用します。このコマンドは、用途やコマンド行インタフェースの点で truss コマンドに似ています。このコマンドにより、3 種類の ToolTalk トレースをコントロールできます。ttrace コマンドには、サーバ・モードとクライアント・モードの 2 つの基本モードがあります。
サーバ・モードでは、Session_Trace 要求を送信することによって、指定されたセッションのトレースを指示します。
クライアント・モードでは、ttrace は環境変数を設定し、コマンド行に指定された ToolTalk クライアント・コマンドを実行します。実行されたクライアントの環境変数は、クライアント・メッセージとクライアント API 呼び出しをトレースするかどうかとその方法を libtt に指示します。
ttrace は、旧バージョンのサーバや、libtt の旧バージョンを使用するクライアントとの下位互換性はありません。ttrace は、旧バージョンのサーバを検出して診断すると、libtt の旧バージョンを使用するクライアント上で何も通知せずに異常終了します。
libtt トレースの動作をコントロールする方法の 1 つは、環境変数 $TT_TRACE_SCRIPT を設定することです。
libtt のトレースは、変数の値が正確ではない場合や一貫性がない場合は異常終了します。
tt_trace_control 呼び出しは、内部フラグを設定または消去して、すべてのクライアント側トレースをコントロールします。この呼び出しを使用して、コード内の問題の領域をトレースします。この呼び出しの形式は次のとおりです。
int tt_trace_control(int option)
オプションの値として 0 を指定するとトレースをオフにし、1 を指定するとトレースをオンにします。-1 を指定すると、トレースのオンとオフを切り替えます。トレースがオンの場合は、トレースの範囲を TT_TRACE_SCRIPT 変数かトレースファイルでコントロールします。この呼び出しは、トレース・フラグの以前の設定を返します。
Session_Trace 要求は、ttsession がそれ自身を処理するために登録する ToolTalk 要求です。つまり、ttsession は Session_Trace 要求のハンドラです。この要求は、どの ToolTalk クライアントでも送信できます。お勧めできる方法ではありませんが、この要求を処理するために他の ToolTalk クライアントを登録できます。
この方法ではトレースは行われません。
この要求の構文は次のとおりです
[file] Session_Trace( in boolean on, in boolean follow [in attribute toPrint |in state toTrace |in op toTrace |in handler_ptype toTrace |in sender_ptype toTrace][...] );
Session_Trace 要求は、配信範囲指定されたセッションでのメッセージ・トレースをオンまたはオフにします。
トレースがオンで、要求のファイル属性が設定されている場合、後続のトレース出力は属性が名前を付けたファイルに付け加えられます。
トレースがオンで、ファイル属性が設定されていない場合、トレースは現在のトレースを続行します。
デフォルトの場合、デーモン・モードでは ttsession を実行中のホストのコンソールが出力先になります。ジョブ・コントロール・モードでは、ttsession の標準エラーが出力先になります。表 4-1 は、この要求の必須およびオプションの引き数を示しています。
表 4-1 Session_Trace 引き数
現在のセッション・トレースの動作は、この要求が失敗しない場合にのみ変更されます。失敗した場合には、応答の tt_message_status は表 4-2 で説明されているエラーの 1 つに設定されます。
表 4-2 Session_Trace 要求が返すエラー・メッセージ
エラー |
説明 |
---|---|
要求に対するハンドラを見つけることができません。 |
|
ttsession がトレース・ファイルを開くまたは作成するためのアクセス権を持っていません。 |
|
トレース・ファイルがディレクトリです。 |
|
ターゲット・ファイル・システムにトレース・ファイルの作成に十分なスペースがありません。 |
|
トレースがすでに別のファイルで行われています。ttsession は、応答のファイル属性を再設定して既存のトレース・ファイルの名前を付けます。別のファイルへのトレースを行うには、最初に現在のトレース・ファイルへのトレースをオフにします。 |
ttrace 関数は、指定の ToolTalk セッションのためにサーバによりメッセージ・トラフィックをトレースするか、ToolTalk クライアント・トレースをオンにしてコマンドを実行します。セッションとコマンドの両方とも指定されない場合は、デフォルトのセッションがトレースされます。デフォルトでは、ttrace が終了するとトレースも終了します。この関数の構文は次のとおりです。
tttrace [-0FCa] [-o outfile ] -S session | command] tttrace [-e script | -f scriptfile ] [-S session | command]
表 4-3 では、ttrace オプションについて説明します。
表 4-3 tttrace オプション
オプション |
説明 |
---|---|
-0 |
セッション内のメッセージ・トレースをオフにするか、メッセージ・トレースを行わないで (つまり呼び出しのトレースだけを行なって) 指定のコマンドを実行します。 |
-F |
指定のコマンドによってフォークされた、または ttsession によりセッション内で続けて起動されたすべての子を追跡します。通常、指定のコマンドだけか ttsession インスタンスがトレースされます。-F オプションが指定されている場合、プロセス ID がトレース出力の各行に表示され、どのプロセスが生成したかを示します。 |
-C |
ToolTalk API へのクライアント呼び出しをトレースしないようにします。デフォルトでは呼び出しをトレースします。 |
-a |
トレースされたメッセージのすべての属性、引き数、およびコンテキスト・スロットを出力します。デフォルトでは、トレース出力へメッセージを出力するには単一行だけを使用します。 |
-o outfile |
トレース出力に使用されるファイルです。セッション・トレースの場合、出力先は tttrace の標準出力です。 |
-S session | |
command |
起動し、トレースを行う ToolTalk クライアント・コマンドです。 |
-e script |
ttrace 設定として使用されるスクリプトです。 |
-f scriptfile |
ttrace 設定を読み取るファイルです。 |
ttrace は、ttsession へのメッセージ・インタフェースと TT_TRACE_SCRIPT 環境変数を使用する ToolTalk クライアントとして実行できるようになっています。この変数が設定されると、トレース・スクリプトに指定されているようにクライアント側トレースをオンにすることを libtt に通知します。値の最初の文字が「.」か「/」の場合、その値は使用するトレース・スクリプトが入っているファイルのパス名として認識されます。その他の文字の場合は、インライン・トレース・スクリプトとして認識されます。
次は、トレースされた ToolTalk 関数の例です。
[pid] function_name(params) = return_value (Tt_status)
-a オプションは、次のように 1 行のメッセージ要約の後にメッセージ属性を出力します。
Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope) : status == Tt_status
状態の変更は次の形式で示されます。
old_state => new_state.
配信は次のように示されます。
Tt_message => procid recipient_procid
表 4-4 は、ディスパッチ・トレース中に受信するメッセージついて説明しています。
表 4-4 ディスパッチ・トレース用の理由
メッセージ |
説明 |
---|---|
tt_message_send |
送信するメッセージです。 |
tt_message_reject |
メッセージが拒否されました。 |
tt_message_fail |
メッセージが無視されました。 |
tt_message_reply |
メッセージへの応答です。 |
tt_session_join |
参加するセッションです。 |
tt_file_join |
参加するファイルです。 |
tt_message_reply |
クライアントが指定の関数を呼び出しました。 |
tt_message_send_on_exit |
ttsession は、tt_close を呼び出す前に切り離されたクライアントに対して on_exit メッセージをディスパッチしています。 |
tt_message_accept |
ttsession は、ptype が起動されている間にブロックされたメッセージをディスパッチしています。起動されたクライアントは、ptype がブロック解除されることを示す tt_message_accept か tt_message_reply のどちらかを呼び出します。 |
TT_ERR_PTYPE_START |
ptype インスタンスがメッセージの受信のために起動されましたが、起動コマンドは ttsession に接続される前に終了しました。 |
TT_ERR_PROCID |
ttsession はこの要求に応じて動作中であったクライアントとの接続を切りました。 |
ttsession -> ttsession |
別のセッションが、このセッションに対してメッセージの受信者を見つけるように求めています。 |
ttsession <- ttsession |
別のセッションが、このセッションで発信したメッセージの更新 (たとえば失敗すること) を求めています。 |
ディスパッチがトレースされているとき、照合は次の形式のうちの 1 つで示されます。
Tt_message & Tt_pattern { Tt_message & ptype ptid { Tt_message & otype otid {
パターンまたはシグニチャーが次の形式で出力されます。
} == match_score; [/* mismatch_reason */]
この節では、tttrace 関数の使用例を取り上げます。
パターンを登録し、そのパターンに一致するという通知を送信するには、次のように入力します。
% tttrace -a myclientprogram
例 4-1 は、その結果を示します。
tt_open() = 0x51708=="7.jOHHM X 129.144.153.55 0" (TT_OK) tt_fd() = 11 (TT_OK) tt_pattern_create() = 0x50318 (TT_OK) tt_pattern_category_set(0x50318, TT_OBSERVE) = 0 (TT_OK) tt_pattern_scope_add(0x50318, TT_SESSION) = 0 (TT_OK) tt_pattern_op_add(0x50318, 0x2f308=="Hello World") = 0 (TT_OK) tt_default_session() = 0x519e0=="X 129.144.153.55 0" (TT_OK) tt_pattern_session_add(0x50318, 0x519e0=="X 129.144.153.55 0") = 0 (TT_OK) tt_pattern_register(0x50318) = 0 (TT_OK) tt_message_create() = 0x51af0 (TT_OK) tt_message_class_set(0x51af0, TT_NOTICE) = 0 (TT_OK) tt_message_address_set(0x51af0, TT_PROCEDURE) = 0 (TT_OK) tt_message_scope_set(0x51af0, TT_SESSION) = 0 (TT_OK) tt_message_op_set(0x51af0, 0x2f308=="Hello World") = 0 (TT_OK) tt_message_send(0x51af0) ... TT_CREATED => TT_SENT: TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK id: 0 7.jOHHM X 129.144.153.55 0 op: Hello World session: X 129.144.153.55 0 sender: 7.jOHHM X 129.144.153.55 0 = 0 (TT_OK) tt_message_receive() ... Tt_message => procid <7.jOHHM X 129.144.153.55 0> TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK id: 0 7 jOHHM X 129.144.153.55 0 op: Hello World session: X 129.144.153.55 0 sender: 7.jOHHM X 129.144.153.55 0 pattern: 0:7.jOHHM X 129.144.153.55 0 = 0x51af0 (TT_OK)
ttsession によるメッセージ・フローの表示を見るには、次のように入力します。
% tttrace -a
ttsession による mylientprogram のメッセージ・フローの表示は、例 4-2 のとおりです。
tt_message_reply: TT_SENT => TT_HANDLED: TT_HANDLED TT_PROCEDURE TT_REQUEST (TT_DISCARD in TT_SESSION): 0 == TT_OK id: 0 2.jOHHM X 129.144.153.55 0 op: Session_Trace args: TT_IN string: "> /tmp/traceAAAa002oL; version 1; states"[...] session:X 129.144.153.55 0 sender: 2.jOHHM X 129.144.153.55 0 pattern:0:X 129.144.153.55 0 handler:0.jOHHM X 129.144.153.55 0 Tt_message => procid <2.jOHHM X 129.144.153.55 0> tt_message_send: TT_CREATED TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK id: 0 7.jOHHM X 129.144.153.55 0 op: Hello World session:X 129.144.153.55 0 sender: 7.jOHHM X 129.144.153.55 0 TT_CREATED => TT_SENT: TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK id: 0 7.jOHHM X 129.144.153.55 0 op: Hello World session:X 129.144.153.55 0 sender: 7.j HHM X 129.144.153.55 0 Tt_message & Tt_pattern { id: 0:7.jOHHM X 129.144.153.55 0 category:TT_OBSERVE scopes: TT_SESSION sessions:X 129.144.153.55 0 ops: Hello World } == 3; Tt_message => procid <7.jOHHM X 129.144.153.55 0>
トレースされた最初のメッセージは、ほとんどの場合 ttrace が送信した要求への ttsession による応答になります。
特定の、デフォルトではないセッション内のメッセージ・フローをトレースするには、次のように入力します。
% tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"
"01 15303 1342177284 1 0 13691 129.144.153.55 2" は、デフォルトではない特定のトレースされるセッションです。
ttrace スクリプトには、ToolTalk 呼び出しとメッセージをコントロールする設定があります。ttrace スクリプトは、セミコロンか復帰改行で区切られたコマンドから成ります。重複している値が設定に指定されると、最後の値が使用されます。
表 4-5 では、これらのコマンドについて説明します。
表 4-5 tttrace スクリプト・コマンド