<!-- $XConsortium: fail.sgm /main/5 1996/08/30 13:38:05 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. -->

<![ %CDE.C.CDE; [<RefEntry Id="CDEMX.XCDI.MAN119.rsml.1">]]>
<![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN119.rsml.1">]]>
<RefMeta>
<RefEntryTitle>tt_message_fail</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>tt_message_fail</Function></RefName>
<RefPurpose>indicate a message cannot be handled
</RefPurpose>
</RefNameDiv>
<!-- $XConsortium: fail.sgm /main/5 1996/08/30 13:38:05 rws $-->
<!-- CDE Common Source Format, Version 1.0.0-->
<!-- (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.-->
<RefSynopsisDiv>
<FuncSynopsis Remap="ANSI">
<FuncSynopsisInfo>#include &lt;Tt/tt_c.h>
</FuncSynopsisInfo>
<FuncDef>Tt_status <Function>tt_message_fail</Function></FuncDef>
<ParamDef>Tt_message <Parameter>m</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>The
<Function>tt_message_fail</Function> function
informs the ToolTalk service that the process cannot handle the request just
received.
</Para>
<Para>This function also informs the ToolTalk service that the message is not be
offered to other processes of the same ptype.
The ToolTalk service will send the
message back to the sender with state
<SystemItem Class="Constant">TT_FAILED</SystemItem>.</Para>
<Para>The
<Emphasis>m</Emphasis> argument is the opaque handle for the message involved in this operation.
</Para>
</RefSect1>
<RefSect1>
<Title>RETURN VALUE</Title>
<Para>Upon successful completion, the
<Function>tt_message_fail</Function> function returns the status of the operation as one of the following
<StructName Role="typedef">Tt_status</StructName> values:
</Para>
<VariableList>
<VarListEntry>
<Term>TT_OK</Term>
<ListItem>
<Para>The operation completed successfully.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>TT_ERR_NOMP</Term>
<ListItem>
<Para>The
&cdeman.ttsession; process is not running and the ToolTalk service cannot restart it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>TT_ERR_NOTHANDLER</Term>
<ListItem>
<Para>This application is not the handler for this message.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>TT_ERR_POINTER</Term>
<ListItem>
<Para>The pointer passed does not point to an object of
the correct type for this operation.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<Para>The status value must be greater than
<SystemItem Class="Constant">TT_ERR_LAST</SystemItem> to avoid confusion with the ToolTalk service status values.
</Para>
</RefSect1>
<RefSect1>
<Title>APPLICATION USAGE</Title>
<Para>To distinguish this case from the case where a message failed because no
matching handler could be found,
the application should place an explanatory message code in the
status attribute of the message with
&cdeman.tt.message.status.set; and
&cdeman.tt.message.status.string.set; before calling
<Function>tt_message_fail</Function>.</Para>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.Tt.tt.c.h;, &cdeman.tt.message.status.set;, &cdeman.tt.message.status.string.set;.</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
