debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the CDE 2.1.30 sources from the Open Group.

Browse Source
This commit is contained in:
Peter Howkins
2012-03-10 18:21:40 +00:00
commit 83b6996daa
18978 changed files with 3945623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
cde/doc/C/guides/ttGuide/BEntity.sgm Normal file
View File

@@ -0,0 +1,4 @@
<!-- $XConsortium: BEntity.sgm /main/6 1996/08/07 16:18:06 cdedoc $ -->
<!ENTITY TTUG.Intro.fig.1 SYSTEM "./ttGuide/graphics/ttserv.cgm" NDATA CGM-BINARY>

3
cde/doc/C/guides/ttGuide/Title.tmpl Normal file
View File

@@ -0,0 +1,3 @@
/* $XConsortium: Title.tmpl /main/2 1996/06/19 16:05:00 drk $ */
/* TOC title, only what's between quotes should be modified. */
title = "ToolTalk Messaging Guide"

56
cde/doc/C/guides/ttGuide/adbook.sgm Normal file
View File

@@ -0,0 +1,56 @@
<!-- $XConsortium: adbook.sgm /main/9 1996/08/19 13:25:59 cdedoc $ -->
<!DOCTYPE DocBook PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY TTUG.Intro.fig.1 SYSTEM "./graphics/TTUG.Intro.iFrame.1.eps" NDATA eps>
<!ENTITY GSCr SYSTEM "./credits.sgm">
<!ENTITY Pref SYSTEM "./preface.sgm">
<!ENTITY Intro SYSTEM "./ch01.sgm">
<!ENTITY HTU SYSTEM "./ch02.sgm">
<!ENTITY ttsnp SYSTEM "./ch03.sgm">
<!ENTITY tttrc SYSTEM "./ch04.sgm">
<!ENTITY MsgTk SYSTEM "./appa.sgm">
<!ENTITY BrCast SYSTEM "./appb.sgm">
<!ENTITY ttmt SYSTEM "./appc.sgm">
<!ENTITY Examp SYSTEM "./appd.sgm">
<!ENTITY % Solaris "INCLUDE">
<!ENTITY % CDE.C.XO "IGNORE">
<!ENTITY % CDE.C.CDE "INCLUDE">
<!ENTITY % CDE.C.HP "IGNORE">
<!ENTITY % CDE.C.SUN "IGNORE">
]>
<!-- -->
<DocBook>
<Book>
<Title>Common Desktop Environment: ToolTalk Messaging Guide</Title>
&GSCr;
&Pref;
&Intro;
&HTU;
&ttsnp;
&tttrc;
&MsgTk;
&BrCast;
<Appendix Id="TTUG.ttmt.div.1">
&ttmt;
</appendix>
&Examp;
</Book>
</DocBook>

3619
cde/doc/C/guides/ttGuide/appa.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

305
cde/doc/C/guides/ttGuide/appb.sgm Normal file
View File

@@ -0,0 +1,305 @@
<!-- $XConsortium: appb.sgm /main/6 1996/08/25 15:16:07 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Appendix Id="TTUG.BrCast.div.1">
<Title Id="TTUG.BrCast.mkr.1">The broadcast Demonstration Program</Title>
<indexterm><primary>broadcast demo program</primary></indexterm>
<indexterm><primary>example program</primary></indexterm>
<Para>This appendix contains the source code for the ToolTalk demo
program, <literal>broadcast</literal>. The source code can also
be found in the file <filename>/usr/dt/examples/tt/broadcast.c</filename>.
The purpose of the demo program is to show the use of some ToolTalk
APIs. In particular, this program:
</para>
<itemizedlist>
<listitem>
<para>Creates and registers a pattern
</para>
</listitem>
<listitem>
<para>Creates a notification message and sends it (to itself)
</para>
</listitem>
<listitem>
<para>Receives a message
</para>
</listitem>
</itemizedlist>
<Sect1 Id="TTUG.BrCast.div.2">
<title>broadcast.c Program Listing</title>
<programlisting>
/*
* (c) Copyright 1995 Digital Equipment Corporation.
* (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company
* (c) Copyright 1993, 1994, 1995 International Business Machines Corp.
* (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.
* (c) Copyright 1993, 1994, 1995 Novell, Inc.
* (c) Copyright 1995 FUJITSU LIMITED.
* (c) Copyright 1995 Hitachi.
*
* $XConsortium: appb.sgm /main/6 1996/08/25 15:16:07 rws $
*
* broadcast - dynamic pattern and procedural notification example
*
*/
#include &lt;stdio.h&gt;
#include &lt;sys/param.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;string.h&gt;
#include &lt;Xm/XmAll.h&gt;
#include &lt;Tt/tt_c.h&gt;
Widget toplevel, base_frame, controls, slider, gauge, button;
char *my_procid;
void broadcast_value();
void receive_tt_message();
void create_ui_components();
void
main(argc, argv)
int argc;
char **argv;
{
int ttfd;
Tt_pattern pat;
XtAppContext app;
/*
* Initialize Motif and create ui components
*/
toplevel = XtVaAppInitialize(&amp;app, "ttsample1", NULL, 0,
&amp;argc, argv, NULL, NULL);
XtVaSetValues(toplevel, XmNtitle, "ToolTalk Sample 1", 0);
create_ui_components();
/*
* Initialize ToolTalk, using the initial default session, and
* obtain the file descriptor that will become active whenever
* ToolTalk has a message for this process.
*/
my_procid = tt_open();
ttfd = tt_fd();
/*
* Arrange for Motif to call receive_tt_message when the ToolTalk
* file descriptor becomes active.
*/
XtAppAddInput(app, ttfd, (XtPointer) XtInputReadMask,
receive_tt_message, 0);
/*
* Create and register a pattern so ToolTalk knows we are interested
* in "ttsample1_value" messages within the session we join.
*/
pat = tt_pattern_create();
tt_pattern_category_set(pat, TT_OBSERVE);
tt_pattern_scope_add(pat, TT_SESSION);
tt_pattern_op_add(pat, "ttsample1_value");
tt_pattern_register(pat);
/*
* Join the default session
*/
tt_session_join(tt_default_session());
/*
* Turn control over to Motif.
*/
XtRealizeWidget(toplevel);
XtAppMainLoop(app);
/*
* Before leaving, allow ToolTalk to clean up.
*/
tt_close();
exit(0);
}
/*
* When the button is pressed, broadcast the new slider value.
*/
void
broadcast_value(widget, client_data, call_data)
Widget widget;
XtPointer client_data, call_data;
{
int slider_value;
Tt_message msg_out;
/*
* Create and send a ToolTalk notice message
* ttsample1_value(in int &lt;new value)
*/
XtVaGetValues(slider, XmNvalue, &amp;slider_value, 0);
slider_value++;
XtVaSetValues(slider, XmNvalue, slider_value, 0);
msg_out = tt_pnotice_create(TT_SESSION, "ttsample1_value");
tt_message_arg_add(msg_out, TT_IN, "integer", NULL);
tt_message_arg_ival_set(msg_out, 0, slider_value);
tt_message_send(msg_out);
/*
* Since this message is a notice, we don't expect a reply, so
* there's no reason to keep a handle for the message.
*/
tt_message_destroy(msg_out);
}
/*
* When a ToolTalk message is available, receive it; if it's a
* ttsample1_value message, update the gauge with the new value.
*/
void
receive_tt_message(client_data, fid, id)
XtPointer client_data;
int *fid;
XtInputId *id;
{
Tt_message msg_in;
int mark;
int val_in;
char *op;
Tt_status err;
msg_in = tt_message_receive();
/*
* It's possible that the file descriptor would become active
* even though ToolTalk doesn't really have a message for us.
* The returned message handle is NULL in this case.
*/
if (msg_in == NULL) return;
/*
* Get a storage mark so we can easily free all the data
* ToolTalk returns to us.
*/
mark = tt_mark();
op = tt_message_op(msg_in);
err = tt_ptr_error(op);
if (err &gt; TT_WRN_LAST) {
printf( "tt_message_op(): %s\n", tt_status_message(err));
} else if (op != 0) {
if (0==strcmp("ttsample1_value", tt_message_op(msg_in))) {
tt_message_arg_ival(msg_in, 0, &amp;val_in);
XtVaSetValues(gauge, XmNvalue, val_in, 0);
}
}
tt_message_destroy(msg_in);
tt_release(mark);
return;
}
/*
* Straight Motif calls for creating the ui elements. No
* ToolTalk-specific code here.
*/
void
create_ui_components()
{
int decor;
Widget glabel, slabel;
XmString label;
base_frame = XtVaCreateManagedWidget("base_frame",
xmMainWindowWidgetClass, toplevel,
XmNwidth, 250,
XmNheight, 175,
0);
XtVaGetValues(base_frame, XmNmwmDecorations, &amp;decor, 0);
decor &amp;= ~MWM_DECOR_RESIZEH;
XtVaSetValues(base_frame, XmNmwmDecorations, &amp;decor, 0);
controls = XtVaCreateManagedWidget("controls",
xmFormWidgetClass, base_frame, NULL, 0, 0);
slabel = XtVaCreateManagedWidget("Send:",
xmLabelWidgetClass, controls,
XmNleftAttachment, XmATTACH_WIDGET,
XmNtopAttachment, XmATTACH_WIDGET,
XmNtopWidget, controls,
XmNtopOffset, 10,
XmNleftOffset, 5,
0);
slider = XtVaCreateManagedWidget("slider",
xmScaleWidgetClass, controls,
XmNleftAttachment, XmATTACH_WIDGET,
XmNleftWidget, controls,
XmNleftOffset, 10,
XmNtopAttachment, XmATTACH_WIDGET,
XmNtopWidget, slabel,
XmNscaleWidth, 225,
XmNscaleHeight, 18,
XmNminimum, 0,
XmNmaximum, 25,
XmNorientation, XmHORIZONTAL,
XmNshowValue, TRUE,
0);
glabel = XtVaCreateManagedWidget("Received:",
xmLabelWidgetClass, controls,
XmNleftAttachment, XmATTACH_WIDGET,
XmNtopAttachment, XmATTACH_WIDGET,
XmNleftOffset, 5,
XmNtopWidget, slider,
0);
gauge = XtVaCreateManagedWidget("gauge",
xmScaleWidgetClass, controls,
XmNleftAttachment, XmATTACH_WIDGET,
XmNleftWidget, controls,
XmNleftOffset, 10,
XmNtopAttachment, XmATTACH_WIDGET,
XmNtopWidget, glabel,
XmNorientation, XmHORIZONTAL,
XmNscaleWidth, 225,
XmNscaleHeight, 18,
XmNminimum, 0,
XmNmaximum, 25,
XmNshowValue, TRUE,
0);
label = XmStringCreateSimple("Broadcast");
button = XtVaCreateManagedWidget("button",
xmPushButtonWidgetClass, controls,
XmNtopWidget, gauge,
XmNtopAttachment, XmATTACH_WIDGET,
XmNtopOffset, 5,
XmNleftOffset, 75,
XmNleftWidget, controls,
XmNleftAttachment, XmATTACH_WIDGET,
XmNbottomOffset, 5,
XmNlabelString, label,
0);
XmStringFree(label);
XtAddCallback(button, XmNactivateCallback, broadcast_value, 0);
}
</programlisting>
</Sect1>
</Appendix>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

78
cde/doc/C/guides/ttGuide/appc.sgm Normal file
View File

@@ -0,0 +1,78 @@
<!-- $XConsortium: appc.sgm /main/6 1996/09/08 19:35:15 rws $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<Title Id="TTUG.ttmt.mkr.1">Writing Thread-Safe ToolTalk Applications</Title>
<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>writing</secondary></indexterm>
<Para>The multithread-safe ToolTalk
library enables application developers to write
multithreaded applications for ToolTalk without having to manage
locks on ToolTalk resources explicitly in their application code.
An extended version of the <Filename>Xthreads.h</Filename> thread API wrappers
is used; therefore, multithreaded libtt should be readily
portable to various thread implementations.
</para>
<para>To protect internal libtt resources, a process-wide lock is introduced and
maintained. Unlike the case of window toolkits, few applications
spend a significant amount of their time in libtt, so the added
parallelism of more fine-grained locking techniques would not
result in a perceptible performance improvement.
</para>
<para>A few ToolTalk global values, such as the default <literal>procid</literal> and the
storage stack manipulated by the <function>tt_mark</function> and <function>tt_release</function> API
calls, must have a consistent state as seen by one thread across
ToolTalk API calls &mdash these values are made into thread-specific data.
Additional API calls are introduced to initialize this behavior
and manipulate the new data. When a thread-specific value has been
set for the current thread, existing API calls are modified
to reference the thread-specific values instead of the
process-wide values. If no thread-specific value
has been set for the current thread, then the process-wide value
is used.
</para>
<para>The multithreaded feature may not be
available on all platforms. For this reason, an API for querying for the
existence of the feature is included in the library. The intent is
that even platforms that do not enable the multithreaded
feature should implement the new API calls, returning
<Symbol>TT_ERR_UNIMP</Symbol> for the thread-specific ones; this
allows application developers to do run-time checks without
having to deal with the problem of unresolved symbols.
</para>
<para>Following is a summary of the API:
</para>
<itemizedlist>
<listitem>
<para><function>tt_feature_enabled</function> &mdash determine whether the specified feature has been enabled.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_feature_enabled</secondary></indexterm><indexterm><primary>tt_feature_enabled function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>tt_feature_required</function> &mdash declare that the specified feature is required, and enable it if it is available.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_feature_required</secondary></indexterm><indexterm><primary>tt_feature_required function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>tt_thread_session_set</function> &mdash set the default session for this thread.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_thread_session_set</secondary></indexterm><indexterm><primary>tt_thread_session_set function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>tt_thread_session</function> &mdash fetch the default session for this thread.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_thread_session</secondary></indexterm><indexterm><primary>tt_thread_session function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>tt_thread_procid_set</function> &mdash set the default process ID for this thread.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_thread_procid_set</secondary></indexterm><indexterm><primary>tt_thread_procid_set function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>tt_procid_session</function> &mdash return the session associated with the specified process ID.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>tt_procid_session</secondary></indexterm><indexterm><primary>tt_procid_session function</primary></indexterm>
</para>
</listitem>
<listitem>
<para><function>Tttt_c</function> &mdash typedefs and enums.<indexterm><primary>thread-safe ToolTalk applications</primary><secondary>Tttt_c</secondary></indexterm><indexterm><primary>Tttt_c typdef/enum declarations</primary></indexterm>
</para>
</listitem>
</itemizedlist>

386
cde/doc/C/guides/ttGuide/appd.sgm Normal file
View File

