Common Desktop Environment: ToolTalk Messaging Overview

Tracing ToolTalk Calls and Messages through the Server

The ttrace function traces message traffic through the server for the indicated ToolTalk session, or runs a command with ToolTalk client tracing turned on. If neither the session nor the command is given, the default session is traced. By default, tracing terminates when ttrace exits. The syntax for this function is:

tttrace [-0FCa] [-o outfile ] -S session | command]
tttrace [-e script | -f scriptfile ] [-S session | command]

Table 4-3 describes the ttrace options.

Table 4-3 tttrace Options


Option	Description
`-0`	Turns off message tracing in session, or runs the specified command without message tracing (that is, with only call tracing).
`-F`	Follows all children forked by the indicated command, or subsequently started in session by ttsession. Normally, only the indicated command or a ttsession instance is traced. When the `-F` option is specified, the process ID is included with each line of trace output to indicate which process generated it.
`-C`	Do not trace client calls into the ToolTalk API. The default is to trace the calls.
`-a`	Prints all attributes, arguments, and context slots of traced messages. The default is to use only a single line when printing a message on the trace output.
`-o` `outfile`	The file to be used for the trace output. For session tracing, output goes to standard output of tttrace.
`-S` `session`	The session to trace. Defaults to the default session; that is, the session that `tt_open` would contact.
`command`	The ToolTalk client command to invoke and trace.
-e `script`	The script to be used as a `ttrace` setting.
-f `scriptfile`	The file from which to read the `ttrace` settings.

ttrace is implemented purely as a ToolTalk client, using the message interface to ttsession and the TT_TRACE_SCRIPT environment variable. If this variable is set, it tells libtt to turn on client-side tracing as specified in the trace script. If the first character of the value is '.' or '/', the value is taken to be the path name of file containing the trace script to use; otherwise, the value is taken to be an inline trace script.

Formats of Traced Functions

The following is an example of how a traced ToolTalk function looks.

[pid] function_name(params) = return_value (Tt_status)

Message Summary Format

The -a option prints message attributes after a one-line summary of the message, as follows:

Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope): status == Tt_status

State Change Format

State changes are indicated by the following format:

old_state => new_state.

Message Delivery Format

Deliveries are indicated by the following indicated:

Tt_message => procid recipient_procid

Table 4-4 dexplains the messages you may receive during a dispatch trace.

Table 4-4 Reasons for Dispatch Trace


Message	Explanation
`tt_message_send`	The message to send.
`tt_message_reject`	The message was rejected.
`tt_message_fail`	The message failed.
`tt_message_reply`	The reply to a message.
`tt_session_join`	The session to join.
`tt_file_join`	The file to join.
`tt_message_reply`	A client called the indicated function.
`tt_message_send_on_exit`	ttsession is dispatching on_exit messages for a client that disconnected before calling `tt_close`.
`tt_message_accept`	ttsession is dispatching messages that had been blocked while a ptype was being started. The started client has now called either `tt_message_accept` or `tt_message_reply` to indicate that the ptype should be unblocked.
`TT_ERR_PTYPE_START`	A ptype instance was started to receive the message, but the start command exited before it connected to ttsession.
`TT_ERR_PROCID`	ttsession lost its connection to the client that was working on this request.
`ttsession -> ttsession`	Another session wants this session to find recipients for the message.
`ttsession <- ttsession`	Another session wants to update (for example, fail) a message originating in this session.

Matching Format

When dispatching is being traced, matching is indicated by one of the following formats:

Tt_message & Tt_pattern {  Tt_message & ptype ptid {  Tt_message & otype otid {

The pattern or signature is printed, followed by:

} == match_score; [/* mismatch_reason */]

Examples

This sections contains examples of how to use the tttrace function.

Registering a Pattern and Sending a Matching Notice

To register a pattern and send a notice that matches the pattern, type:

 % tttrace -a myclientprogram

Example 4-1 shows the results.

Example 4-1 Registering a Pattern and Sending a Notice

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)

To see ttsession's view of the message flow, type:

 % tttrace -a

ttsession's view of mylientprogram's message flow is shown in Example 4-2.

Example 4-2 ttsession's View of Trace

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>

Note -

The first message traced will almost always be ttsession's reply to the request sent to it by ttrace.

Tracing a Message Flow

To trace the message flow in a specific, non-default session, type:

 % tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"

where "01 15303 1342177284 1 0 13691 129.144.153.55 2" is the specific, non-default session to be traced.