<!-- $XConsortium: barg_add.sgm /main/8 1996/08/30 13:35:04 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.MAN102.rsml.1">]]>
<![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN102.rsml.1">]]>
<RefMeta>
<RefEntryTitle>tt_message_barg_add</RefEntryTitle><ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>tt_message_barg_add</Function></RefName>
<RefPurpose>add an argument to a pattern
</RefPurpose>
</RefNameDiv>
<RefSynopsisDiv>
<FuncSynopsis Remap="ANSI">
<FuncSynopsisInfo>#include &lt;Tt/tt_c.h>
</FuncSynopsisInfo>
<FuncDef>Tt_status <Function>tt_message_barg_add</Function></FuncDef>
<ParamDef>Tt_message <Parameter>m</Parameter></ParamDef>
<ParamDef>Tt_mode <Parameter>n</Parameter></ParamDef>
<ParamDef>const char *<Parameter>vtype</Parameter></ParamDef>
<ParamDef>const unsigned char *<Parameter>value</Parameter></ParamDef>
<ParamDef>int <Parameter>len</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>The
<Function>tt_message_barg_add</Function> function
adds an argument to a pattern that may have a byte-array value that
contains embedded nulls.
</Para>
<Para>To change existing argument values, the application must use only modes
<SystemItem Class="Constant">TT_OUT</SystemItem> or
<SystemItem Class="Constant">TT_INOUT</SystemItem>.</Para>
<Para>Adding arguments when replying to a message produces undefined results.
</Para>
<Para>The
<Emphasis>m</Emphasis> argument is the opaque handle for the message involved in this operation.
The
<Symbol Role="Variable">n</Symbol> argument specifies who (sender, handler, observers)
writes and reads a message argument.
The following modes are defined:
</Para>
<VariableList>
<VarListEntry>
<Term>TT_IN</Term>
<ListItem>
<Para>The argument is written by the sender and read by the
handler and any observers.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>TT_OUT</Term>
<ListItem>
<Para>The argument is written by the handler and read by the
sender and any reply observers.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>TT_INOUT</Term>
<ListItem>
<Para>The argument is written by the sender and the
handler and read by all.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<Para>The
<Emphasis>vtype</Emphasis> argument describes the type of argument data being added.
</Para>
<Para>The ToolTalk service treats the value as an opaque byte string.
To pass structured data, the application and the receiving application
must encode and decode these opaque byte strings.
The most common method to do this is XDR.
</Para>
<Para>The
<Symbol Role="Variable">value</Symbol> argument is the value to be added.
The
<Emphasis>len</Emphasis> argument is the length of the value in bytes.
</Para>
</RefSect1>
<RefSect1>
<Title>RETURN VALUE</Title>
<Para>Upon successful completion, the
<Function>tt_message_barg_add</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_POINTER</Term>
<ListItem>
<Para>The pointer passed does not point to an object of
the correct type for this operation.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.Tt.tt.c.h;, &cdeman.tt.message.arg.add;, &cdeman.tt.message.iarg.add;
</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