@@ -0,0 +1,386 @@
<!-- $XConsortium: appd.sgm /main/7 1996/09/08 19:35:23 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Appendix Id="TTUG.Examp.div.0">
<Title>Examples</Title>
<Sect1 Id="TTUG.Examp.div.1">
<Title>Example Ttdt_contract_cb</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.1"> is an example of a typical algorithm of a
<Filename><IndexTerm>
<Primary>Ttdt_contract_cb</Primary>
</IndexTerm>Ttdt_contract_cb</Filename> callback for an application that handles its own
Pause/Resume/Quit requests but allows the toolkit to handle the X11-related
requests.</Para>
<Note>
<Para>This example callback deals with the case when the <Emphasis>contract</Emphasis> parameter
has a value other than zero and can, therefore, also be used as the
<Filename>Ttdt_contract_cb</Filename> callback passed to <Filename>ttdt_message_accept</Filename>.</Para>
</Note>
<Example Id="TTUG.Examp.tbl.1">
<Title Id="TTUG.Examp.mkr.1">Typical Algorithm of Ttdt_contract_cb</Title>
<ProgramListing>Tt_message
myContractCB(
Tt_message msg,
void *clientdata,
Tt_message contract
)
{
char *opString = tt_message_op( msg );
Tttk_op op = tttk_string_op( opString );
tt_free( opString );
int silent = 0;
int force = 0;
Boolean cancel = False;
Boolean sensitive = True;
char *status, command;
switch (op) {
case TTDT_QUIT:
tt_message_arg_ival( msg, 0, &amp;silent );
tt_message_arg_ival( msg, 1, &amp;force );
if (contract == 0) {
/* Quit entire application */
cancel = ! myQuitWholeApp( silent, force );
} else {
/* Quit just the specified request being worked on */
cancel = ! myCancelThisRequest(contract, silent, force);
}
if (cancel) {
/* User canceled Quit; fail the Quit request */
tttk_message_fail( msg, TT_DESKTOP_ECANCELED, 0, 1 );
} else {
tt_message_reply( msg );
tttk_message_destroy( msg );
}
return 0;
case TTDT_PAUSE:
sensitive = False;
case TTDT_RESUME:
if (contract == 0) {
int already = 1;
if (XtIsSensitive( myTopShell) != sensitive) {
already = 0;
XtSetSensitive( myTopShell, sensitive );
}
if (already) {
tt_message_status_set(msg,TT_DESKTOP_EALREADY);
}
} else {
if (XtIsSensitive( thisShell) == sensitive) {
tt_message_status_set(msg,TT_DESKTOP_EALREADY);
} else {
XtSetSensitive( thisShell, sensitive );
}
}
tt_message_reply( msg );
tttk_message_destroy( msg );
return 0;
case TTDT_GET_STATUS:
if (contract == 0) {
status = &ldquo;Message about status of entire app&ldquo;;
} else {
status = &ldquo;Message about status of this request&ldquo;;
}
tt_message_arg_val_set( msg, 0, status );
tt_message_reply( msg );
tttk_message_destroy( msg );
return 0;
case TTDT_DO_COMMAND:
if (! haveExtensionLanguage) {
tttk_message_fail( msg, TT_DESKTOP_ENOTSUP, 0, 1 );
return 0;
}
command = tt_message_arg_val( msg, 0 );
result = myEval( command );
tt_free( command );
tt_message_status_set( msg, result );
if (tt_is_err( result )) {
tttk_message_fail( msg, result, 0, 1 );
} else {
tt_message_reply( msg );
tttk_message_destroy( msg );
}
return 0;
}
/* Unrecognized message; do not consume it */
return msg;
}
</ProgramListing>
</Example>
</Sect1>
<Sect1 Id="TTUG.Examp.div.2">
<Title>Example<IndexTerm>
<Primary>Ttdt_file_cb</Primary>
</IndexTerm>
Ttdt_file_cb</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;2'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.2"> is an example of a typical algorithm of this callback.</Para>
<Example Id="TTUG.Examp.tbl.2">
<Title Id="TTUG.Examp.mkr.2">Typical Algorithm of Ttdt_file_cb</Title>
<ProgramListing>Tt_message
myFileCB(
Tt_message msg,
Tttk_op op,
char *pathname,
int trust,
int isMe
)
{
tt_free( pathname );
Tt_status status = TT_OK;
switch (op) {
case TTDT_MODIFIED:
if ((_modifiedByMe) &amp;&amp; (! isMe)) {
// Hmm, the other editor either does not know or
// does not care that we are already modifying the
// file, so the last saver will win.
} else {
// Interrogate user if she ever modifies the buffer
_modifiedByOther = 1;
XtAddCallback( myTextWidget, XmNmodifyVerifyCallback,
myTextModifyCB, 0 );
}
break;
case TTDT_GET_MODIFIED:
tt_message_arg_ival_set( msg, 1, _modifiedByMe );
tt_message_reply( msg );
break;
case TTDT_SAVE:
status = mySave( trust );
if (status == TT_OK) {
tt_message_reply( msg );
} else {
tttk_message_fail( msg, status, 0, 0 );
}
break;
case TTDT_REVERT:
status = myRevert( trust );
if (status == TT_OK) {
tt_message_reply( msg );
} else {
tttk_message_fail( msg, status, 0, 0 );
}
break;
case TTDT_REVERTED:
if (! isMe) {
_modifiedByOther = 0;
}
break;
case TTDT_SAVED:
if (! isMe) {
_modifiedByOther = 0;
int choice = myUserChoice( myContext, myBaseFrame,
&ldquo;Another tool has saved &ldquo;
&ldquo;this file.&ldquo;, 2, &ldquo;Ignore&ldquo;,
&ldquo;Revert&ldquo; );
switch (choice) {
case 1:
myRevert( 1 );
break;
}
}
break;
case TTDT_MOVED:
case TTDT_DELETED:
// Do something appropriate
break;
}
tttk_message_destroy( msg );
return 0;
}
</ProgramListing>
</Example>
</Sect1>
<Sect1 Id="TTUG.Examp.div.3">
<Title>Example<IndexTerm>
<Primary>Ttmedia_load_msg_cb</Primary>
</IndexTerm>
Ttmedia_load_msg_cb</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.3"> is an example of a typical algorithm of this callback.</Para>
<Example Id="TTUG.Examp.tbl.3">
<Title Id="TTUG.Examp.mkr.3">Typical Algorithm of Ttmedia_load_msg_cb</Title>
<ProgramListing>Tt_message
myLoadMsgCB(
Tt_message msg,
void *clientData,
Tttk_op op,
unsigned char *contents,
int len,
char *file
)
{
if (len > 0) {
// Replace data with len bytes in contents
} else if (file != 0) {
// Replace data with data read from file
}
if (op == TTME_DEPOSIT) {
tt_message_reply( msg );
}
tttk_message_destroy( msg );
return 0;
}
</ProgramListing>
</Example>
</Sect1>
<Sect1 Id="TTUG.Examp.div.4">
<Title>Example<IndexTerm>
<Primary>Ttmedia_load_pat_cb</Primary>
</IndexTerm>
Ttmedia_load_pat_cb</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;4'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.4"> is an example of a typical algorithm of this callback.</Para>
<Example Id="TTUG.Examp.tbl.4">
<Title Id="TTUG.Examp.mkr.4">Typical Algorithm of Ttmedia_load_pat_cb</Title>
<ProgramListing>Tt_message
myAcmeSheetLoadCB(
Tt_message msg,
void *client_data,
Tttk_op op,
Tt_status diagnosis,
unsigned char *contents,
int len,
char *file,
char *docname
)
{
Tt_status status = TT_OK;
if (diagnosis != TT_OK) {
// toolkit detected an error
if (tt_message_status( msg) == TT_WRN_START_MESSAGE) {
//
// Error is in start message! We now have no
// reason to live, so tell main() to exit().
//
myAbortCode = 2;
}
// let toolkit handle the error
return msg;
}
if ((op == TTME_COMPOSE) &amp;&amp; (file == 0)) {
// open empty new buffer
} else if (len > 0) {
// load contents into new buffer
} else if (file != 0) {
if (ttdt_Get_Modified( msg, file, TT_BOTH, myCntxt, 5000 )) {
switch (myUserChoice( &ldquo;Save, Revert, Ignore?&ldquo; )) {
case 0:
ttdt_Save( msg, file, TT_BOTH, myCntxt, 5000 );
break;
case 1:
ttdt_Revert( msg, file, TT_BOTH, myCntxt, 5000);
break;
}
}
// load file into new buffer
} else {
tttk_message_fail( msg, TT_DESKTOP_ENODATA, 0, 1 );
tt_free( contents ); tt_free( file ); tt_free( docname );
return 0;
}
int w, h, x, y = INT_MAX;
ttdt_sender_imprint_on( 0, msg, 0, &amp;w, &amp;h, &amp;x, &amp;y, myCntxt, 5000 );
positionMyWindowRelativeTo( w, h, x, y );
if (maxBuffersAreNowOpen) {
// Un-volunteer to handle future requests until less busy
tt_ptype_undeclare( &ldquo;Acme_Calc&ldquo; );
}
if (tt_message_status( msg) == TT_WRN_START_MESSAGE) {
//
// Join session before accepting start message,
// to prevent unnecessary starts of our ptype
//
ttdt_session_join( 0, myContractCB, myShell, 0, 1 );
}
ttdt_message_accept( msg, myContractCB, myShell, 0, 1, 1 );
tt_free( contents ); tt_free( file ); tt_free( docname );
return 0;
}
</ProgramListing>
</Example>
</Sect1>
<Sect1 Id="TTUG.Examp.div.5">
<Title>Example Ptype Signature for<IndexTerm>
<Primary>Ttmedia_ptype_declare</Primary>
</IndexTerm>
Ttmedia_ptype_declare Function</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;5'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.5"> is an example of the signature layout of a media ptype.</Para>
<Example Id="TTUG.Examp.tbl.5">
<Title Id="TTUG.Examp.mkr.5">Example of Media Ptype Signature Layout</Title>
<ProgramListing>ptype Acme_Calc {
start &ldquo;acalc&ldquo;;
handle:
/*
* Display Acme_Sheet
* Include in tool's ptype if tool can display a document.
*/
session Display( in Acme_Sheet contents) => start opnum = 1;
session Display( in Acme_Sheet contents,
in messageID counterfoil) => start opnum = 2;
session Display( in Acme_Sheet contents,
in title docName) => start opnum = 3;
session Display( in Acme_Sheet contents,
in messageID counterfoil,
in title docName) => start opnum = 4;
/*
* Edit Acme_Sheet
* Include in tool's ptype if tool can edit a document.
*/
session Edit( inout Acme_Sheet contents) => start opnum = 101;
session Edit( inout Acme_Sheet contents,
in messageID counterfoil) => start opnum = 102;
session Edit( inout Acme_Sheet contents,
in title docName) => start opnum = 103;
session Edit( inout Acme_Sheet contents,
in messageID counterfoil,
in title docName) => start opnum = 104;
/*
* Compose Acme_Sheet
* Include in tool's ptype if tool can compose a document from scratch.
*/
session Edit( out Acme_Sheet contents) => start opnum = 201;
session Edit( out Acme_Sheet contents,
in messageID counterfoil) => start opnum = 202;
session Edit( out Acme_Sheet contents,
in title docName) => start opnum = 203;
session Edit( out Acme_Sheet contents,
in messageID counterfoil,
in title docName) => start opnum = 204;
/*
* Mail Acme_Sheet
* Include in tool's ptype if tool can mail a document.
*/
session Mail( in Acme_Sheet contents) => start opnum = 301;
session Mail( inout Acme_Sheet contents) => start opnum = 311;
session Mail( inout Acme_Sheet contents,
in title docName) => start opnum = 313;
session Mail( out Acme_Sheet contents) => start opnum = 321;
session Mail( out Acme_Sheet contents,
in messageID counterfoil) => start opnum = 323;
};
</ProgramListing>
</Example>
</Sect1>
<Sect1 Id="TTUG.Examp.div.6">
<Title>Example for Xt Input Handler Function</Title>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;D&hyphen;6'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Examp.mkr.6"> is an example for the Xt input handler function.</Para>
<Example Id="TTUG.Examp.tbl.6">
<Title Id="TTUG.Examp.mkr.6">Xt Input Handler Function Example</Title>
<ProgramListing>int myTtFd;
char *myProcID;
myProcID = ttdt_open( &amp;myTtFd, &ldquo;WhizzyCalc&ldquo;, &ldquo;Acme&ldquo;, &ldquo;1.0&ldquo;, 1 );
/* ... */
/* Process the message that started us, if any */
tttk_Xt_input_handler( myProcID, 0, 0 );
/* ... */
XtAppAddInput( myContext, myTtFd, (XtPointer)XtInputReadMask,
<IndexTerm><Primary>tttk_Xt_input_handler</Primary></IndexTerm>
tttk_Xt_input_handler, myProcID );
</ProgramListing>
</Example>
</Sect1>
</Appendix>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

75
cde/doc/C/guides/ttGuide/book.sgm Normal file
View File

@@ -0,0 +1,75 @@
<!-- $XConsortium: book.sgm /main/12 1996/08/19 13:25:49 cdedoc $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook//EN" [
<!ENTITY % ISOpublishing PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN">
%ISOpublishing;
<!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN">
%ISOnumeric;
<!ENTITY % ISOdiacritical PUBLIC "ISO 8879-1986//ENTITIES Diacritical Marks//EN">
%ISOdiacritical;
<!ENTITY % ISOgeneraltech PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN">
%ISOgeneraltech;
<!ENTITY % ISOalatin1 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN">
%ISOalatin1;
<!ENTITY % ISOalatin2 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN">
%ISOalatin2;
<!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN">
%ISOgreek;
<!ENTITY % ISOboxandline PUBLIC "ISO 8879-1986//ENTITIES Box and Line Drawing//EN">
%ISOboxandline;
<!ENTITY % BEntities SYSTEM "./ttGuide/BEntity.sgm">
%BEntities;
<!ENTITY GSCr SYSTEM "./ttGuide/credits.sgm">
<!ENTITY Pref SYSTEM "./ttGuide/preface.sgm">
<!ENTITY Intro SYSTEM "./ttGuide/ch01.sgm">
<!ENTITY HTU SYSTEM "./ttGuide/ch02.sgm">
<!ENTITY ttsnp SYSTEM "./ttGuide/ch03.sgm">
<!ENTITY tttrc SYSTEM "./ttGuide/ch04.sgm">
<!ENTITY MsgTk SYSTEM "./ttGuide/appa.sgm">
<!ENTITY BrCast SYSTEM "./ttGuide/appb.sgm">
<!ENTITY ttmt SYSTEM "./ttGuide/appc.sgm">
<!ENTITY Examp SYSTEM "./ttGuide/appd.sgm">
<!ENTITY % Solaris "INCLUDE">
<!ENTITY % CDE.C.XO "IGNORE">
<!ENTITY % CDE.C.CDE "INCLUDE">
<!ENTITY % CDE.C.HP "IGNORE">
<!ENTITY % CDE.C.SUN "IGNORE">
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment: ToolTalk Messaging Guide</Title>
&GSCr;
&Pref;
&Intro;
&HTU;
&ttsnp;
&tttrc;
&MsgTk;
&BrCast;
<Appendix Id="TTUG.ttmt.div.1">
&ttmt;
</appendix>
&Examp;
</Book>

672
cde/doc/C/guides/ttGuide/ch01.sgm Normal file
View File

