Scope Attributes

You can specify the following types of scopes in your message patterns:

Scope to a session only.
Scope to a file only.
Scope only to a file in a particular session.
Scope to either or both a file and a session.

Note - File scopes are restricted to NFS and UFS file systems; you cannot scope a file across other types of file systems (for example, a tmpfs file system).

Scoping to a Session Only

The type TT_SESSION scopes to a session only. Static session-scoped patterns require an explicit tt_session_join call to set the scope value; dynamic session-scoped patterns can be set with either the tt_session_join call or the tt_pattern_session_add call.

Note - The session specified by these calls must be the default session.

Example 3-1 shows a static session-scoped pattern; Example 3-2 shows a dynamic session-scoped pattern.

Example 3-1 Static Session-Scoped Pattern

Obtain procid	tt_open();
Ptype is scoped to session	tt_ptype_declare(ptype);
Join session	tt_session_join(tt_default_session());

Example 3-2 Dynamic Session-Scoped Pattern with a File Attribute

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat, TT_SESSION);
Add session to pattern	tt_pattern_session_add (tt_default_session());
Register pattern	tt_pattern_register(pat);

Scoping to a File Only

The type TT_FILE scopes to a file only. Example 3-3 shows a static file-scoped pattern; Example 3-4 shows a dynamic file-scoped pattern.

Example 3-3 Static File-Scoped Pattern

Obtain procid	tt_open();
Ptype is scoped to file	tt_ptype_declare(ptype);
Join file	tt_file_join(file);

Example 3-4 Dynamic File-Scoped Pattern

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat, TT_FILE);
Add file to pattern	tt_pattern_file_add (pat, file);
Register pattern	tt_pattern_register(pat);

Scoping to a File in a Session

The type TT_FILE_IN_SESSION scopes to the specified file in the specified session only. A pattern with this scope set will only match messages that are scoped to both the file and the session. Example 3-5 adds the session and then registers the pattern.

Example 3-5 Adding a Session to the TT_FILE_IN_SESSION-Scoped Pattern

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat,TT_FILE_IN_SESSION);
Add file to pattern	tt_pattern_file_add(pat, file);
Add session to pattern	tt_pattern_session_add(pat, tt_default_session());
Register pattern	tt_pattern_register(pat);

Example 3-6 registers the pattern and then joins a session.

Example 3-6 Joining a Session to Set the Session of a TT_FILE_IN_SESSION-Scoped Pattern

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat, TT_FILE_IN_SESSION);
Add file to pattern	tt_pattern_file_add(pat, file);
Register pattern	tt_pattern_register(pat);
Join session	tt_session_join(tt_default_session());

Example 3-7 sets the scope value for a static pattern.

Example 3-7 Setting the Scope Value for a TT_FILE_IN_SESSION Static Pattern

Obtain procid	tt_open();
Declare Ptype	Tt_ptype_declare(ptype);
Join File	tt_file_join(file);
Join session	tt_session_join(tt_default_session());

Scoping to a File and/or a Session

A TT_BOTH-scoped pattern will match messages that are scoped to the file, the session, or the file and the session. However, when you use this scope, you must explicitly make a tt_file_join call; otherwise, the ToolTalk service will only match messages that are scoped to both the file and session of the registered pattern. Example 3-8 and Example 3-9 show examples of how to use this scope.

Example 3-8 A Dynamic Pattern that Uses the TT_BOTH Scope

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat, TT_BOTH);
Add session to pattern	tt_pattern_session_add(pat,tt_default_session());
Add file to pattern	tt_pattern_file_add (pat, file);
Register pattern	tt_pattern_register(pat);

Example 3-9 A Static Pattern that Uses the TT_BOTH Scope

Obtain procid	tt_open();
Declare Ptype	Tt_ptype_declare(ptype);
Join file	tt_file_join(file);
Join session	tt_session_join(tt_default_session());

Adding Files to Scoped Patterns

To match TT_SESSION-scoped messages and TT_SESSION-scoped patterns that have the same file attributes, you can add file attributes to TT_SESSION-scoped patterns with the tt_pattern_file_add call, as shown in Example 3-10.

Note - The file attribute values do not affect the scope of the pattern.

Example 3-10 Adding Two File Attributes to a Session-Scoped Pattern

Obtain procid	tt_open();
Create pattern	Tt_pattern pat = tt_create_pattern();
Add scope to pattern	tt_pattern_scope_add(pat, TT_SESSION);
Add session to pattern	tt_pattern_session_add(tt_default_session());
Add first file attribute to pattern	tt_pattern_file_add(pat, file1);
Add second file attribute to pattern	tt_pattern_file_add(pat, file2);
Register pattern	tt_pattern_register(pat);

Context Attributes

ToolTalk contexts are sets of <name, value> pairs explicitly included in both messages and patterns. ToolTalk contexts allow fine-grain matching.

You can use contexts to associate arbitrary pairs with ToolTalk messages and patterns, and to restrict the set of possible recipients of a message. One common use of the restricted pattern matching provided by ToolTalk context attributes is to create sub-sessions. For example, two different programs could be debugged simultaneously with tools such as a browser, an editor, a debugger, and a configuration manager active for each program. The message and pattern context slots for each set of tools contain different values; the normal ToolTalk pattern matching of these values keep the two sub-sessions separate.

Another use for the restricted pattern matching provided by ToolTalk context attributes is to provide information in environment variables and command line arguments to tools started by the ToolTalk service.

Pattern Argument Attributes

ToolTalk pattern arguments may be strings, binary data, or integer values which Tooltalk service uses to match against incoming messages.

Arguments differ from contexts in that arguments are positional paramaters while contexts are named paramaters. The order of arguments, set in a message, determines the order in which they are present in the sent and received message. That is, they must agree with the order and types of arguments set in a pattern. Since arguments are positional, you must add a "wildcard" argument for intermidiate arguments in a pattern if you wish to match an argument that is not the first argument in the incoming message. Wildcard arguments should have the vtype of "ALL" and the value of NULL.

You must use the pattern argument adding API call that matches the type of your argument (integer, binary data, or ASCII string). In particular, you should note that it is not possible to add a pattern argument with a wildcard value of NULL with tt_pattern_iarg_add(), since NULL, or 0 is a valid integer argument value. To add wildcard arguments, use tt_pattern_arg_add().

Disposition Attributes

Disposition attributes instruct the ToolTalk service how to handle messages to your application if an instance of the application is not currently running.

The disposition value specified in the static type definition of a pattern is the default disposition; however, if the message deposition specifies the handler ptype the default disposition value is over-ridden. For example, a message disposition specifies a static type definition for the ptype UWriteIt which includes the message signature Display. This message signature does not match any of the static signatures in the pattern. The ToolTalk service will follow the instructions for the disposition set in the message; for example, if the message disposition is TT_START and the UWriteIt ptype specifies a start string, the ToolTalk service will start an instance of the application if one is not running.