Creating a Ptype File

The following listing illustrates a ptype file.

#include "Sun_EditDemo_opnums.h"

ptype Sun_EditDemo {
		/* setenv Sun_EditDemo_HOME to install dir for the demo */
	 start	“${Sun_EditDemo_HOME}/edit”;
	 handle:
	 /* edit file named in message, start editor if necessary */
	 session Sun_EditDemo_edit(void)
					=> start opnum=Sun_EditDemo_EDIT;

	 /* tell editor viewing file in message to save file */
	 session Sun_EditDemo_save(void)
					=> opnum=Sun_EditDemo_SAVE;

	 /* save file named in message to new filename */
	 session Sun_EditDemo_save_as(in string new_filename)
					=> opnum=Sun_EditDemo_SAVE_AS;

	 /* bring down editor viewing file in message */
	 session Sun_EditDemo_close(void)
					=> opnum=Sun_EditDemo_CLOSE;
};

The following listing shows the syntax for a ptype file.

ptype	::=	'ptype' ptid `{'
		property*		[`observe:' psignature*]
		[`handle:' psignature* ]
		[`handle_push:' psignature*]
		[`handle_rotate:' psignature*]
		`}' [`;']
property	::=	property_id value `;'
property_id	::=	`start'
value	::=	string
ptid	::=	identifier
psignature	::=	[scope] op args [contextdcl]
		[`=>'
		[`start'][`queue']
		[`opnum='number]]
		`;'
scope	::=	`file'
	|	`session'
	|	`file_in_session'
args	::=	`(` argspec {, argspec}* `)'
	|	`(void)'
	|	`()'
contextdcl	::=	`context' `(` identifier {, identifier}* `)' `;'
argspec	::=	mode type name
mode	::=	`in' | `out' | `inout'
type	::=	identifier
name	::=	identifier

Property_id Information

ptid—process type identifier (ptid). Identifies the process type. A ptid must be unique for every installation. Because this identifier cannot be changed after installation time, each chosen name must be unique. For example, you can use a name that includes the trademarked name of your product or company, such as Sun_EditDemo. The ptid cannot exceed 32 characters and should not be one of the reserved identifiers: ptype, otype, start, opnum, queue, file, session, observe, or handle.

start—start string for the process. If the ToolTalk service needs to start a process, it executes this command; /bin/sh is used as the shell.

Before executing the command, the ToolTalk service defines TT_FILE as an environment variable with the value of the file attribute of the message that started the application. This command runs in the environment of ttsession, not in the environment of the sender of the message that started the application, so any context information must be carried by message arguments or contexts.

Psignature Matching Information

scope—this pattern attribute is matched against the scope attribute in messages.

op—operation name. This name is matched against the op attribute in messages.

If you specify message signatures in both your ptype and otypes, use unique operation names in each. For example, do not specify a display operation in both your ptype and otype.

args—arguments for the operation. If the args list is void, the signature matches only messages with no arguments. If the args list is empty (that is, “()”), the signature matches without regard to the arguments.

contextdcl—context name. When a pattern with this named context is generated from the signature, it contains an empty value list.

Psignature Actions Information

start—if the psignature matches a message and no running process of this ptype has a pattern that matches the message, start a process of this ptype.

queue—if the psignature matches a message and no running process of this ptype has a pattern that matches the message, queue the message until a process of this ptype registers a pattern that matches it.

opnum—fill in the message's opnum attribute with the specified number to enable you to identify the signature that matched the message.

When the message matches the signature, the opnum from the signature is filled into the message. Your application can then retrieve the opnum with the tt_message_opnum call. By giving each signature a unique opnum, you can quickly determine which signature matched the message.

You can attach a callback routine to the opnum with the tt_ptype_opnum_callback_add call. When the message is matched, the ToolTalk service will check for any callbacks attached to the opnum and, if any are found, run them.

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.