@@ -0,0 +1,672 @@
<!-- $XConsortium: ch01.sgm /main/8 1996/09/08 19:35:32 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter Id="TTUG.Intro.div.1">
<Title Id="TTUG.Intro.mkr.1">Introducing the ToolTalk Service</Title>
<Para>As computer users increasingly demand that independently developed
applications work together, inter-operability is becoming an important theme
for software developers. By cooperatively using each other's facilities,
inter&hyphen;operating applications offer users capabilities that would be difficult to
provide in a single application. The ToolTalk service is designed to facilitate the
development of inter-operating applications that serve individuals and work
groups.</Para>
<Para>The<IndexTerm>
<Primary>ToolTalk service</Primary>
</IndexTerm>
ToolTalk service enables independent applications to communicate with
each other without having direct knowledge of each other. Applications create
and send ToolTalk messages to communicate with each other. The ToolTalk
service receives these messages, determines the recipients, and then delivers
the messages to the appropriate applications, as shown in
<!--Original XRef content: 'Figure&numsp;1&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.Intro.mkr.2">.</Para>
<Figure>
<Title Id="TTUG.Intro.mkr.2">Applications Using the ToolTalk Service</Title>
<Graphic Entityref="TTUG.Intro.fig.1" Id="TTUG.Intro.grph.1"></Graphic>
</Figure>
<Sect1 Id="TTUG.Intro.div.2">
<Title>What Kind of Work Problems Can the ToolTalk Service Solve?</Title>
<Para>This section describes some of the<IndexTerm>
<Primary>inter-operability problems, solved by the ToolTalk service</Primary>
</IndexTerm>
inter-operability problems the ToolTalk
service is designed to solve. The ToolTalk service is the appropriate technology
to use if your application needs:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Tool inter&hyphen;changeability</Para>
</ListItem>
<ListItem>
<Para>Control integration</Para>
</ListItem>
<ListItem>
<Para>Network&hyphen;transparent events that are not owned by any well&hyphen;known server
(for example, an X server) and that do not have any predictable set of
listeners</Para>
</ListItem>
<ListItem>
<Para>Automatic tool invocation</Para>
</ListItem>
<ListItem>
<Para>A widely-available distributed object system</Para>
</ListItem>
<ListItem>
<Para>Persistent objects</Para>
</ListItem>
</ItemizedList>
<Para>Of course, there are some inter-operability problems for which the ToolTalk
service may not be the appropriate technology to use. However, when your
application needs to solve both sorts of problems (that is, a combination of
those inter-operability problems for which the ToolTalk service is designed to
solve and those problems for which it is not designed), you can use the
ToolTalk service in combination with other technologies.</Para>
<Sect2 Id="TTUG.Intro.div.3">
<Title>Tool Inter-changeability</Title>
<Para>Use the ToolTalk service when you want<IndexTerm>
<Primary>plug-and-play</Primary>
</IndexTerm>
plug-and-play capability. The term
<Emphasis>plug-and-play</Emphasis> means that any tool can be replaced by any other tool that follows
the same protocol. That is, any tool that follows a given ToolTalk protocol can
be placed (plugged) into your computing environment and perform (play)
those functions indicated by the protocol. Tools can be mixed and matched,
without modification and without having any specific built-in knowledge of
each other.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.4">
<Title>Control Integration</Title>
<Para>Use the ToolTalk service when your application requires<IndexTerm>
<Primary>control integration</Primary>
</IndexTerm>
control integration.
The term <Emphasis>control integration</Emphasis> indicates a group of tools working together toward
a common end without direct user intervention. The ToolTalk service enables
control integration through its easy and flexible facilities for issuing arbitrary
requests, either to specific tool instances or to anonymous service providers.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.5">
<Title>Network-Transparent Events</Title>
<Para>Use the ToolTalk service when your application needs to generate or receive<IndexTerm>
<Primary>network-transparent events</Primary>
</IndexTerm>
network-transparent events. To be useful, traditional event mechanisms (such
as signals and window-system events) require special circumstances; for
example, you must know a process or window ID. The ToolTalk service allows
events to be expressed naturally: in terms of the file to which the event refers,
or the group of processes on the network to which the event is applicable. The
ToolTalk service delivers events (called <Emphasis>notices</Emphasis>) to any interested process
anywhere on the network. ToolTalk notices are a flexible and easy way to
provide extensibility for your system.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.6">
<Title>Automatic Tool Invocation</Title>
<Para>Use the ToolTalk service when your application needs network-transparent<IndexTerm>
<Primary>automatic invocation</Primary>
</IndexTerm>
automatic invocation. The ToolTalk service lets you describe the messages that,
when sent from any location on the network, should cause your tool to be
invoked. The ToolTalk auto-start facility is easier to use and less host-specific
than the conventional <Filename MoreInfo="RefEntry">inetd</Filename>(1) facility.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.7">
<Title>Distributed-Object System</Title>
<Para>Use ToolTalk when you need to build your application on a<IndexTerm>
<Primary>distributed object system</Primary>
</IndexTerm>
distributed-object
system that is available across a wide variety of platforms. ToolTalk's object
system can be used by any application on all the popular UNIX platforms,
regardless of whether the application</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Is single- or multi-threaded</Para>
</ListItem>
<ListItem>
<Para>Has a command-line or graphical user interface</Para>
</ListItem>
<ListItem>
<Para>Uses its own event loop, or that of a window-system toolkit</Para>
</ListItem>
</ItemizedList>
<Note>
<Para>Programs coded to the ToolTalk object-oriented messaging interface are
<Symbol Role="Variable">not</Symbol> portable to<IndexTerm>
<Primary>OMG-compliant systems</Primary>
</IndexTerm>
CORBA&hyphen;compliant systems without source changes.</Para>
</Note>
</Sect2>
<Sect2 Id="TTUG.Intro.div.8">
<Title>Persistent Objects</Title>
<Para>Use the ToolTalk service when your application needs to place<IndexTerm>
<Primary>objects, persistent</Primary>
</IndexTerm>
objects
unobtrusively in the UNIX file system.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.9">
<Title>Scenarios Illustrating How the ToolTalk Service Helps Solve Work Problems</Title>
<Para>The s<IndexTerm>
<Primary>scenarios illustrating the ToolTalk service in use</Primary>
</IndexTerm>
cenarios in this section illustrate how the ToolTalk service helps users
solve their work problems. The message protocols used in these scenarios are
hypothetical.</Para>
<Sect3 Id="TTUG.Intro.div.10">
<Title>Using the ToolTalk Desktop Services Message Set</Title>
<Para>The<IndexTerm>
<Primary>ToolTalk message sets</Primary>
<Secondary>Desktop</Secondary>
</IndexTerm>
ToolTalk<IndexTerm>
<Primary>Desktop Services Message Set</Primary>
</IndexTerm>
Desktop Services Message Set allows an application to integrate
and control other applications without user intervention. This section presents
two scenarios (
<!--Original XRef content: '&xd2;The Smart Desktop'--><XRef Role="SectionTitle" Linkend="TTUG.Intro.mkr.3"> and
<!--Original XRef content: '&xd2;Integrated Toolsets&xd3; on page&numsp;6'--><XRef Role="SecTitleAndPageNum" Linkend="TTUG.Intro.mkr.4">) that
show how the Desktop Services Message Set might be implemented.</Para>
<Sect4 Id="TTUG.Intro.div.11">
<Title Id="TTUG.Intro.mkr.3">The Smart Desktop</Title>
<Note>
<Para>The scenario in this section is intended to illustrate how the ToolTalk
service can be used in an application-level program that interprets user
requests; it is <Symbol Role="Variable">not</Symbol> intended to illustrate how the Common Desktop Environment
product implements the ToolTalk service to interpret user
requests.</Para>
</Note>
<Para>A common user requirement for a graphic user interface (GUI) front-end is the
ability to have data files be aware (or &ldquo;know&rdquo;) of their applications. To do this,
an application-level program is needed to interpret the user's requests.
Examples of application-level programs (known as <Emphasis>smart desktops</Emphasis>) are the
Apple Macintosh&reg; finder, Microsoft Windows&trade; File Manager, and the
Common Desktop Desktop File Manager. The key common requirements for
smart desktops are:</Para>
<OrderedList Remap="List1">
<ListItem>
<Para>Takes a file</Para>
</ListItem>
<ListItem>
<Para>Determines its application</Para>
</ListItem>
<ListItem>
<Para>Invokes the application</Para>
</ListItem>
</OrderedList>
<Para>The ToolTalk Service provides additional flexibility by allowing classes of tools
to edit a specific data type. The following scenario illustrates how the Desktop
Services Message Set might be implemented as a smart desktop transparent to
the end-user.</Para>
<OrderedList>
<ListItem>
<Para>Diane double-clicks on the File Manager icon.</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para>The File Manager opens and displays the files in Diane's current directory.</Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>Diane double-clicks on an icon for a data file.</Para>
<OrderedList Remap="List2">
<ListItem>
<Para>The File Manager requests that the file represented by the icon be
displayed. The File Manager encodes the file type in the <Symbol Role="Variable">display</Symbol> message.</Para>
</ListItem>
<ListItem>
<Para>The ToolTalk session manager matches the pattern in the <Symbol Role="Variable">display</Symbol> message
to a registered application (in this case, the Icon Editor), and finds an
instance of the application running on Diane's desktop.</Para>
<Note>
<Para>If the ToolTalk session manager does not find a running instance of the
application, it checks the statically-defined<IndexTerm>
<Primary>process type (ptype)</Primary>
</IndexTerm>
process types (ptypes) and starts
an application that best matches the pattern in the message. If none of the
ptypes matches, the session manager returns failure to the File Manager
application.</Para>
</Note>
</ListItem>
<ListItem>
<Para>The Icon Editor accepts the <Symbol Role="Variable">display</Symbol> message, de&hyphen;iconifies itself, and raises
itself to the top of the display.</Para>
</ListItem>
</OrderedList>
</ListItem>
<ListItem>
<Para>Diane manually edits the file.</Para>
</ListItem>
</OrderedList>
</Sect4>
<Sect4 Id="TTUG.Intro.div.12">
<Title Id="TTUG.Intro.mkr.4">Integrated Toolsets</Title>
<Para>Another significant application for which the Desktop Services Message Set
can be implemented is <Emphasis>integrated toolsets</Emphasis>. These environments can be applied in
vertical applications (such as a CASE developer toolset) or in horizontal
environments (such as compound documents). Common to both of these
applications is the premise that the overall solution is built from specialized
applications designed to perform one particular task well. Examples of
integrated toolset applications are text editors, drawing packages, video or
audio display tools, compiler front&hyphen;ends, and debuggers. The integrated toolset
environment requires applications to interact by calling on each other to
handle user requests. For example, to display video, an editor calls a video
display program; or to check a block of completed code, an editor calls a
compiler.</Para>
<Para>The following scenario shows how the Desktop Services Message Set might be
implemented as an integrated toolset:</Para>
<OrderedList>
<ListItem>
<Para>Bruce is working on a compound document using his favorite editor.</Para>
<Para>He decides to change the some of the source code text.</Para>
</ListItem>
<ListItem>
<Para>Bruce double-clicks on the source code text.</Para>
<OrderedList Remap="List2">
<ListItem>
<Para>The Document Editor first determines the text represents source code
and then determines which file contains the source code.</Para>
</ListItem>
<ListItem>
<Para>The Document Editor sends an <Emphasis>edit</Emphasis> message request, using the file name
as a parameter for the message.</Para>
</ListItem>
<ListItem>
<Para>The ToolTalk session manager matches the pattern in the <Emphasis>edit</Emphasis> message to
a registered application (in this case, the Source Code Editor), and finds
an instance of the application running on Bruce's desktop.</Para>
<Note>
<Para>If the ToolTalk session manager does not find a running instance of the
application, it checks the statically-defined ptypes and starts an application
that best matches the pattern in the message. If none of the ptypes matches, the
session manager returns failure to the Document Editor application.</Para>
</Note>
</ListItem>
<ListItem>
<Para>The Source Code Editor accepts the <Emphasis>edit</Emphasis> message request.</Para>
</ListItem>
<ListItem>
<Para>The Source Code Editor determines that the source code file is under
configuration control, and sends a message to check out the file.</Para>
</ListItem>
<ListItem>
<Para>The Source Code Control application accepts the message and creates a
read-write copy of the requested file. It then passes the name of the file
back to the Source Code Editor.</Para>
</ListItem>
<ListItem>
<Para>The Source Code Editor opens a window that contains the source file.</Para>
</ListItem>
</OrderedList>
</ListItem>
<ListItem>
<Para>Bruce edits the source code text.</Para>
</ListItem>
</OrderedList>
</Sect4>
</Sect3>
<Sect3 Id="TTUG.Intro.div.13">
<Title>Using the ToolTalk Document and Media Exchange Message Set</Title>
<Para>The<IndexTerm>
<Primary>ToolTalk message sets</Primary>
<Secondary>Document and Media Exchange</Secondary>
</IndexTerm>
ToolTalk<IndexTerm>
<Primary>Document and Media Exchange Message Set</Primary>
</IndexTerm>
Document and Media Exchange Message Set is very flexible and
robust. This section illustrates three uses of the ToolTalk Document and Media
Exchange Message Set:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Integrating multimedia into an authoring application</Para>
</ListItem>
<ListItem>
<Para>Adding multimedia extensions to an existing application</Para>
</ListItem>
<ListItem>
<Para>Extending the <Emphasis>cut-and-paste</Emphasis> facility of X with a media-translation facility</Para>
</ListItem>
</ItemizedList>
<Sect4 Id="TTUG.Intro.div.14">
<Title>Integrating Multimedia Functionality</Title>
<Para>Integrating multimedia functionality into an application allows end-users of
the application to embed various media types in their documents.</Para>
<Para>Typically, an icon that represents the media object is embedded in the
document. Upon selection of an embedded object, the ToolTalk service
automatically invokes an appropriate external media application and the object
is played as illustrated in the following scenario.</Para>
<OrderedList Remap="List1">
<ListItem>
<Para>Daniel opens a document that contains multimedia objects.</Para>
</ListItem>
<ListItem>
<Para>The window shows the document with several icons representing various
media types (such as sound, video, and graphics).</Para>
</ListItem>
<ListItem>
<Para>Daniel double-clicks on the sound icon.</Para>
<Para>A sound application (called a <Emphasis>player</Emphasis>) is launched and the embedded
recording is played.</Para>
</ListItem>
<ListItem>
<Para>To edit the recording, Daniel clicks once on the icon to select it and uses the
third mouse button to display an Edit menu.</Para>
<Para>An editing application is launched, and Daniel edits the media object.</Para>
</ListItem>
</OrderedList>
</Sect4>
<Sect4 Id="TTUG.Intro.div.15">
<Title>Adding Multimedia Extensions to Existing Applications</Title>
<Para>The ToolTalk Document and Media Exchange Message Set also allows an
application to use other multimedia applications to extend its features or
capabilities. For example, a Calendar Manager can be extended to use the
Audio Tool to play a sound file as a reminder of an appointment, as illustrated
in the following scenario:</Para>
<OrderedList Remap="List1">
<ListItem>
<Para>Shelby opens her Calendar Manager and sets an appointment.</Para>
</ListItem>
<ListItem>
<Para>Shelby clicks on an Audio Response button, which causes the Audio Tool to
start.</Para>
</ListItem>
<ListItem>
<Para>Shelby records her message; for example, &ldquo;Bring the report.&rdquo;</Para>
</ListItem>
</OrderedList>
<Para>When Shelby's appointment reminder is executed, the Calendar Manager will
start the Audio Tool and play Shelby's recorded reminder.</Para>
</Sect4>
<Sect4 Id="TTUG.Intro.div.16">
<Title>Extending the X Cut-and-Paste Facility</Title>
<Para>The ToolTalk Document and Media Exchange Message Set can support an
extensible, open-ended translation facility. The following scenario illustrates
how an extensible multimedia <Emphasis>cut and paste</Emphasis> facility could work:</Para>
<OrderedList Remap="List1">
<ListItem>
<Para>Maria opens two documents that are different media types.</Para>
</ListItem>
<ListItem>
<Para>Maria selects a portion of Document A and cuts the portion using the
standard <Emphasis>X</Emphasis>-windowing <Emphasis>cut</Emphasis> facility.</Para>
</ListItem>
<ListItem>
<Para>Maria then pastes the cut portion into Document B.</Para>
<OrderedList Remap="List2">
<ListItem>
<Para>Document B negotiates the transfer of the cut data with Document A.</Para>
</ListItem>
<ListItem>
<Para>If Document B does not understand any of the types offered by
Document&numsp;A, it requests that Document&numsp;A sends it a <Emphasis>tagged media type</Emphasis>.
Document B uses the tagged media type to broadcast a ToolTalk message
requesting a translation of the media type to a media type it understands.</Para>
</ListItem>
<ListItem>
<Para>A registered translation utility accepts the request and returns the
translated version of the media type to Document B.</Para>
</ListItem>
<ListItem>
<Para>The paste of the translated data into Document B is performed.</Para>
</ListItem>
</OrderedList>
</ListItem>
</OrderedList>
</Sect4>
</Sect3>
</Sect2>
</Sect1>
<Sect1 Id="TTUG.Intro.div.17">
<Title><IndexTerm>
<Primary>how applications use ToolTalk messages</Primary>
</IndexTerm>How Applications Use ToolTalk Messages</Title>
<Para>Applications create, send, and receive ToolTalk messages to communicate with
other applications<Interface Class="Button">.<IndexTerm>
<Primary>senders</Primary>
</IndexTerm>
Senders</Interface> create, fill in, and send a message; the ToolTalk
service determines the recipients and delivers the message to the<IndexTerm>
<Primary>recipients</Primary>
</IndexTerm>
recipients.
Recipients retrieve messages, examine the information in the message, and
then either discard the message or perform an operation and reply with the
results.</Para>
<Sect2 Id="TTUG.Intro.div.18">
<Title><IndexTerm>
<Primary>sending ToolTalk messages</Primary>
</IndexTerm><IndexTerm>
<Primary>messages</Primary>
<Secondary>sending</Secondary>
</IndexTerm>Sending ToolTalk Messages</Title>
<Para><IndexTerm>
<Primary>ToolTalk messages</Primary>
</IndexTerm>ToolTalk messages are simple structures that contain fields for address, subject,
and delivery information. To send a ToolTalk message, an application obtains
an empty message, fills in the message attributes, and sends the message. The
sending application needs to provide the following information:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Is the message a notice or a request (that is, should the recipient respond to
the message)?</Para>
</ListItem>
<ListItem>
<Para>What interest does the recipient share with the sender? (For example, is the
recipient running in a specific user session or interested in a specific file?)</Para>
</ListItem>
</ItemizedList>
<Para>To narrow the focus of the message delivery, the sending application can
provide more information in the message.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.19">
<Title>Message Patterns</Title>
<Para>An important ToolTalk<IndexTerm>
<Primary>features, of ToolTalk</Primary>
</IndexTerm>
feature is that senders need to know little about the
recipients because applications that want to receive messages explicitly state
what message they want to receive. This information is registered with the
ToolTalk service in the form of <Emphasis>message patterns</Emphasis>.</Para>
<Para>Applications can provide message patterns to the ToolTalk service at
installation time and while the application is running. Message patterns are
created similarly to the way a message is created; both use the same type of
information. For each type of message an application wants to receive, it
obtains an empty message pattern, fills in the attributes, and registers the
pattern with the ToolTalk service.<IndexTerm>
<Primary>message patterns</Primary>
</IndexTerm>
These message patterns usually match the
message protocols that applications have agreed to use. Applications can add
more patterns for individual use.</Para>
<Para>When the ToolTalk service receives a message from a sending application, it
compares the information in the message to the register patterns. Once matches
have been found, the ToolTalk service<IndexTerm>
<Primary>messages</Primary>
<Secondary>determining recipients of</Secondary>
</IndexTerm>
delivers copies of the message to all
recipients.</Para>
<Para>For each pattern that describes a message an application wants to receive, the
application declares whether it can <Emphasis><IndexTerm>
<Primary>messages</Primary>
<Secondary>handling</Secondary>
</IndexTerm>handle</Emphasis> or <Emphasis><IndexTerm>
<Primary>messages</Primary>
<Secondary>observing</Secondary>
</IndexTerm>observe</Emphasis> the message. Although
many applications can observe a message, only one application can handle the
message to ensure that a requested operation is performed only once. If the
ToolTalk service cannot find a handler for a request, it returns the message to
the sending application indicating that delivery failed.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.20">
<Title><IndexTerm>
<Primary>receiving ToolTalk messages</Primary>
</IndexTerm><IndexTerm>
<Primary>messages</Primary>
<Secondary>receiving</Secondary>
</IndexTerm>Receiving ToolTalk Messages</Title>
<Para>When the ToolTalk service determines that a message needs to be delivered to
a specific process, it creates a copy of the message and notifies the process that
a message is waiting. If a receiving application is not running, the ToolTalk
service looks for instructions (provided by the application at installation time)
on how to start the application.</Para>
<Para>The process retrieves the message and examines its contents.</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>If the message contains a notice that an operation has been performed, the
process reads the information and then discards the message.</Para>
</ListItem>
<ListItem>
<Para>If the message contains a request to perform an operation, the process
performs the operation and returns the result of the operation in a reply to
the original message. Once the reply has been sent, the process discards the
original message.</Para>
</ListItem>
</ItemizedList>
</Sect2>
</Sect1>
<Sect1 Id="TTUG.Intro.div.21">
<Title>ToolTalk Message Distribution</Title>
<Para>The ToolTalk service provides two methods of<IndexTerm>
<Primary>addressing messages, methods of</Primary>
</IndexTerm><IndexTerm>
<Primary>messages</Primary>
<Secondary>methods of addressing</Secondary>
</IndexTerm>
addressing messages:
<Emphasis>process&hyphen;oriented</Emphasis> messages and <Emphasis>object-oriented</Emphasis> messages.</Para>
<Sect2 Id="TTUG.Intro.div.22">
<Title>Process-Oriented Messages</Title>
<Para><IndexTerm>
<Primary>process-oriented messages</Primary>
</IndexTerm><IndexTerm>
<Primary>messages</Primary>
<Secondary>process-oriented</Secondary>
</IndexTerm>Process-oriented messages are addressed to processes. Applications that create
a process-oriented message address the message to either a specific process or
to a particular type of process. Process-oriented messages are a good way for
existing applications to begin communication with other applications.
Modifications to support process-oriented messages are straightforward and
usually take a short time to implement.</Para>
</Sect2>
<Sect2 Id="TTUG.Intro.div.23">
<Title>Object-Oriented Messages</Title>
<Para><IndexTerm>
<Primary>object-oriented messages</Primary>
</IndexTerm><IndexTerm>
<Primary>messages</Primary>
<Secondary>object-oriented</Secondary>
</IndexTerm>Object-oriented messages are addressed to objects managed by applications.
Applications that create an object-oriented message address the message to
either a specific object or to a particular type of object. Object-oriented
messages are particularly useful for applications that currently use objects or
that are to be designed around objects. If an existing application is not
object&hyphen;oriented, the ToolTalk service allows applications to identify portions of
application data as objects so that applications can begin to communicate about
these objects.</Para>
<Note>
<Para>Programs coded to the ToolTalk object-oriented messaging interface are
<Symbol Role="Variable">not</Symbol> portable to<IndexTerm>
<Primary>OMG-compliant systems</Primary>
</IndexTerm>
CORBA&hyphen;compliant systems without source changes.</Para>
</Note>
</Sect2>
<Sect2 Id="TTUG.Intro.div.24">
<Title>Determining Message Delivery</Title>
<Para>To<IndexTerm>
<Primary>determining who receive messages</Primary>
</IndexTerm>
determine which groups receive messages, you <Emphasis>scope</Emphasis> your messages.
Scoping limits the delivery of messages to a particular session or file.</Para>
<Sect3 Id="TTUG.Intro.div.25">
<Title>Sessions</Title>
<Para>A<IndexTerm>
<Primary>session, ToolTalk concept of</Primary>
</IndexTerm>
<Emphasis>session</Emphasis> is a group of processes that have an instance of the ToolTalk message
server in common (refer to Appendix C for information on thread-safe session management).
When a process opens communication with the ToolTalk
service, a default session is located (or created, if a session does not already
exist) and a <Emphasis>process identifier</Emphasis> (<Emphasis>procid</Emphasis>) is assigned to the process. Default sessions
are located either through an environment variable (called &ldquo;process tree
sessions&rdquo;) or through the X display (called &ldquo;X sessions&rdquo;).</Para>
<Para>The concept of a session is important in the delivery of messages. Senders can
scope a message to a session and the ToolTalk service will deliver it to all
processes that have message patterns that reference the current session. To
update message patterns with the current<IndexTerm>
<Primary>session identifier (sessid)</Primary>
</IndexTerm>
<Emphasis>session identifier</Emphasis> (sessid), applications
join the session.</Para>
</Sect3>
<Sect3 Id="TTUG.Intro.div.26">
<Title>Files</Title>
<Para>A container for data that is of interest to applications is called a<IndexTerm>
<Primary>files</Primary>
<Secondary>ToolTalk concept of</Secondary>
</IndexTerm>
<Symbol Role="Variable">file</Symbol> in this
book.</Para>
<Para>The concept of a file is important in the delivery of messages. Senders can
scope a message to a file and the ToolTalk service will deliver it to all processes
that have message patterns that reference the file without regard to the
process's default session. To update message patterns with the current file path
name, applications join the file.</Para>
<Para>You can also scope a message to a file within a session. The ToolTalk service
will deliver the message to all processes that reference both the file and session
in their message patterns.</Para>
<Note>
<Para>The<IndexTerm>
<Primary>file scoping, restrictions</Primary>
</IndexTerm>
file scoping feature is restricted to NFS&reg; and UFS file systems.</Para>
</Note>
</Sect3>
</Sect2>
</Sect1>
<Sect1 Id="TTUG.Intro.div.27">
<Title><IndexTerm>
<Primary>modifying your application to use the ToolTalk service</Primary>
</IndexTerm>Modifying Applications to Use the ToolTalk Service</Title>
<Para>Before you modify your application to use the ToolTalk service, you must
define (or locate) a ToolTalk<IndexTerm>
<Primary>message protocol</Primary>
</IndexTerm>
<Emphasis>message protocol</Emphasis>: a set of ToolTalk messages that
describe operations applications agree to perform. The message protocol
specification includes the set of messages and how applications should behave
when they receive the messages.</Para>
<Para>To use the ToolTalk service, an application calls ToolTalk functions from the
ToolTalk<IndexTerm>
<Primary>application programming interface (API)</Primary>
</IndexTerm>
API. The ToolTalk API provides functions to register with the ToolTalk
service, to create message patterns, to send messages, to receive messages, to
examine message information, and so on. To modify your application to use
the ToolTalk service, you must first include the ToolTalk API header file in your
program. You also need to modify your application to:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Initialize the ToolTalk service and join a session</Para>
</ListItem>
<ListItem>
<Para>Register message patterns with the ToolTalk service</Para>
</ListItem>
<ListItem>
<Para>Send and receive messages</Para>
</ListItem>
<ListItem>
<Para>Unregister message patterns and leave your ToolTalk session</Para>
</ListItem>
</ItemizedList>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

