ToolTalk User's Guide

May 2002

This book describes the ToolTalk service and how to modify applications to send and receive ToolTalk messages. This document is for developers who create or maintain applications that use the ToolTalk service to interoperate with other applications; it is also useful for system administrators who set up workstations. This book assumes familiarity with Solaris operating environment commands, system administrator commands, and system terminology.

Document Information
Preface
1. Introducing the ToolTalk Service
- Overview
- ToolTalk Scenarios
- How Applications Use ToolTalk Messages
- ToolTalk Message Distribution
- Modifying Applications to Use the ToolTalk Service
2. An Overview of the ToolTalk Service
- ToolTalk Architecture
- Starting a ToolTalk Session
- Maintaining ToolTalk Files and Databases
- Demonstration Programs
3. Message Patterns
- Message Pattern Attributes
- Scope Attributes
- Context Attributes
- Pattern Argument Attributes
- Disposition Attributes
4. Setting Up and Maintaining the ToolTalk Processes
- Location of the ToolTalk Service Files
- Version
- Requirements
- Environment Variables
- Installing the ToolTalk Database Server
- Running the New ToolTalk Database Server
- Redirecting the ToolTalk Database Server
  - Redirecting the Host Machine
  - Redirecting the File System Partition
5. Maintaining Application Information
- Installing Application Types
- Examining ToolTalk Type Information
- Removing ToolTalk Type Information
- Updating the ToolTalk Service
  - To send the ttsession process a SIGUSR2:
- Process Type Errors
- Using ttsnoop to Debug Messages and Patterns
6. Maintaining Files and Objects Referenced in ToolTalk Messages
- ToolTalk-Enhanced Shell Commands
- Maintaining and Updating ToolTalk Databases
- Displaying, Checking, and Repairing Databases
7. Participating in ToolTalk Sessions
- Including the ToolTalk API Header File
- Registering with the ToolTalk Service
- Registering in the Initial Session
  - Registering in a Specified Session
  - Registering in Multiple Sessions
- Setting Up to Receive Messages
- Sending and Receiving Messages in the Same Process
- Sending and Receiving Messages in a Networked Environment
- Unregistering from the ToolTalk Service
- Using ToolTalk in a Multi-Threaded Environment
8. Sending Messages
- How the ToolTalk Service Routes Messages
- Message Attributes
- ToolTalk Message Delivery Algorithm
- Modifying Applications to Send ToolTalk Messages
- Examples
9. Dynamic Message Patterns
- Defining Dynamic Messages
- Updating Message Patterns with the Current Session or File
10. Static Message Patterns
- Defining Static Messages
- Defining Process Types
- Defining Object Types
  - Signatures
  - Creating Otype Files
- Installing Type Information
- Checking for Existing Process Types
- Declaring Process Type
- Undeclaring Process Types
11. Receiving Messages
- Retrieving Messages
  - Identifying and Processing Messages Easily
  - Recognizing and Handling Replies Easily
- Checking Message Status
- Examining Messages
- Callback Routines
  - Callbacks for Messages Addressed to Handlers
  - Attaching Callbacks to Static Patterns
- Handling Requests
  - Replying to Requests
  - Rejecting or Failing a Request
    - Rejecting a Request
    - Failing a Request
- Observing Offers
- Destroying Messages
12. Objects
- Object-Oriented Messaging
  - Object Data
- Creating Object Specs
- Writing Object Specs
- Updating Object Specs
- Maintaining Object Specs
- Destroying Object Specs
- Managing Object and File Information
  - Managing Files that Contain Object Data
  - Managing Files that Contain ToolTalk Information
- An Example of Object-Oriented Messaging
13. Managing Information Storage
- Information Provided to the ToolTalk Service
- Information Provided by the ToolTalk Service
- Calls Provided to Manage the Storage of Information
  - Marking and Releasing Information
  - Allocating and Freeing Storage Space
    - Allocating Storage Space
    - Freeing Allocated Storage Space
- Special Case: Callback and Filter Routines
  - Callback Routines
  - Filter Routines
14. Handling Errors
- Retrieving ToolTalk Error Status
- Checking ToolTalk Error Status
- Returned Value Status
  - Functions with Natural Return Values
  - Functions with No Natural Return Values
- Returned Pointer Status
- Returned Integer Status
- Broken Connections
- Error Propagation
A. Migrating from the Classing Engine to the ToolTalk Types Database
- The ttce2xdr Script
- Converting the User Database
- Converting the System Database
- Converting the Network Database
B. A Simple Demonstration of How the ToolTalk Service Works
- Inter-Application Communication Made Easy
- Adding Inter-Operability Functionality
  - Modifying the Xedit Application
  - Modifying the Xfontsel Application
- We Have Tool Communication!
- Adding ToolTalk Code to the Demonstration Applications
  - Adding ToolTalk Code to the Xedit Files
  - Adding ToolTalk Code to the Xfontsel Files
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
- Developing ToolTalk Applications
- Messaging Alliances
D. Frequently Asked Questions
- Questions
Glossary
Index
- Numbers and Symbols
- A
- B
- C
- D
- E
- F
- H
- I
- J
- K
- L
- M
- N
- O
- P
- Q
- R
- S
- T
- U
- V
- W
- X