Osignature Actions Information

start--if the osignature matches a message and no running process of this otype has a pattern that matches the message, start a process of this otype.

queue--if the osignature matches a message and no running process of this otype has a pattern that matches the message, queue the message until a process of this otype registers a pattern that matches it.

The following listing illustrates an otype file.

#include "Sun_EditDemo_opnums.h"

otype Sun_EditDemo_object {
	 handle:
	 /* hilite object given by objid, starts an editor if necessary */
	 hilite_obj(in string objid)
		=> Sun_EditDemo session start opnum=Sun_EditDemo_HILITE_OBJ;
};

The Sun_EditDemo_opnums.h file defines symbolic definitions for all the opnums used by edit.c, allowing both the edit.types file and edit.c file to share the same definitions.

Installing Type Information

The ToolTalk Types Database makes ptype and otype information available on the host that executes the sending process, the host that executes the receiving process, and the hosts that run the sessions to which the processes are joined.

• To start applications and to queue messages, the ptype definition must be placed into the ToolTalk Types Database.

• To receive messages addressed to objects your application creates and manages, the otype definitions must also be installed in the ToolTalk Types Database.

To place your type information into the ToolTalk Types Database and make it available to the ToolTalk service, you compile your type files with the ToolTalk type compiler, tt_type_comp. This compiler creates ToolTalk types definitions for your type information and stores them in the ToolTalk Types Database. See Chapter 5, Maintaining Application Information for detailed information.

This version of the ToolTalk service provides a function to merge a compiled ToolTalk type file into the currently running ttsession:

tt_session_types_load(current_session, compiled_types_file)

where current_session is the current default ToolTalk session and compiled_types_file is the name of the compiled ToolTalk types file. This function adds new types and replaces existing types of the same name; other existing types remain unchanged.

Caution - The action of tt_session_types_load() is controlled both by arguments to ttsession(1) and by ttsession_file(4). Refer to those man pages before using tt_session_types_load().

Checking for Existing Process Types

The ToolTalk service provides a simple function to test if a given ptype is already registered in the current session.

tt_ptype_exists(const char *ptid)

where ptid is the identifier of the session to test for registration.

Declaring Process Type

Since type information is only specified once (when your application is installed), your application needs to only declare its ptype each time it starts.

To declare your ptype, use tt_ptype_declare during your application's ToolTalk initialization routine. The ToolTalk service will create the message patterns listed in your ptype and any otypes that reference the specified ptype.

The message patterns created when you declare your ptype exist in memory until your application exits the ToolTalk session.

Note - The message patterns created when you declare your ptype information cannot be unregistered with tt_pattern_unregister; however, you can unregister these patterns with tt_ptype_undeclare.

The following listing illustrates how a ptype is registered during a program's initialization.

/*
 * Initialize our ToolTalk environment.
 */
int
edit_init_tt()
{
        int     mark;
        char    *procid = tt_open();
        int     ttfd;
        void    edit_receive_tt_message();

        mark = tt_mark();

        if (tt_pointer_error(procid) != TT_OK) {
                return 0;
        }
        if (tt_ptype_declare("Sun_EditDemo") != TT_OK) {
                fprintf(stderr,"Sun_EditDemo is not an installed ptype.\n");
                return 0;
        }
        ttfd = tt_fd();
        tt_session_join(tt_default_session());
        notify_set_input_func(edit_ui_base_window,
                              (Notify_func)edit_receive_tt_message,
                              ttfd);

        /*
         * Note that without tt_mark() and tt_release(), the above
         * combination would leak storage -- tt_default_session() returns
         * a copy owned by the application, but since we don't assign the
         * pointer to a variable we could not free it explicitly.
         */

        tt_release(mark);
        return 1;
}

Undeclaring Process Types

There may be cases when you need to retract a declared ptype; for example, in the CASE environment:

• An installation sets up a compile server which declares itself willing to accept compilation requests when it comes up. Once the server has accepted a request, it changes state and will no longer accept new compilation requests.

• A generic encapsulation process declares itself as multiple ptypes and then forwards requests to underlying tools. If an underlying tool exits, the generic wrapper no longer wants to declare itself as the ptype associated with that tool.

To unregister a ptype, use tt_ptype_undeclare. This call reverses the effect of the tt_ptype_declare call; that is, all patterns generated from the ptype are unregistered and the process is removed from the session's list of active processes with this ptype. This call returns a status of TT_ERR_PTYPE if the named ptype was not declared by the calling process.

Caution - One invocation of tt_type_undeclare will completely unregister the ptype regardless of how many times the process has declared the ptype; that is, multiple declarations of the ptype are the same as declaring it once.

Example 10-1 is an example of how to retract a a declared ptype.

Example 10-1 Undeclaring a Ptype

/*

 * Obtain procid
 */
tt_open();

/*

 * Undeclared Ptype

 */
tt_ptype_undeclare(ptype);