JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
ToolTalk User's Guide
search filter icon
search icon

Document Information

Preface

1.  Introducing the ToolTalk Service

2.  An Overview of the ToolTalk Service

3.  Message Patterns

4.  Setting Up and Maintaining the ToolTalk Processes

5.  Maintaining Application Information

6.  Maintaining Files and Objects Referenced in ToolTalk Messages

7.  Participating in ToolTalk Sessions

8.  Sending Messages

9.  Dynamic Message Patterns

10.  Static Message Patterns

11.  Receiving Messages

12.  Objects

13.  Managing Information Storage

14.  Handling Errors

A.  Migrating from the Classing Engine to the ToolTalk Types Database

B.  A Simple Demonstration of How the ToolTalk Service Works

C.  The ToolTalk Standard Message Sets

The ToolTalk Desktop Services Message Set

Why the ToolTalk Desktop Services Message Set was Developed

Key Benefits of the ToolTalk Desktop Services Message Set

The ToolTalk Document and Media Exchange Message Set

ToolTalk Document and Media Exchange Message Set Development History

Key Benefits of the ToolTalk Document and Media Exchange Message Set

General ToolTalk Message Definitions and Conventions

Errors

General ToolTalk Development Guidelines and Conventions

Always Make Anonymous Requests

Let Tools Be Started as Needed

Reply When Operation has been Completed

Avoid Statefulness Whenever Possible

Declare One Process Type per Role

Developing ToolTalk Applications

Messaging Alliances

D.  Frequently Asked Questions

Glossary

Index

General ToolTalk Message Definitions and Conventions

In the ToolTalk messages there are terms used with specific ToolTalk definitions. This section defines these terms and conventions used in the ToolTalk message man pages.

Table C-1 Document and Media Exchange Message Set Descriptions

Type of Information
Description
header
A single line that describes the message in the following format:

MsgName(Tt_class)

where MsgName is the name of the message and Tt_class is either Request or Notice.

name
The name of the message and a one-line description of the message.
description
An explanation of the operation (event) that the message requests (announces).
synopsis

A representation of the message in the ToolTalk types-file syntax (similar to the syntax understood by the ToolTalk type compiler tt_type_comp) in the following format:

<fileAttrib> <opName> (<requiredArgs> [<optionalArgs>]);

A synopsis entry is given for each interesting variant of the message.

<fileAttrib> - An indication of whether the file attribute of the message can/should be set.

<opName> - The name of the operation or event is called the “op name” (or “op”). It is important that different tools not use the same opName to mean different things. Therefore, unless a message is a standard one, its opName should be made unique. A good way to do this is to prefix it with: <Company><Product> e.g.,

“Acme_Hoarktool_My_Frammistat”.

<requiredArgs>, <optionalArgs> - The arguments that must always be included in the message. A particular argument is described in the following format:

<mode> <vtype> <argument name>

where mode is one of “in”, ”out”, or “inout”, vtype is a programmer-defined string that describes what kind of data a message argument contains; and argument name is the name of the argument.

The ToolTalk service uses vtypes to match sent message instances with registered message patterns. By convention, a vtype maps to a single, well-known data type.

required arguments
The arguments that must always be in the message.

<vtype> <argumentName>

A description of a particular argument.

A `vtype' is a programmer-defined string that describes what kind of data a message argument contains. ToolTalk uses vtypes for the sole purpose of matching sent message instances with registered message patterns.

Every vtype should by convention map to a single, well-known data type. The data type of a ToolTalk argument is either integer, string, or bytes. The data type of a message or pattern argument is determined by which ToolTalk API function is used to set its value.

The argument name is merely a comment hinting to human readers at the semantics of the argument, much like a parameter name in a C typedef.

optional arguments

The extra arguments that may be included in a message. Unless otherwise noted, any combination of the optional arguments, in any order, may be appended to the message after the required arguments.
description

An explanation of the operation that the request entreats, or the event that the notice announces.
errors
A list of the error codes that can be set by the handler of the request (or the sender of the notice).

Edict—An edict is a notice that looks like a request. If a request returns no data (or if the sender does not care about the returned data), it can sometimes be useful to broadcast that request to a set of tools. Since the message is a notice, no data is returned, no replies are received, and the sender is not told if any tool gets the message.

Handler—The handler is the distinguished recipient procid of a request. This procid is responsible for completing the indicated operation.

Notice—A notice is a message that announces an event. Zero or more tools may receive a given notice. The sender does not know whether any tools receive its notice. A notice cannot be replied to.

Procid—A procid is a principal that can send and receive ToolTalk messages. A procid is an identity, created and handed over by the ToolTalk service on demand (via tt_open), that a process must assume in order to send and receive messages. A single process can use multiple procids; and a single procid can be used by a group of cooperating processes.

Request—A request is a message that asks an operation to be performed. A request has a distinguished recipient, called a handler, who is responsible for completing the indicated operation. A handler may fail, reject, or reply to a request. Any number of handlers may reject a request but ultimately only one handler can fail it or reply to it. If no running handler can be found to accept a request, the ToolTalk service can automatically start a handler. If no willing handler can be found, or if a handler fails the request, then the request is returned to the sender in the `failed' state.