604
cde/doc/C/guides/ttGuide/ch02.sgm Normal file
View File

@@ -0,0 +1,604 @@
<!-- $XConsortium: ch02.sgm /main/8 1996/08/31 15:12:59 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter Id="TTUG.HTU.div.1">
<Title Id="TTUG.HTU.mkr.1">Using ToolTalk Messaging</Title>
<indexterm><primary>messages</primary><secondary>general information</secondary></indexterm>
<note>
<para>Some code fragments shown in this chapter are taken from a
ToolTalk demo program called <literal>broadcast</literal>. See the directory
<filename>/usr/dt/examples/tt</filename> for the source code, <filename>Makefile</filename>
and <filename>README</filename> file.
</para>
</note>
<Sect1 Id="TTUG.HTU.div.2">
<title>Telling Your Application about ToolTalk Functionality</title>
<para>Before your application can use the inter-operability functionality
provided by the ToolTalk service and the Messaging Toolkit, it needs to
know where the ToolTalk libraries and toolkit reside.
</para>
<Sect2 Id="TTUG.HTU.div.3">
<title>Using the Messaging Toolkit and Including ToolTalk Commands</title>
<para>To use the ToolTalk service, an application calls ToolTalk functions
from the ToolTalk application programming interface (API). The Messaging
Toolkit provides higher-level functions than the ToolTalk API, such as
functions to register with the ToolTalk service, to create message
patterns, to send messages, to receive messages, and to examine message
information. To modify your application to use the ToolTalk service and
toolkit, you must include the following header files:
</para>
<indexterm><primary>header files</primary></indexterm>
<programlisting>#include &lt;Tt/tt_c.h&gt; /* ToolTalk Header File */
#include &lt;Tt/tttk.h&gt; /* Messaging Toolkit Header File */
</programlisting>
</sect2>
<Sect2 Id="TTUG.HTU.div.4">
<title>Using the ToolTalk Library</title>
<indexterm><primary>library, ToolTalk</primary></indexterm>
<para>The ToolTalk library is located in the directory:
</para>
<programlisting>/usr/dt/lib
</programlisting>
<para>The library name is platform-dependent (for example, on Solaris it is named
<filename>libtt.so</filename> and on HP-UX is its named
<filename>libtt.sl</filename>).
</para>
</sect2>
</sect1>
<Sect1 Id="TTUG.HTU.div.5">
<title>Before You Start Coding</title>
<para>Before you can incorporate the Messaging Toolkit functionality into your
application, you need to determine the way that your tool will work with
other tools. There are several basic questions you need to ask:
</para>
<itemizedlist>
<listitem>
<para>How will these tools work together?
</para>
</listitem>
<listitem>
<para>What kinds of operations can these tools perform?
</para>
</listitem>
<listitem>
<para>What kinds of operations can these tools ask other tools to perform?
</para>
</listitem>
<listitem>
<para>What events will these tools generate that may interest other tools?
(What types of messages will these tools want to send?)
</para>
</listitem>
<listitem>
<para>What events generated by other tools will be of interest to these
tools? (What types of messages will these tools want to receive?)
</para>
</listitem>
</itemizedlist>
<para>To best answer these questions, you need to understand the difference
between events and operations, and how the ToolTalk service handles
messages regarding each of these.
</para>
<Sect2 Id="TTUG.HTU.div.6">
<title>What Is the Difference Between an Event and an Operation?</title>
<indexterm><primary>event defined</primary></indexterm>
<indexterm><primary>operation defined</primary></indexterm>
<para>An <emphasis>event</emphasis> is an announcement that something has happened. An event is
simply a news bulletin. The sending process has no formal expectations
as to whether any other process will hear about the event, or whether an
action is taken as a consequence of the event. When a process uses the
ToolTalk service to inform interested processes that an event has
occurred, it sends a <emphasis>notice</emphasis>. Since the sending process does not expect a
reply, an event cannot fail.
</para>
<para>An <emphasis>operation</emphasis> is an inquiry or an action. The requesting process makes an
inquiry or requests that an operation be performed. The requesting
process expects a result to be returned and needs to be informed of the
status of the inquiry or action. When a process uses the ToolTalk
service to ask another tool to perform an operation, it sends a <emphasis>request</emphasis>.
The ToolTalk service delivers the request to interested processes and
informs the sending process of the status of the request.
</para>
<Sect3 Id="TTUG.HTU.div.7">
<title>Sending Notices</title>
<para>When your application sends a ToolTalk notice, it will not receive a
reply or be informed about whether or not any tool pays attention to the
notice. It is important to make the notice an impartial report of the
event as it happens. For example, if your tool sends the Desktop
Services message <literal>Modified</literal>, it may expect any listening tools to react in
a given way. Your tool, however, should not care, and does not need to
be informed about whether any or no other tool reacts to the message; it
only wants to report the event, <Symbol>THE_USER_HAS_MADE_CHANGES_TO_THIS</Symbol>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.8">
<title>Sending Requests</title>
<para>When your application sends a ToolTalk request, it expects one tool to
perform the indicated operation, or to answer the inquiry, and return a
reply message. For example, if your tool sends the Desktop Services
message <literal>Get_Modified</literal>, it should expect notification that the message was
delivered and the action performed. The ToolTalk service guarantees that
either a reply will be returned by the receiving process or the sender
will be informed of the request's failure.
</para>
<para>You can identify requests in three ways:
</para>
<itemizedlist>
<listitem>
<para>By identifying the operations requested by your tool that can fail.
</para>
</listitem>
<listitem>
<para>By identifying the operations your tool can perform for other tools.
</para>
</listitem>
<listitem>
<para>By identifying the operations your tool will want other tools to perform.
</para>
</listitem>
</itemizedlist>
<para>A good method to use to identify these operations is to develop a
scenario that outlines the order of events and operations that you
expect your tool to perform and have performed.
</para>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.9">
<title>Developing a Scenario</title>
<para>A scenario outlines the order of the events and operations that a tool
will expect to perform and to have performed. For example, the following
scenario outlines the events a generic editor could expect to perform
and to have performed:
</para>
<orderedlist>
<listitem>
<para>User double-clicks on a document icon in the File Manager.
The file opens in the editor, which is started by the system if one is
not already running. (If another tool has modifications to the text
pending for the document, the user is asked whether the other tool
should save the text changes or revert to the last saved version of the
document.)
</para>
</listitem>
<listitem>
<para>User inserts text.
</para>
</listitem>
<listitem>
<para>User saves the document. (If another tool has modifications pending
for the document, the user is asked whether to modify the document.)
</para>
</listitem>
<listitem>
<para>User exits the editor. (If text has unsaved changes, the user is
asked whether to save or discard the changes before quitting the file.)
</para>
</listitem>
</orderedlist>
<para>Once the scenario is done, you can answer your basic questions.
</para>
<Sect3 Id="TTUG.HTU.div.10">
<title>How Will the Tools Work Together?</title>
<itemizedlist>
<listitem>
<para>The File Manager requests that an editor open a document for
editing.
</para>
</listitem>
<listitem>
<para>Each instance of the editor notifies other interested instances of
changes it makes to the state of the document.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.11">
<title>What Kinds of Operations Do the Tools Perform?</title>
<itemizedlist>
<listitem>
<para>Each instance of the editor can answer questions about itself and
its state, such as &ldquo;What is your status?&rdquo;
</para>
</listitem>
<listitem>
<para>Each instance of the editor has the capability of performing
operations such as:
</para>
<itemizedlist>
<listitem>
<para>Iconifying and de-iconifying
</para>
</listitem>
<listitem>
<para>Raising to front and lowering to back
</para>
</listitem>
<listitem>
<para>Editing a document
</para>
</listitem>
<listitem>
<para>Displaying a document (read-only)
</para>
</listitem>
<listitem>
<para>Quitting
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.12">
<title>What Kinds of Operations Can the Tools Ask Other Tools to Perform?</title>
<itemizedlist>
<listitem>
<para>The File Manager must request that the editor open a document for editing.
</para>
</listitem>
<listitem>
<para>An instance of the editor can ask another instance of the editor to save changes to the open document.
</para>
</listitem>
<listitem>
<para>An instance of the editor can ask another instance of the editor to revert to the last saved version of the open document.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.13">
<title>What Events Will the Tools Generate that May Interest Other Tools?</title>
<itemizedlist>
<listitem>
<para>The document has been opened.
</para>
</listitem>
<listitem>
<para>The document has been modified.
</para>
</listitem>
<listitem>
<para>The document has been reverted to last saved version.
</para>
</listitem>
<listitem>
<para>The document has been saved.
</para>
</listitem>
<listitem>
<para>An instance of the editor has been exited.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.14">
<title>What Events Generated by Other Tools Will Be of Interest to This Tool?</title>
<itemizedlist>
<listitem>
<para>The document has been opened.
</para>
</listitem>
<listitem>
<para>The document has been modified.
</para>
</listitem>
<listitem>
<para>The document has been reverted to last saved version.
</para>
</listitem>
<listitem>
<para>The document has been saved.
</para>
</listitem>
<listitem>
<para>An instance of the editor has been exited.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<Sect1 Id="TTUG.HTU.div.15">
<title>Preparing Your Application for Communication</title>
<para>The ToolTalk service provides you with a complete set of functions for
application integration. Using the functionality provided with the
ToolTalk Messaging Toolkit, your applications can be made to &ldquo;speak&rdquo; to
other applications that are ToolTalk-compliant. This section describes
how to add the kinds of ToolTalk functions you need to include in your
application so that it can communicate with other ToolTalk-aware
applications that follow the same protocols.
</para>
<Sect2 Id="TTUG.HTU.div.16">
<title>Creating a Ptype File</title>
<indexterm><primary>ptype file, creating</primary></indexterm>
<para>The ToolTalk types mechanism is designed to help the ToolTalk service
route messages. When your tool declares a ptype (process type), the message patterns
listed in it are automatically registered. The ToolTalk service then
matches messages it receives to these registered patterns. These static
message patterns remain in effect until the tool closes communication
with the ToolTalk service.
</para>
<para>The ToolTalk Types Database already has installed ptypes for tools
bundled with this release. You can extract a list of the installed
ptypes from the ToolTalk Types Database, as follows:
</para>
<screen>% tt_type_comp -d <symbol role="variable">user | system | network</symbol> -P
</screen>
<para>The names of the ptypes are printed out in source format.
</para>
<para>To generate a list of the installed ptypes including their signatures:
</para>
<screen>% tt_type_comp -d <symbol role="variable">user | system | network</symbol> -p
</screen>
<para>For all other tools (that is, tools that are not included in this
release), you need to first create a ptype file to define the ptype for
your application, and then compile the ptype with the ToolTalk type
compiler, <filename>tt_type_comp</filename>. To define a ptype, you need to include the
following information in a file:
</para>
<itemizedlist>
<listitem>
<para>A process-type identifier (<literal>ptid</literal>).
</para>
</listitem>
<listitem>
<para>An optional start string &mdash; The ToolTalk service executes this command, if necessary, to start a process running the program.
</para>
</listitem>
<listitem>
<para>Signatures &mdash; Describes the <Symbol>TT_PROCEDURE</Symbol>-addressed messages that the
program wants to receive. Messages to be observed are described
separately from messages to be handled.
</para>
</listitem>
</itemizedlist>
<para>To create a ptype file, you can use any text editor
(such as <command>vi</command>, <command>emacs</command>, or <command>dtpad</command>).
</para>
<para>After you have created a ptype file, you need to install the ptype by
running the ToolTalk type compiler. On the command line, type:
</para>
<screen>% tt_type_comp <symbol role="variable">file_name.ptype</symbol>
</screen>
<para>where <symbol role="variable">file_name.ptype</symbol>
is the name of the ptype file.
</para>
<Sect3 Id="TTUG.HTU.div.17">
<title>Testing for Existing Ptypes in Current Session</title>
<indexterm><primary>ptypes, testing for existence of</primary></indexterm>
<para>The ToolTalk service provides the following function to test if a given
ptype is already registered in the current session:
</para>
<programlisting>tt_ptype_exists(const char *ptype_id)
</programlisting>
<para>where <symbol role="variable">ptype_id</symbol> is the identifier of the session to test for registration.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.18">
<title>Merging a Compiled Ptype File into a Currently Running ttsession</title>
<para>The ToolTalk service provides the following function to merge a compiled
ToolTalk type file into the currently running <literal>ttsession</literal>:
</para>
<programlisting>tt_session_types_load (
const char *session,
const char *compile_types_file)
</programlisting>
<para>where <symbol role="variable">session</symbol> is the current default ToolTalk session and
<symbol role="variable">compiled_types_file</symbol> 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.
</para>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.19">
<title>Tasks Every ToolTalk-aware Application Needs to Perform</title>
<para>There are a number of tasks every ToolTalk-aware application needs to
perform, including:
</para>
<itemizedlist>
<listitem>
<para>Initializing the toolkit.
</para>
</listitem>
<listitem>
<para>Joining a ToolTalk session and registering patterns.
</para>
</listitem>
<listitem>
<para>Adding the ToolTalk service to its event loop.
</para>
</listitem>
</itemizedlist>
<para>This section provides examples of the ToolTalk code you need to include
in your application so that it can perform these tasks.
</para>
<Sect3 Id="TTUG.HTU.div.20">
<title>Initializing the Toolkit</title>
<indexterm><primary>toolkit initialization</primary></indexterm>
<para>Your application needs to initialize and register with the initial
ToolTalk session. To do so, it first needs to obtain a process
identifier (procid). The following code fragment shows how to obtain a
procid and how to initialize the toolkit.
</para>
<programlisting>char *procid = ttdt_open(
int *tt_fd,
const char *ptype_name,
const char *vendor_name,
const char *version,
int send_started)
</programlisting>
<note>
<para>Your application must call <function>ttdt_open</function> before any other ToolTalk
calls are made; otherwise, errors may occur.
</para>
</note>
</sect3>
<Sect3 Id="TTUG.HTU.div.21">
<title>Joining the ToolTalk Session and Registering Message Patterns</title>
<indexterm><primary>message patterns, registering</primary></indexterm>
<para>Before your application can receive messages, it must join a ToolTalk
session and register the message patterns that are to be matched. The
ttdt_session_join function registers patterns and default callbacks for
many standard desktop message interfaces.
</para>
<programlisting>Tt_pattern *sess_patt = ttdt_session_join(
const char *session_id,
Ttdt_contract_cb cb,
Widget shell,
void *client_data,
int join)
</programlisting>
<para>Note that if an application has ptypes installed, it will normally call
the function <function>ttmedia_ptype_declare</function> before calling <function>ttdt_session_join</function>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.22">
<title>Adding the ToolTalk Service to Event Loop</title>
<para>Your application also needs to add the ToolTalk service to its event
loop. If the application is an Xt client, it would use <function>XtAppAddInput</function> as
follows:
</para>
<programlisting>XtAppAddInput (app_context,
tt_fd(),
(XtPointer) XtInputReadMask,
tttk_Xt_input_handler,
client_data)
</programlisting>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.23">
<title>Tasks ToolTalk-aware Editor Applications Need to Perform</title>
<para>In addition to the duties described in the section &ldquo;Tasks Every
ToolTalk-aware Application Needs to Perform&rdquo; in this chapter,
ToolTalk-aware editor applications may also need to perform other tasks,
including:
</para>
<itemizedlist>
<listitem>
<para>Declaring a ptype.
</para>
</listitem>
<listitem>
<para>Writing a media load callback.
</para>
</listitem>
<listitem>
<para>Accepting a contract to handle a message.
</para>
</listitem>
<listitem>
<para>Replying when a request has been completed.
</para>
</listitem>
</itemizedlist>
<para>This section provides examples of the ToolTalk code you need to include
in your editor application so that it can perform these additional
tasks.
</para>
<Sect3 Id="TTUG.HTU.div.24">
<title>Declaring a Ptype</title>
<indexterm><primary>ptype, declaring</primary></indexterm>
<para>If an application has a ptype file that has been installed, the ptypes
need to be associated with the application. The convenience function for
declaring this association is ttmedia_ptype_declare:
</para>
<programlisting>Tt_status status = ttmedia_ptype_declare(
char *ptype_name,
int base_opnum,
Ttmedia_load_pat_cb cb,
void *client_data,
int declare)
</programlisting>
<para>The callback <function>cb</function> is invoked when the application is asked to service
a request supported by the ptype <symbol role="variable">ptype_name</symbol>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.25">
<title>Writing a Media Load Pattern Callback</title>
<para>Before coding an editor application to include any ToolTalk functions,
you need to write a media load callback routine. This callback is
invoked when another application responds to your application's
<function>ttmedia_load</function> call.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.26">
<title>Accepting a Contract to Handle a Message</title>
<para>When an application receives a message in its <function>ttmedia_ptype_declare</function>
handler, it should call the following function to accept a contract to
handle the request.
</para>
<programlisting>Tt_pattern *desktop_patts = ttdt_message_accept (
Tt_message contract,
Ttdt_contract_cb cb,
Widget shell,
void *client_data,
int accept,
int send_status)
</programlisting>
</sect3>
<Sect3 Id="TTUG.HTU.div.27">
<title>Replying When Request Is Completed</title>
<para>After your application has completed the operation requested (for
example to edit a document), it must reply to the sending application.
The following function can be used to do the reply and to return the
edited contents of the text to the sender.
</para>
<programlisting>Tt_message msg = ttmedia_load_reply (
Tt_message contract,
const unsigned char *new_contents,
int new_length,
int reply_and_destroy)
</programlisting>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.28">
<title>Optional Tasks ToolTalk-aware Editor Applications Can Perform</title>
<para>In addition to the tasks described in the section &ldquo;Tasks ToolTalk-aware
Editor Applications Need to Perform&rdquo; in this chapter, editor
applications can also perform other optional tasks such as tasks that
use desktop file interfaces to coordinate with other editors. This
section mentions some of the ToolTalk functions you need to include in
your editor application so that it can perform these optional tasks.
</para>
<Sect3 Id="TTUG.HTU.div.29">
<title>Requesting Modify, Revert, or Save Operations</title>
<para>The following functions can be used to request modify, revert, or save
operations:
</para>
<itemizedlist>
<listitem>
<para><function>ttdt_Get_Modified</function>
</para>
</listitem>
<listitem>
<para><function>ttdt_Revert</function>
</para>
</listitem>
<listitem>
<para><function>ttdt_Save</function>
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.30">
<title>Notifying When a File Is Modified, Reverted, or Saved</title>
<para>The function <function>ttdt_file_event</function> can be used to notify other ToolTalk
applications that your application's file has been modified, has
reverted, or has been saved.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.31">
<title>Quitting a File</title>
<para>The function <function>ttdt_file_quit</function> unregisters interest in ToolTalk events
about a file and destroys the associated pattern.
</para>
</sect3>
</sect2>
</sect1>
</chapter>

