Common Desktop Environment: ToolTalk Messaging Overview

Tracing Message Traffic in a ToolTalk Session

The Session_Trace request is a ToolTalk request that ttsession registers to handle itself; that is, ttsession is the handler for the Session_Trace request. This request can be sent by any ToolTalk client, and, although not recommended, other ToolTalk clients can register to handle this request. (Note: This method will cause tracing to not work.) The syntax for this request is:

[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][...] );

The Session_Trace request turns message tracing in the scoped-to session on or off.

If tracing is on and the file attribute of the request is set, subsequent trace output is appended to the file named by the attribute.
If tracing is on and the file attribute is not set, tracing continues to the current trace.

By default, daemon mode causes the output to go to the console of the host on which ttsession is running; job-control mode causes the output to go to ttsession's standard error. Table 4-1 describes the required and optional arguments for this request.

Table 4-1 Session_Trace Agurments


Argument		Description
`boolean` on	Required	Turn tracing on or off. If no toTrace arguments are included and on is true, the previous trace settings are restored.
`boolean` follow	Required	Turn on client-side tracing for Invoked clients.
`attribute` toPrint	Optional	Print attribute(s) for each message traced. Valid attributes are: none-print only a one-line description of traced messages (default) all-print all attributes of traced messages


`state` toTrace	Optional	State(s) through which to trace messages. In addition to the Tt_states defined in `tt_c.h`, valid states are: edge-messages entering initial (`TT_SENT`) and final (`TT_HANDLED`, `TT_FAILED`) states. deliver-all state changes and all client deliveries. dispatch-deliver + all patterns considered for matching. (default)
`op` toTrace `sender_ptype` toTrace`handler_ptype` toTrace	OptionalOptionalOptional	Trace messages that have toTrace as a value for the indicated message attribute. Any number of toTrace arguments may be included in the request. toTrace may include `sh` wildcard characters. If no toTrace argument is included for a given message attribute, no value of that attribute excludes a message from tracing.

The current session tracing behavior changes only if this request is not failed. On failure, the tt_message_status of the reply is set to one of the errors described in Table 4-2 .

Table 4-2 Error Messages Returned by Session_Trace Request


Error	Description
`TT_ERR_NO_MATCH`	No handler could be found for the request.
`TT_ERR_APPFIRST + EACCES`	ttsession does not have permission to open or create the trace file.
`TT_ERR_APPFIRST + EISDIR`	The trace file is a directory.
`TT_ERR_APPFIRST + ENOSPC`	There is not enough space in the target file system to create the trace file.
`TT_ERR_APPFIRST + EEXIST`	Tracing is already occurring on another file. ttsession resets the file attribute of the reply to name the existing trace file. To trace to a different file, first turn off tracing to the current trace file.