175
cde/doc/C/guides/ttGuide/ch03.sgm Normal file
View File

@@ -0,0 +1,175 @@
<!-- $XConsortium: ch03.sgm /main/6 1996/09/08 19:35:41 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter Id="TTUG.ttsnp.div.1">
<Title Id="TTUG.ttsnp.mkr.1">Using TTSnoop to Debug
Messages and Patterns</Title>
<Para><Emphasis><IndexTerm>
<Primary>TTSnoop</Primary>
</IndexTerm></Emphasis>TTSnoop is a tool provided to create and send custom&hyphen;constructed ToolTalk
messages. You can also use TTSnoop as a tool to selectively monitor any or all
ToolTalk messages.</Para>
<Sect1 Id="TTUG.ttsnp.div.2">
<Title>About TTSnoop</Title>
<Para>TTSnoop is a useful interactive tool that you can use to become familiar with
TookTalk concepts and API calls as well as to perform demonstrations. In
addition, TTSnoop is a valuable debugging tool when you are developing
applications.</Para>
<Para>You can use TTSnoop to monitor for messages that match more than one
pattern. When a matched message is displayed, the name of the pattern that
matched the entry can also be displayed.</Para>
<Para>You can add, edit, or delete messages and patterns to scrollable lists. TTSnoop
allows the definitions of multiple patterns and messages to be saved and
loaded from files. You can also define, save, and reload patterns and messages
particular to a category of applications (for example, DeskSet&trade; tools) as well
as associate messages and patterns with a user-defined name.</Para>
</Sect1>
<Sect1 Id="TTUG.ttsnp.div.3">
<Title>Where to Find TTSnoop</Title>
<Para>The TTSnoop program resides in the directory<IndexTerm>
<Primary>/usr/dt/bin/ttsnoop</Primary>
</IndexTerm>
<Filename>/usr/dt/bin</Filename>.</Para>
</Sect1>
<Sect1 Id="TTUG.ttsnp.div.4">
<Title>Starting TTSnoop</Title>
<Para>To start the program, enter the following command on the command line:</Para>
<ProgramListing>ttsnoop [ -t ]</ProgramListing>
<Para>The<IndexTerm><Primary>-t option, of ttsnoop command[t]</Primary>
</IndexTerm> <Filename>-t</Filename> option displays the ToolTalk API calls that are being used to construct a
particular pattern or message.
<!--Original XRef content: 'Table&numsp;3&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.ttsnp.mkr.2"> describes the menu options that are displayed
when TTSnoop starts.</Para>
<Table Id="TTUG.ttsnp.tbl.1" Frame="Topbot">
<Title Id="TTUG.ttsnp.mkr.2">TTSnoop Menu Options</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="1.25 in">
<ColSpec Colname="2" Colwidth="3.75 in">
<THead>
<Row>
<Entry><Para><Literal>Menu Option</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para>Snoop</Para></Entry>
<Entry><Para>Turn on/off tracing; get version information
</Para></Entry>
</Row>
<Row>
<Entry><Para>Message</Para></Entry>
<Entry><Para>Create, open, receive, and destroy messages</Para></Entry>
</Row>
<Row>
<Entry><Para>Pattern</Para></Entry>
<Entry><Para>Create, open, and destroy patterns</Para></Entry>
</Row>
<Row>
<Entry><Para>File</Para></Entry>
<Entry><Para>Numerous tasks, including joining a file</Para></Entry>
</Row>
<Row>
<Entry><Para>Session</Para></Entry>
<Entry><Para>Join a specific session; set the default session
</Para></Entry>
</Row>
<Row>
<Entry><Para>Ptype</Para></Entry>
<Entry><Para>Declare and undeclare a <literal>ptype</literal>; determine whether
a <literal>ptype</literal> exists
</Para></Entry>
</Row>
<Row>
<Entry><Para>Types</Para></Entry>
<Entry><Para>Generate a list of declared types; generate a list of ToolTalk-based actions
</Para></Entry>
</Row>
<Row>
<Entry><Para>Procid</Para></Entry>
<Entry><Para>Open, close, suspend, and resume a procid
</Para></Entry>
</Row>
<Row>
<Entry><Para>libc</Para></Entry>
<Entry><Para>Call <function>system()</function>, <function>putenv()</function>, <function>chdir()</function>, <function>pause()</function>, and <function>exit()</function>; use <function>exit()</function>
to exit <command>ttsnoop</command>
</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
</Sect1>
<Sect1 Id="TTUG.ttsnp.div.5">
<Title>Composing and Sending Messages</Title>
<Para>When you select <command>Message &hyphen;&gt; Create</command>, a dialog is posted that
enables you to
</para>
<itemizedlist>
<listitem>
<para>Create and send a message
</para>
</listitem>
<listitem>
<para>Create a template for a ptype
</para>
</listitem>
<listitem>
<para>Create a template for a ToolTalk type action
</para>
</listitem>
<listitem>
<para>Create a C language template for a message reply handler
</para>
</listitem>
</itemizedlist>
<para>To create a message, select the <command>Create &hyphen;&gt; Tt_message</command> option. The following may be
specified for a message:
</para>
<itemizedlist>
<listitem>
<para>The Scope (for example, File, Session, Both, or File in Session)
</para>
</listitem>
<listitem>
<para>The Session Id
</para>
</listitem>
<listitem>
<para>The Class (for example, Notice or Request)
</para>
</listitem>
<listitem>
<para>The Address (for example, Object, Handler, or Procedure)
</para>
</listitem>
<listitem>
<para>The Disposition (Discard, Queue, or Start)
</para>
</listitem>
<listitem>
<para>The Arguments
</para>
</listitem>
</itemizedlist>
</sect1>
<Sect1 Id="TTUG.ttsnp.div.9">
<Title>To Begin Snooping</Title>
<Para>To turn on the displaying of messages and pattern traffic, select
<command>Snoop &hyphen;&gt; On</command>.
</para>
</Sect1>
<Sect1 Id="TTUG.ttsnp.div.10">
<Title>To Stop Snooping</Title>
<Para>To turn off the displaying of messages and pattern traffic, select
<command>Snoop &hyphen;&gt; Off</command>.
</Para>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

635
cde/doc/C/guides/ttGuide/ch04.sgm Normal file
View File

@@ -0,0 +1,635 @@
<!-- $XConsortium: ch04.sgm /main/7 1996/10/30 14:41:46 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter Id="TTUG.tttrc.div.1">
<Title Id="TTUG.tttrc.mkr.1">Using ToolTalk Tracing</Title>
<Para>The ToolTalk<IndexTerm>
<Primary>ttsession trace</Primary>
</IndexTerm>
ttsession trace shows how ToolTalk pattern matches and delivers
every message ttsession sees. ToolTalk tracing for this release also</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Displays a single client's interactions with ToolTalk. This feature allows
implementors to focus on only one client.</Para>
</ListItem>
<ListItem>
<Para>Filters the ttsession trace by, for example, message type, sender, or receiver.</Para>
</ListItem>
</ItemizedList>
<Sect1 Id="TTUG.tttrc.div.2">
<Title>Accessing ToolTalk Tracing</Title>
<Para>A command new for this release,<IndexTerm>
<Primary>tttrace</Primary>
</IndexTerm><IndexTerm>
<Primary>ToolTalk commands</Primary>
<Secondary>tttrace</Secondary>
</IndexTerm>
<Command>tttrace</Command>, is the primary way to access
ToolTalk tracing. This command is similar in purpose and command&hyphen;line
interface to the<IndexTerm>
<Primary>truss command</Primary>
</IndexTerm>
<Command>truss</Command> command. It enables you to control the three kinds of
ToolTalk tracing. The<IndexTerm>
<Primary>tttrace command</Primary>
</IndexTerm>
<Command>tttrace</Command> command has two fundamental modes:<IndexTerm>
<Primary>server mode</Primary>
</IndexTerm>
<Symbol Role="Variable">server</Symbol>
mode and<IndexTerm>
<Primary>client mode</Primary>
</IndexTerm>
<Symbol Role="Variable">client</Symbol> mode.</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>In server mode, <Command>tttrace</Command> directs the indicated session to trace by sending it
a Session_Trace request.</Para>
</ListItem>
<ListItem>
<Para>In client mode, <Command>tttrace</Command> sets an environment variable and executes the
ToolTalk client command given on the command line. The environment
variable in the executed client instructs<IndexTerm>
<Primary>libtt</Primary>
</IndexTerm>
<Command>libtt</Command> whether, and how, to trace
client messaging and client API calls.</Para>
</ListItem>
</ItemizedList>
<Note>
<Para><Command>tttrace</Command> is not downward compatible with older servers or with
clients using older versions of <Command>libtt</Command>. While <Command>tttrace</Command> will detect and diagnose
older servers, it fails silently on clients using older versions of <Command>libtt</Command>.</Para>
</Note>
</Sect1>
<Sect1 Id="TTUG.tttrc.div.3">
<Title>Controlling Tracing</Title>
<Sect2 Id="TTUG.tttrc.div.4">
<Title>Controlling libtt Tracing</Title>
<Para>One way to control <Command>libtt</Command>'s tracing behavior is to set the<IndexTerm>
<Primary>environment variables</Primary>
<Secondary>$DT_TT_TRACE_SCRIPT</Secondary>
</IndexTerm>
environment variable
<ComputerOutput>$<IndexTerm>
<Primary>$DT_TT_TRACE_SCRIPT</Primary>
</IndexTerm>
TT_TRACE_SCRIPT</ComputerOutput>.</Para>
<Note>
<Para><Command>libtt</Command>'s tracing fails gracefully if the variable's value is corrupt or
inconsistent.</Para>
</Note>
</Sect2>
<Sect2 Id="TTUG.tttrc.div.5">
<Title>Controlling Client-Side Tracing</Title>
<Para>The<IndexTerm>
<Primary>tt_trace_control call</Primary>
</IndexTerm>
<Filename>tt_trace_control</Filename> call sets or clears an internal flag to control all
client&hyphen;side tracing. You can use this call to trace suspect areas in your code. The
format of this call is:</Para>
<ProgramListing>int tt_trace_control(int <Symbol Role="Variable">option</Symbol>)</ProgramListing>
<Para>where <Symbol Role="Variable">option</Symbol> 0 to turn traciing off; 1 to turn tracing on; and -1 to toggle tracing
on and off. When tracing is on, the extent of tracing is controlled by the<IndexTerm>
<Primary>tttrace command</Primary>
</IndexTerm>
<Filename>TT_TRACE_SCRIPT</Filename> variable or tracefile. This call returns the previous setting
of the trace flag.</Para>
</Sect2>
</Sect1>
<Sect1 Id="TTUG.tttrc.div.6">
<Title>Tracing Message Traffic in a ToolTalk Session</Title>
<Para>The<IndexTerm>
<Primary>Session_Trace request</Primary>
</IndexTerm>
Session_Trace request is a ToolTalk request that ttsession registers to
handle itself; that is, ttsession is the handler for the Session_Trace request. This
request can be sent by any ToolTalk client, and, although not recommended,
other ToolTalk clients can register to handle this request. (Note: This method
will cause tracing to <Symbol Role="Variable">not</Symbol> work.) The syntax for this request is:</Para>
<ProgramListing>[<Symbol Role="Variable">file</Symbol>] Session_Trace( in boolean <Symbol Role="Variable">on</Symbol>,
in boolean <Symbol Role="Variable">follow</Symbol>
[in attribute <Symbol Role="Variable">toPrint</Symbol>
|in state <Symbol Role="Variable">toTrace</Symbol>
|in op <Symbol Role="Variable">toTrace</Symbol>
|in handler_ptype <Symbol Role="Variable">toTrace</Symbol>
|in sender_ptype <Symbol Role="Variable">toTrace</Symbol>][...] );</ProgramListing>
<Para>The Session_Trace request turns message tracing in the scoped-to session on or
off.</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>If tracing is on and the file attribute of the request is set, subsequent trace
output is appended to the file named by the attribute.</Para>
</ListItem>
<ListItem>
<Para>If tracing is on and the file attribute is <Symbol Role="Variable">not</Symbol> set, tracing continues to the
current trace.</Para>
</ListItem>
</ItemizedList>
<Para>By default, <Emphasis>daemon</Emphasis> mode causes the output to go to the console of the host on
which ttsession is running; job-control mode causes the output to go to
ttsession's standard error.
<!--Original XRef content: 'Table&numsp;4&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.2"> describes the required and optional
arguments for this request.</Para>
<Table Id="TTUG.tttrc.tbl.1" Frame="Topbot">
<Title Id="TTUG.tttrc.mkr.2">Session_Trace Agurments</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.56191 in">
<ColSpec Colname="2" Colwidth="0.65667 in">
<ColSpec Colname="3" Colwidth="2.79167 in">
<THead>
<Row>
<Entry><Para><Literal>Argument</Literal></Para></Entry>
<Entry></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>boolean</Command> <Emphasis>on</Emphasis></Para></Entry>
<Entry><Para>Required</Para></Entry>
<Entry><Para>Turn tracing on or off. If no <Emphasis>toTrace</Emphasis> arguments
are included and <Emphasis>on</Emphasis> is true, the previous trace
settings are restored.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>boolean</Command> <Emphasis>follow</Emphasis></Para></Entry>
<Entry><Para>Required</Para></Entry>
<Entry><Para>Turn on client-side tracing for Invoked clients.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>attribute</Command> <Emphasis>toPrint</Emphasis></Para></Entry>
<Entry><Para>Optional</Para></Entry>
<Entry><Para>Print attribute(s) for each message traced.
Valid attributes are:</Para><Para>&bull; <Symbol Role="Variable">none</Symbol>&ndash;print only a one-line description of
traced messages (default)</Para><Para>&bull; <Symbol Role="Variable">all</Symbol>&ndash;print all attributes of traced messages</Para></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Command>state</Command> <Emphasis>toTrace</Emphasis></Para></Entry>
<Entry><Para>Optional</Para></Entry>
<Entry><Para>State(s) through which to trace messages. In
addition to the Tt_states defined in <Filename>tt_c.h</Filename>,
valid <Symbol Role="Variable">state</Symbol>s are:</Para><Para>&bull; <Emphasis>edge</Emphasis>&ndash;messages entering initial (<Filename>TT_SENT</Filename>)
and final (<Filename>TT_HANDLED</Filename>, <Command>TT_FAILED</Command>)
states.</Para><Para>&bull; <Emphasis>deliver</Emphasis>&ndash;all state changes and all client
deliveries.</Para><Para>&bull; <Emphasis>dispatch</Emphasis>&ndash;deliver + all patterns considered for
matching. (default)</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>op</Command> <Emphasis>toTrace</Emphasis></Para><Para><Filename>sender_ptype</Filename> <Emphasis>toTrace</Emphasis></Para><Para><Filename>handler_ptype</Filename> <Emphasis>toTrace</Emphasis></Para></Entry>
<Entry><Para>Optional</Para><Para>Optional</Para><Para>Optional</Para></Entry>
<Entry><Para>Trace messages that have <Emphasis>toTrace</Emphasis> as a value for
the indicated message attribute.</Para><Para>&bull; Any number of <Emphasis>toTrace</Emphasis> arguments may be
included in the request.</Para><Para><Emphasis>&bull; toTrace</Emphasis> may include <Command>sh</Command> wildcard characters.</Para><Para>&bull; If no toTrace argument is included for a
given message attribute, no value of that
attribute excludes a message from tracing.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>The current session tracing behavior changes only if this request is not failed.
On failure, the <ComputerOutput>tt_message_status</ComputerOutput> of the reply is set to one of the errors
described in
<!--Original XRef content: 'Table&numsp;4&hyphen;2'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.3">.</Para>
<Table Id="TTUG.tttrc.tbl.2" Frame="Topbot">
<Title Id="TTUG.tttrc.mkr.3">Error Messages Returned by Session_Trace Request</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="2.0 in">
<ColSpec Colname="2" Colwidth="3.0 in">
<THead>
<Row>
<Entry><Para><Literal>Error</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Filename><IndexTerm>
<Primary>TT_ERR_NO_MATCH</Primary>
</IndexTerm><IndexTerm>
<Primary>errors returned</Primary>
<Secondary>TT_ERR_NO_MATCH</Secondary>
</IndexTerm>TT_ERR_NO_MATCH</Filename></Para></Entry>
<Entry><Para>No handler could be found for the request.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command><IndexTerm>
<Primary>TT_ERR_APPFIRST + EACCES</Primary>
</IndexTerm><IndexTerm>
<Primary>errors returned</Primary>
<Secondary>TT_ERR_APPFIRST + EACCES</Secondary>
</IndexTerm>TT_ERR_APPFIRST + EACCES</Command></Para></Entry>
<Entry><Para>ttsession does not have permission to open or
create the trace file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command><IndexTerm>
<Primary>TT_ERR_APPFIRST + EISDIR</Primary>
</IndexTerm><IndexTerm>
<Primary>errors returned</Primary>
<Secondary>TT_ERR_APPFIRST + EISDIR</Secondary>
</IndexTerm>TT_ERR_APPFIRST + EISDIR</Command></Para></Entry>
<Entry><Para>The trace file is a directory.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command><IndexTerm>
<Primary>TT_ERR_APPFIRST + ENOSPC</Primary>
</IndexTerm><IndexTerm>
<Primary>errors returned</Primary>
<Secondary>TT_ERR_APPFIRST + ENOSPC</Secondary>
</IndexTerm>TT_ERR_APPFIRST + ENOSPC</Command></Para></Entry>
<Entry><Para>There is not enough space in the target file system
to create the trace file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command><IndexTerm>
<Primary>TT_ERR_APPFIRST + EEXIST</Primary>
</IndexTerm><IndexTerm>
<Primary>errors returned</Primary>
<Secondary>TT_ERR_APPFIRST + EEXIST</Secondary>
</IndexTerm>TT_ERR_APPFIRST + EEXIST</Command></Para></Entry>
<Entry><Para>Tracing is already occurring on another file.
ttsession resets the file attribute of the reply to
name the existing trace file. To trace to a different
file, first turn off tracing to the current trace file.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
</Sect1>
<Sect1 Id="TTUG.tttrc.div.7">
<Title>Tracing ToolTalk Calls and Messages through the Server</Title>
<Para>The<IndexTerm>
<Primary>tttrace function</Primary>
</IndexTerm><IndexTerm>
<Primary>ToolTalk functions</Primary>
<Secondary>tttrace</Secondary>
</IndexTerm>
<Command>tttrace</Command> function traces message traffic through the server for the
indicated ToolTalk session, or runs a command with ToolTalk client tracing
turned on. If neither the session nor the command is given, the default session
is traced. By default, tracing terminates when <Command>tttrace</Command> exits. The syntax for
this function is:</Para>
<ProgramListing>tttrace [-0FCa] [-o <Symbol Role="Variable">outfile</Symbol> ] [-S <Symbol Role="Variable">session</Symbol> | <Symbol Role="Variable">command</Symbol>]
tttrace [-e <Symbol Role="Variable">script</Symbol> | -f <Symbol Role="Variable">scriptfile</Symbol> ] [-S <Symbol Role="Variable">session</Symbol> | <Symbol Role="Variable">command</Symbol>]</ProgramListing>
<Para><!--Original XRef content: 'Table&numsp;4&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.4"> describes the <Command>tttrace</Command> options.</Para>
<Table Id="TTUG.tttrc.tbl.3" Frame="Topbot">
<Title Id="TTUG.tttrc.mkr.4">tttrace Options</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="0.84259 in">
<ColSpec Colname="2" Colwidth="4.14583 in">
<THead>
<Row>
<Entry><Para><Literal>Option</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>-0</Command></Para></Entry>
<Entry><Para>Turns off message tracing in session, or runs the specified command
without message tracing (that is, with only call tracing).</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>-F</Filename></Para></Entry>
<Entry><Para>Follows all children forked by the indicated command, or
subsequently started in session by ttsession. Normally, only the
indicated command or a ttsession instance is traced. When the <Filename>-F</Filename>
option is specified, the process ID is included with each line of trace
output to indicate which process generated it.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>-C</Filename></Para></Entry>
<Entry><Para>Do not trace client calls into the ToolTalk API. The default is to trace
the calls.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>-a</Command></Para></Entry>
<Entry><Para>Prints all attributes, arguments, and context slots of traced messages.
The default is to use only a single line when printing a message on the
trace output.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>-o</Filename> <Symbol Role="Variable">outfile</Symbol></Para></Entry>
<Entry><Para>The file to be used for the trace output. For session tracing, output
goes to standard output of tttrace.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>-S</Filename> <Symbol Role="Variable">session</Symbol></Para></Entry>
<Entry><Para>The session to trace. Defaults to the default session; that is, the session
that<IndexTerm>
<Primary>tt_open</Primary>
</IndexTerm>
<Filename>tt_open</Filename> would contact.</Para></Entry>
</Row>
<Row>
<Entry><Para><Symbol Role="Variable">command</Symbol></Para></Entry>
<Entry><Para>The ToolTalk client command to invoke and trace.</Para></Entry>
</Row>
<Row>
<Entry><Para>-e <Symbol Role="Variable">script</Symbol></Para></Entry>
<Entry><Para>The script to be used as a <Command>ttrace</Command> setting.</Para></Entry>
</Row>
<Row>
<Entry><Para>-f <Symbol Role="Variable">scriptfile</Symbol></Para></Entry>
<Entry><Para>The file from which to read the <Command>tttrace</Command> settings.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para><Command>tttrace</Command> is implemented purely as a ToolTalk client, using the message
interface to ttsession and the<IndexTerm>
<Primary>TT_TRACE_SCRIPT environment variable</Primary>
</IndexTerm>
<Filename>TT_TRACE_SCRIPT</Filename> environment variable. If this
variable is set, it tells <Command>libtt</Command> to turn on client-side tracing as specified in the
trace script. If the first character of the value is '.' or '/', the value is taken to be
the path name of file containing the trace script to use; otherwise, the value is
taken to be an inline trace script.</Para>
<Sect2 Id="TTUG.tttrc.div.8">
<Title>Formats of Traced Functions</Title>
<Para>The following is an example of how a traced ToolTalk function looks.</Para>
<ProgramListing>[<Symbol Role="Variable">pid</Symbol>] <Symbol Role="Variable">function_name</Symbol>(<Symbol Role="Variable">params</Symbol>) = <Symbol Role="Variable">return_value</Symbol> (<Symbol Role="Variable">Tt_status</Symbol>)</ProgramListing>
<Sect3 Id="TTUG.tttrc.div.9">
<Title>Message Summary Format</Title>
<Para>The <Filename>-a</Filename> option prints message attributes after a one-line summary of the
message, as follows:</Para>
<ProgramListing><Symbol Role="Variable">Tt_state Tt_paradigm Tt_class</Symbol> (<Symbol Role="Variable">Tt_disposition in Tt_scope</Symbol>): <Symbol Role="Variable">status</Symbol> == <Symbol Role="Variable">Tt_status</Symbol></ProgramListing>
</Sect3>
<Sect3 Id="TTUG.tttrc.div.10">
<Title>State Change Format</Title>
<Para>State changes are indicated by the following format:</Para>
<ProgramListing><Symbol Role="Variable">old_state</Symbol> => <Symbol Role="Variable">new_state</Symbol>.</ProgramListing>
</Sect3>
<Sect3 Id="TTUG.tttrc.div.11">
<Title>Message Delivery Format</Title>
<Para>Deliveries are indicated by the following indicated:</Para>
<ProgramListing>Tt_message => procid <Symbol Role="Variable">recipient_procid</Symbol></ProgramListing>
<Para><!--Original XRef content: 'Table&numsp;4&hyphen;4'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.5"> dexplains the messages you may receive during a dispatch trace.</Para>
<Table Id="TTUG.tttrc.tbl.4" Frame="Topbot">
<Title Id="TTUG.tttrc.mkr.5">Reasons for Dispatch Trace</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="1.86148 in">
<ColSpec Colname="2" Colwidth="3.16667 in">
<THead>
<Row>
<Entry><Para><Literal>Message</Literal></Para></Entry>
<Entry><Para><Literal>Explanation</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Filename>tt_message_send</Filename></Para></Entry>
<Entry><Para>The message to send.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_reject</Filename></Para></Entry>
<Entry><Para>The message was rejected.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_fail</Filename></Para></Entry>
<Entry><Para>The message failed.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_reply</Filename></Para></Entry>
<Entry><Para>The reply to a message.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_session_join</Filename></Para></Entry>
<Entry><Para>The session to join.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_file_join</Filename></Para></Entry>
<Entry><Para>The file to join.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_reply</Filename></Para></Entry>
<Entry><Para>A client called the indicated function.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_send_on_exit</Filename></Para></Entry>
<Entry><Para>ttsession is dispatching on_exit messages for a client
that disconnected before calling <Filename>tt_close</Filename>.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>tt_message_accept</Filename></Para></Entry>
<Entry><Para>ttsession is dispatching messages that had been
blocked while a ptype was being started. The started
client has now called either <Filename>tt_message_accept</Filename> or
<Filename>tt_message_reply</Filename> to indicate that the ptype
should be unblocked.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>TT_ERR_PTYPE_START</Filename></Para></Entry>
<Entry><Para>A ptype instance was started to receive the message,
but the start command exited before it connected to
ttsession.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>TT_ERR_PROCID</Filename></Para></Entry>
<Entry><Para>ttsession lost its connection to the client that was
working on this request.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ttsession -> ttsession</Command></Para></Entry>
<Entry><Para>Another session wants this session to find recipients
for the message.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ttsession &lt;- ttsession</Command></Para></Entry>
<Entry><Para>Another session wants to update (for example, fail) a
message originating in this session.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
</Sect3>
<Sect3 Id="TTUG.tttrc.div.12">
<Title>Matching Format</Title>
<Para>When dispatching is being traced, matching is indicated by one of the
following</Para>
<ProgramListing>Tt_message &amp; Tt_pattern {
Tt_message &amp; ptype <Symbol Role="Variable">ptid</Symbol> {
Tt_message &amp; otype <Symbol Role="Variable">otid</Symbol> {</ProgramListing>
<Para>formats:</Para>
<Para>The pattern or signature is printed, followed by:</Para>
<ProgramListing>} == <Symbol Role="Variable">match_score</Symbol>; [/* <Symbol Role="Variable">mismatch_reason</Symbol> */]</ProgramListing>
</Sect3>
</Sect2>
<Sect2 Id="TTUG.tttrc.div.13">
<Title>Examples</Title>
<Para>This sections contains examples of how to use the tttrace function.</Para>
<Sect3 Id="TTUG.tttrc.div.14">
<Title>Registering a Pattern and Sending a Matching Notice</Title>
<Para>To register a pattern and send a notice that matches the pattern, type:</Para>
<ProgramListing>&percnt; tttrace -a <Symbol Role="Variable">myclientprogram</Symbol></ProgramListing>
<Para><!--Original XRef content: 'Code&numsp;Example&numsp;4&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.6"> shows the results.</Para>
<Example Id="TTUG.tttrc.tbl.5">
<Title Id="TTUG.tttrc.mkr.6">Registering a Pattern and Sending a Notice</Title>
<ProgramListing>tt_open() = 0x51708==&ldquo;7.jOHHM X 129.144.153.55 0&ldquo; (TT_OK)
tt_fd() = 11 (TT_OK)
tt_pattern_create() = 0x50318 (TT_OK)
tt_pattern_category_set(0x50318, TT_OBSERVE) = 0 (TT_OK)
tt_pattern_scope_add(0x50318, TT_SESSION) = 0 (TT_OK)
tt_pattern_op_add(0x50318, 0x2f308==&ldquo;Hello World&ldquo;) = 0 (TT_OK)
tt_default_session() = 0x519e0==&ldquo;X 129.144.153.55 0&ldquo; (TT_OK)
tt_pattern_session_add(0x50318, 0x519e0==&ldquo;X 129.144.153.55 0&ldquo;) = 0 (TT_OK)
tt_pattern_register(0x50318) = 0 (TT_OK)
tt_message_create() = 0x51af0 (TT_OK)
tt_message_class_set(0x51af0, TT_NOTICE) = 0 (TT_OK)
tt_message_address_set(0x51af0, TT_PROCEDURE) = 0 (TT_OK)
tt_message_scope_set(0x51af0, TT_SESSION) = 0 (TT_OK)
tt_message_op_set(0x51af0, 0x2f308==&ldquo;Hello World&ldquo;) = 0 (TT_OK)
tt_message_send(0x51af0) ...
TT_CREATED => TT_SENT:
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
= 0 (TT_OK)
tt_message_receive() ...
Tt_message => procid &lt;7.jOHHM X 129.144.153.55 0>
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
pattern: 0:7.jOHHM X 129.144.153.55 0
= 0x51af0 (TT_OK)
</ProgramListing></Example>
<Para>To see ttsession's view of the message flow, type:</Para>
<ProgramListing>&percnt; tttrace -a</ProgramListing>
<Para>ttsession's view</Para>
<Example Id="TTUG.tttrc.tbl.6">
<Title Id="TTUG.tttrc.mkr.7">ttsession's View of Trace</Title>
<ProgramListing>tt_message_reply:
TT_SENT => TT_HANDLED:
TT_HANDLED TT_PROCEDURE TT_REQUEST (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 2.jOHHM X 129.144.153.55 0
op: Session_Trace
args: TT_IN string: &ldquo;> /tmp/traceAAAa002oL; version 1; states&ldquo;[...]
session: X 129.144.153.55 0
sender: 2.jOHHM X 129.144.153.55 0
pattern: 0:X 129.144.153.55 0
handler: 0.jOHHM X 129.144.153.55 0
Tt_message => procid &lt;2.jOHHM X 129.144.153.55 0>
tt_message_send:
TT_CREATED TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
TT_CREATED => TT_SENT:
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
Tt_message &amp; Tt_pattern {
id: 0:7.jOHHM X 129.144.153.55 0
category: TT_OBSERVE
scopes: TT_SESSION
sessions: X 129.144.153.55 0
ops: Hello World
} == 3;
Tt_message => procid &lt;7.jOHHM X 129.144.153.55 0></ProgramListing>
</Example>
<Para>of <Emphasis>mylientprogram</Emphasis>'s message flow is shown in
<!--Original XRef content: 'Code&numsp;Example&numsp;4&hyphen;2'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.7">.</Para>
<Note>
<Para>The first message traced will almost always be ttsession's reply to the
request sent to it by <Command>tttrace</Command>.</Para>
</Note>
</Sect3>
<Sect3 Id="TTUG.tttrc.div.15">
<Title>Tracing a Message Flow</Title>
<Para>To trace the message flow in a specific, non-default session, type:</Para>
<ProgramListing>&percnt; tttrace -S &ldquo;01 15303 1342177284 1 0 13691 129.144.153.55 2&ldquo;</ProgramListing>
<Para>where <Emphasis>&ldquo;01 15303 1342177284 1 0 13691 129.144.153.55 2&ldquo;</Emphasis> is the specific, non-default
session to be traced.</Para>
</Sect3>
</Sect2>
</Sect1>
<Sect1 Id="TTUG.tttrc.div.16">
<Title>Settings for ToolTalk Tracing</Title>
<Para>A <Command>tttrace</Command> script contains settings that control ToolTalk calls and messages. A
<Command>tttrace</Command> script consists of commands separated by semicolons or newlines. If
conflicting values are given for a setting, the last value is the one used.
<!--Original XRef content: 'Table&numsp;4&hyphen;5'--><XRef Role="CodeOrFigureOrTable" Linkend="TTUG.tttrc.mkr.8"> describes these commands.</Para>
<Table Id="TTUG.tttrc.tbl.7" Frame="Topbot">
<Title Id="TTUG.tttrc.mkr.8">tttrace Script Commands</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="1.88658 in">
<ColSpec Colname="2" Colwidth="4.53704 in">
<THead>
<Row>
<Entry><Para><Literal>Command</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>version</Command> n</Para></Entry>
<Entry><Para>The version of the <Filename>tttracefile</Filename> command syntax used. The current
version is 1.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>follow [off | on]</Command></Para></Entry>
<Entry><Para>Sets whether to follow all children forked by the traced client or
subsequently started in the traced session. Default is <Command>off</Command>.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>[> | >>]</Command> <Emphasis>outfile</Emphasis></Para></Entry>
<Entry><Para>File to be used for the trace output. By default, trace output goes to standard
error. Normal shell interpretation of <Emphasis>></Emphasis> and <Emphasis>>></Emphasis> applies.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>functions</Command> [all | none |
<Emphasis>func...</Emphasis>]</Para></Entry>
<Entry><Para>ToolTalk API functions to trace. <Emphasis>func</Emphasis> may include shell wildcard characters.
Default is <Command>all</Command>.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>attributes [all | none]</Command></Para></Entry>
<Entry><Para><Command>none</Command> (default) means use only a single line when printing a message on the
trace output; <Command>all</Command> means print all attributes, arguments, and context slots of
traced messages.</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>states [none | edge |
deliver | dispatch |</Filename>
<StructName Role="typedef">Tt_state</StructName><Filename>]...</Filename></Para></Entry>
<Entry><Para>State(s) through which to trace messages. In addition to the Tt_states defined
in <Filename>tt_c.h</Filename>, valid <Symbol Role="Variable">state</Symbol>s are:</Para><Para>&bull; <Command>none</Command> &ndash; disable all message tracing</Para><Para>&bull; <Command>edge</Command> &ndash; messages entering initial (<Filename>TT_SENT</Filename>) and final (<Filename>TT_HANDLED</Filename>,
<Filename>TT_FAILED</Filename>) states.</Para><Para>&bull; <Command>deliver</Command> &ndash; all state changes and all client deliveries.</Para><Para>&bull; <Command>dispatch</Command> &ndash; deliver plus all patterns considered for matching (default).</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ops</Command> <Emphasis>toTrace</Emphasis>...</Para><Para><Filename>sender_ptypes</Filename> <Emphasis>toTrace</Emphasis>...</Para><Para><Filename>handler_ptypes</Filename> <Emphasis>toTrace</Emphasis>...</Para></Entry>
<Entry><Para>Trace messages that have <Emphasis>toTrace</Emphasis> as a value for the indicated message
attribute. <Emphasis>toTrace</Emphasis> may include shell wildcard characters. If no <Emphasis>toTrace</Emphasis>
argument is included for a given message attribute, then no value of that
attribute excludes a message from tracing.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

31
cde/doc/C/guides/ttGuide/credits.sgm Normal file
View File

@@ -0,0 +1,31 @@
<!-- $XConsortium: credits.sgm /main/3 1996/08/18 19:44:22 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<!--Para: Copyright &xd3; 1994, 1995 Hewlett-Packard Company
Copyright &xd3; 1994, 1995 International Business Machines Corp.
Copyright &xd3; 1994, 1995 Sun Microsystems, Inc.
Copyright &xd3; 1994, 1995 Novell, Inc.-->
<!--Para: All rights reserved. This product and related documentation are protected by copyright and distributed under licenses
restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be
reproduced in any form by any means without prior written authorization.-->
<!--Para: RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions
set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.-->
<!--Para: THIS PUBLICATION IS PROVIDED &xd2;AS IS&xd3; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, OR NON-INFRINGEMENT.-->
<!--Para: The code and documentation for the DtComboBox and DtSpinBox widgets were contributed by Interleaf, Inc. Copyright 1993,
Interleaf, Inc.-->
<!--Para: ToolTalk is a registered trademark of Sun Microsystems, Inc.-->
<!--Para: UNIX is a trademark exclusively licensed through X/Open Company, Ltd.-->
<!--Para: Motif and Motif are trademarks of Open Software Foundation, Ltd.-->
<!--Para: X Window System is a trademark of X Consortium, Inc.-->
<!--Para: PostScript is a trademark of Adobe Systems, Inc., which may be registered in certain jurisdictions.-->
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->

BIN
cde/doc/C/guides/ttGuide/graphics/ttserv.cgm Normal file
View File

Binary file not shown.

216
cde/doc/C/guides/ttGuide/preface.sgm Normal file
View File

@@ -0,0 +1,216 @@
<!-- $XConsortium: preface.sgm /main/7 1996/09/08 19:35:59 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Preface Id="TTUG.Pref.div.1">
<Title>Preface</Title>
<Para>This book describes the Common Desktop Environment (CDE) components,
commands, and error messages of the ToolTalk<Superscript>&reg;</Superscript> service.</Para>
<Note>
<Para>In-depth information about the functionality of the ToolTalk service in
general is beyond the scope of this book. That is, <Emphasis>CDE ToolTalk Messaging Overview</Emphasis> does <Emphasis Role="Lead-in">not</Emphasis> describe all ToolTalk APIs or commands, or other ToolTalk
functionality not specifically related to this release of the ToolTalk service for
the Common Desktop Environment. See the<IndexTerm>
<Primary>ToolTalk Reference Manual</Primary>
</IndexTerm>
<Emphasis>ToolTalk Reference Manual</Emphasis> and the<IndexTerm>
<Primary>ToolTalk User'</Primary>
</IndexTerm><IndexTerm>
<Primary>s Guide</Primary>
</IndexTerm>
<Emphasis>ToolTalk User's Guide</Emphasis> for this information.</Para>
</Note>
<Sect1 Id="TTUG.Pref.div.2">
<Title>Who Should Use This Book</Title>
<Para>This manual is for developers who create or maintain applications that use the
ToolTalk service to inter&hyphen;operate with other applications in Common Desktop Environment
. This manual assumes familiarity with <![ %Solaris; [the ToolTalk service and
its functionality, UNIX<Superscript>&trade;</Superscript> ]]>operating system commands, system administrator
commands, and system terminology.</Para>
</Sect1>
<Sect1 Id="TTUG.Pref.div.3">
<Title>How This Book Is Organized</Title>
<Para>This book is organized as follows:</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Chapter&numsp;1, &xd2;Introducing the ToolTalk Service'--><XRef Role="ChapNumAndTitle" Linkend="TTUG.tttrc.mkr.1">, describes how the ToolTalk
service works and how it uses information that your application supplies to
deliver messages; how applications use the ToolTalk service; and application
and ToolTalk components.</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Chapter&numsp;2, &xd2;How to Use ToolTalk Messaging'--><XRef Role="ChapNumAndTitle" Linkend="TTUG.HTU.mkr.1">, contains the information you
need to write an application using the ToolTalk service in the Common Desktop Environment
, including the kinds of ToolTalk toolkit messages that
need to be included in your application in order for it to inter-operate with
other ToolTalk-aware Common Desktop Environment-compliant applications.</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Chapter&numsp;3, &xd2;Using TTSnoop to Debug Messages and Patterns'--><XRef Role="ChapNumAndTitle" Linkend="TTUG.tttrc.mkr.1">, describes how
to create and send custom&hyphen;constructed ToolTalk messages, and also how to
selectively monitor any or all ToolTalk messages.</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Chapter&numsp;4, &xd2;Using ToolTalk Tracing'--><XRef Role="ChapNumAndTitle" Linkend="TTUG.tttrc.mkr.1">, describes how a ToolTalk pattern
matches and delivers every message ttsession sees.</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Appendix&numsp;A, &xd2;The Messaging Toolkit'--><XRef Role="AppendixNumAndTitle" Linkend="TTUG.MsgTk.mkr.1">, describes some of the application
program interface (API functions) that are a part of the messaging toolkit.</Para>
<Para><Literal><!--Literal closed to allow XRef:--></Literal>
<!--Original XRef content: 'Appendix&numsp;B, &xd2;The broadcast Demonstration Program'--><XRef Role="AppendixNumAndTitle" Linkend="TTUG.BrCast.mkr.1">, contains the source code
for the ToolTalk demo program, <literal>broadcast</literal>.</Para>
<para>Appendix C discusses writing thread-safe ToolTalk applications.
</para>
</Sect1>
<Sect1 Id="TTUG.Pref.div.4">
<Title>Related Books and Other Documentation</Title>
<Para><Emphasis>CDE ToolTalk Messaging Overview</Emphasis> does <Emphasis>not</Emphasis> provide in&hyphen;depth information about<IndexTerm>
<Primary>ToolTalk functionality, in-depth information about</Primary>
</IndexTerm>
ToolTalk and its functionality. In addition to the ToolTalk product base
documentation (that is, <Emphasis>ToolTalk User's Guide</Emphasis> and the <Emphasis>ToolTalk Reference Manual</Emphasis>),
the following related ToolTalk documentation provide in-depth information
about the ToolTalk functionality that is beyond the<IndexTerm>
<Primary>scope, of this book</Primary>
</IndexTerm>
scope of this book:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Emphasis><IndexTerm>
<Primary>The ToolTalk Service - An Inter-Operability Solution, ISBN 013-088717-X</Primary>
</IndexTerm>The ToolTalk Service - An Inter-Operability Solution</Emphasis> <Emphasis>(Published by SunSoft Press/PTR Prentice Hall, ISBN 013-088717-X)</Emphasis></Para>
<Para><Emphasis>This book describes ToolTalk and its functionality in depth, and is
appropriate for all platforms to which ToolTalk has been ported. It is
available at your local bookstore or directly from PTR Prentice Hall.</Emphasis></Para>
</ListItem>
<ListItem>
<Para><Emphasis><IndexTerm>
<Primary>ToolTalk and Open Protocols, ISBN 013-031055-7</Primary>
</IndexTerm>ToolTalk and Open Protocols</Emphasis> <Emphasis>by Astrid M. Julienne and Brian Holtz
(Published by SunSoft Press/PTR Prentice Hall, ISBN 013-031055-7)</Emphasis></Para>
<Para>This book describes how to create and develop open protocols for
applications that use a messaging service to communicate with other
applications. The general principles described in this book provide an
application with the flexibility required for users to easily inter&hyphen;change
tools. It is available at your local bookstore or directly from PTR Prentice
Hall.</Para>
</ListItem>
<ListItem>
<Para><Emphasis>ToolTalk Message Sets</Emphasis></Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para>ToolTalk<IndexTerm>
<Primary>Desktop Services Message Set</Primary>
</IndexTerm>
Desktop Services Message Set</Para>
<Para>These conventions apply to any tools in a POSIX or X11 environment. In
addition to standard messages for these environments, the Desktop
conventions define data types and error codes that apply to all of the
ToolTalk inter&hyphen;client conventions.</Para>
</ListItem>
<ListItem>
<Para>ToolTalk<IndexTerm>
<Primary>Document and Media Exchange Message Set</Primary>
</IndexTerm>
Document and Media Exchange Message Set</Para>
<Para>Allows a tool to be a container for arbitrary media, or to be a media
player/editor that can be driven from such a container.</Para>
</ListItem>
<ListItem>
<Para><Emphasis><IndexTerm>
<Primary>CASE Inter-Operability Message Set</Primary>
</IndexTerm>CASE Inter-Operability Message Set</Emphasis></Para>
<Para>An <Emphasis>open</Emphasis> specification defining abstract, framework-neutral message
interfaces for CASE set-up by Sunsoft, DEC, and SGI. This work has been
merged with HP's CASE Communique work, which defined message
interfaces for HP's SoftBench Broadcast Message Server framework, and
was submitted as a joint draft to ANSI X3H6. As of this writing, ANSI
X3H6 is still reviewing the joint submission draft. More information on
the draft<IndexTerm>
<Primary>X3H6 standard</Primary>
</IndexTerm>
X3H6 standard can be retrieved from <Emphasis><IndexTerm>
<Primary>ftp.netcomcom</Primary>
</IndexTerm>ftp.netcom.com</Emphasis>, in<IndexTerm>
<Primary>/pub/X3H</Primary>
</IndexTerm>
/pub/X3H6; or you can contact:</Para>
</ListItem>
</ItemizedList>
</ListItem>
</ItemizedList>
<Para>X3 Secretariat<IndexTerm>
<Primary>Computer and Business Equipment Manufactures Assoc</Primary>
</IndexTerm>
Computer and Business Equipment Manufactures Assoc
1250 Eye St NW
Washington DC&numsp;&numsp;20005-3922
Telephone: (202) 737-8888 (press `1' twice)
Fax: (202) 638-4922 or (202) 628-2829</Para>
</Sect1>
<Sect1 Id="TTUG.Pref.div.5">
<Title>ToolTalk News Group</Title>
<Para>The ToolTalk<IndexTerm>
<Primary>news group</Primary>
</IndexTerm>
news group is:</Para>
<Para><IndexTerm>
<Primary>alt.soft-sys.tooltalk</Primary>
</IndexTerm><Emphasis>alt.soft-sys.tooltalk</Emphasis></Para>
</Sect1>
<sect1 id="TTUG.Pref.div.6">
<title>What DocBook SGML Markup Means</title>
<para>This book is written in the Structured Generalized Markup
Language (SGML) using the DocBook Document Type Definition (DTD).
The following table describes the DocBook markup used for
various semantic elements.
</para>
<table id="TTUG.Pref.tbl.1" frame="Topbot">
<title>DocBook SGML Markup</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.65in">
<colspec colwidth="2.63in">
<colspec colwidth="2.92in">
<thead>
<row>
<entry align="left" valign="bottom"><para><literal>Markup Appearance</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Semantic Element(s)</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Example</literal></para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>AaBbCc123</command></para></entry>
<entry align="left" valign="top"><para>The names of commands.</para></entry>
<entry align="left" valign="top"><para>Use the <command>ls</command> command to list files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><literal>AaBbCc123</literal></para></entry>
<entry align="left" valign="top"><para>The names of command options.</para></entry>
<entry align="left" valign="top"><para>Use <command>ls</command> <literal>&minus;a</literal>
to list all files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">AaBbCc123</symbol></para></entry>
<entry align="left" valign="top"><para>Command-line placeholder:
replace with a real name or value.</para></entry>
<entry align="left" valign="top"><para>To delete a file, type <command>rm</command> <symbol role="Variable">filename</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>AaBbCc123</filename></para></entry>
<entry align="left" valign="top"><para>The names of files and
directories.</para></entry>
<entry align="left" valign="top"><para>Edit your <filename>.login</filename>
file.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Book titles, new words or terms, or
words to be emphasized.</para></entry>
<entry align="left" valign="top"><para>Read Chapter 6 in <emphasis>User's
Guide</emphasis>.
These are called <emphasis>class</emphasis> options.
You <emphasis>must</emphasis> be root to do this.</para></entry>
</row></tbody></tgroup></table>
</sect1>
</Preface>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 05:02:32-->