<!-- $XConsortium: ActionIn.sgm /main/10 1996/09/08 20:02:14 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.MAN12.rsml.1">]]><![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN12.rsml.1">]]><refmeta>
<refentrytitle>DtActionInvoke</refentrytitle><manvolnum>library call</manvolnum>
</refmeta><refnamediv><refname><function>DtActionInvoke</function></refname>
<refpurpose>invoke a &str-XZ; action</refpurpose></refnamediv><!-- 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;Dt/Action.h></funcsynopsisinfo>
<funcdef>DtActionInvocationID <function>DtActionInvoke</function></funcdef>
<paramdef>Widget <parameter>w</parameter></paramdef>
<paramdef>char *<parameter>action</parameter></paramdef>
<paramdef>DtActionArg *<parameter>args</parameter></paramdef>
<paramdef>int <parameter>argCount</parameter></paramdef>
<paramdef>char *<parameter>termOpts</parameter></paramdef>
<paramdef>char *<parameter>execHost</parameter></paramdef>
<paramdef>char *<parameter>contextDir</parameter></paramdef>
<paramdef>int <parameter>useIndicator</parameter></paramdef>
<paramdef>DtActionCallbackProc <parameter>statusUpdateCb</parameter></paramdef>
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcsynopsis></refsynopsisdiv><refsect1>
<title>DESCRIPTION</title>
<para>The <function>DtActionInvoke</function> function provides a way for
applications to invoke desktop actions on file or buffer arguments. Applications
can register a callback for receiving action-done status and return arguments.
</para>
<para>The actions and data types databases must be initialized and loaded
(using &cdeman.DtInitialize; and &cdeman.DtDbLoad;)
before <function>DtActionInvoke</function> can run successfully.</para>
<para>The <symbol role="Variable">w</symbol> argument is a widget that becomes
the parent of any dialogs or error messages resulting from action invocation.
This widget should be a top-level application shell widget that continues
to exist for the action's expected lifetime. This argument must have a non-<systemitem class="Constant">NULL</systemitem> value.</para>
<para>The <symbol role="Variable">action</symbol> argument is the name of
the action to be invoked. The action database may define more than one action
with the same name. The action selected for a particular invocation depends
on the class, type, and number of arguments provided (as described in <![ %CDE.C.CDE; [ &cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>This
argument must have a non-<systemitem class="Constant">NULL</systemitem> value.
</para>
<para>The <symbol role="Variable">args</symbol> argument is an array of action
argument structures containing information about the arguments for this action
invocation. If there are no arguments, the value of <symbol role="Variable">args</symbol> must be <systemitem class="Constant">NULL</systemitem>. The
items in this array are assigned to the option argument keywords referenced
in the action definition (see <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>The
<symbol role="Variable">n</symbol>th item is assigned to keyword %Arg_ <symbol role="Variable">n</symbol>%. For example, the second item is assigned to %Arg_<emphasis>2</emphasis>%.</para>
<para>The <emphasis>argCount</emphasis> argument is the number of action arguments
provided in the array <symbol role="Variable">args</symbol> references.</para>
<para>The <emphasis>termOpts</emphasis> argument is a string providing special
execution information for the terminal emulator used for <systemitem class="Constant">COMMAND</systemitem> actions of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> or <systemitem class="Constant">PERM_TERMINAL</systemitem>. (See <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>This
string must be quoted if it contains embedded blanks. The application uses
this string to pass on title, geometry, color and font information to the
terminal emulator. This information must be in a form the expected terminal
emulator recognizes. This argument can be <systemitem class="Constant">NULL</systemitem>.</para>
<para>The <emphasis>execHost</emphasis> argument is a string identifying a
preferred execution host for this action. The <emphasis>execHost</emphasis>
specified here, supersedes the list of execution hosts defined in the action
definition. If <emphasis>execHost</emphasis> is <systemitem class="Constant">NULL</systemitem>, the execution host for the action is obtained from the
action definition as described in <![ %CDE.C.CDE; [&cdeman.dtactionfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">. ]]></para>
<para>The <emphasis>contextDir</emphasis> argument is a string identifying
a fallback working directory for the action. File name arguments are interpreted
relative to this directory, which must reside in the local file name space
(for example, <Filename>/usr/tmp</Filename> or <Filename>/net/hostb/tmp</Filename>).
This value is only used if the action definition does not explicitly specify
a working directory in the <systemitem class="Constant">CWD</systemitem> field
of the action definition. If <emphasis>contextDir</emphasis> is <systemitem class="Constant">NULL</systemitem>, the current working directory of the action
is obtained from the action definition, as described in <![ %CDE.C.CDE; [ &cdeman.dtactionfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">. ]]></para>
<para>If the <emphasis>useIndicator</emphasis> flag is zero, <function>DtActionInvoke</function> does not provide any direct indication to the user that an action
has been invoked. If the <emphasis>useIndicator</emphasis> flag is non-zero,
the user is notified via some activity indicator (for example, a flashing
light in the front panel) that an action has been invoked. This indication
persists only until the invocation of the action completes (in other words,
until the action begins running).</para>
<para>The <emphasis>statusUpdateCb</emphasis> callback may be activated if
the invoked actions have returnable status (for example, a <systemitem class="Constant">TT_MSG(TT_REQUEST)</systemitem> returning <systemitem class="Constant">DtACTION_DONE</systemitem> ). At a minimum, a <systemitem class="Constant">DtACTION_INVOKED</systemitem> status is returned when <function>DtActionInvoked</function>
has finished processing and has completely invoked any resulting actions,
and a <systemitem class="Constant">DtACTION_DONE</systemitem> or equivalent
done status is returned when all actions terminate. If <emphasis>statusUpdateCb</emphasis> is set to <systemitem class="Constant">NULL</systemitem>, subsequent
action status is not returned. (See &cdeman.Dt.Action.h;
for a list of all <structname role="typedef">DtActionStatus</structname> codes,
and see &cdeman.DtActionCallbackProc; for details on <emphasis>statusUpdateCb</emphasis> and a list of specific <structname role="typedef">DtActionStatus</structname> codes it can return.)</para>
<para>The <symbol role="Variable">client_data</symbol> argument is optional
data to be passed to the <emphasis>statusUpdateCb</emphasis> callback when
invoked.</para>
<para>The <function>DtActionInvoke</function> function searches the action
database for an entry that matches the specified action name, and accepts
arguments of the class, type and count provided.</para>
<para>If <function>DtActionInvoke</function> finds a matching action, the
supplied arguments are inserted into the indicated action fields. If any missing
action arguments have an associated prompt string, then a dialog box prompts
the user to supply the arguments; otherwise, missing arguments are ignored.
If too many arguments are supplied to an action requiring more than a single
argument, a warning dialog is posted, allowing the action to be cancelled
or continued, ignoring the extra arguments. If too many arguments are supplied
to an action requiring zero or one arguments, then that action is invoked
once for each of the supplied arguments. Arguments in the <structname role="typedef">DtActionArg</structname> structure that may have been modified by the action
are returned by the callback if a <emphasis>statusUpdateCb</emphasis> callback
is provided. For <structname role="typedef">DtActionBuffer</structname> arguments,
the writable flag acts as a hint that the buffer is allowed to be modified
and returned.</para>
<para>The <structname role="typedef">DtActionBuffer</structname> structure
contains at least the following members:</para>
<informaltable remap="center" orient="Port">
<tgroup cols="3">
<colspec align="Left" colname="1">
<colspec align="Left" colname="2">
<colspec align="Left" colname="3">
<tbody>
<row>
<entry><computeroutput>void</computeroutput></entry>
<entry><computeroutput>*bp</computeroutput></entry>
<entry>location of buffer</entry></row>
<row>
<entry><computeroutput>int</computeroutput></entry>
<entry><computeroutput>size</computeroutput></entry>
<entry>size of buffer in bytes</entry></row>
<row>
<entry><computeroutput>char</computeroutput></entry>
<entry><computeroutput>*type</computeroutput></entry>
<entry>optional type of buffer</entry></row>
<row>
<entry><computeroutput>char</computeroutput></entry>
<entry><computeroutput>*name</computeroutput></entry>
<entry>optional name of buffer</entry></row>
<row>
<entry><computeroutput>Boolean</computeroutput></entry>
<entry><computeroutput>writable</computeroutput></entry>
<entry>action is allowed to modify and return the buffer</entry></row></tbody>
</tgroup></informaltable>
<para>The <structname role="typedef">DtActionFile</structname> structure contains
at least the following member:</para>
<informaltable remap="center" orient="Port">
<tgroup cols="3">
<colspec align="Left" colname="1">
<colspec align="Left" colname="2">
<colspec align="Left" colname="3">
<tbody>
<row>
<entry><computeroutput>char</computeroutput></entry>
<entry><computeroutput>*name</computeroutput></entry>
<entry>name of file</entry></row></tbody></tgroup></informaltable>
<para>The <structname role="typedef">DtActionArg</structname> structure contains
at least the following members:</para>
<informaltable remap="center" orient="Port">
<tgroup cols="3">
<colspec align="Left" colname="1">
<colspec align="Left" colname="2">
<colspec align="Left" colname="3">
<tbody>
<row>
<entry><computeroutput>int</computeroutput></entry>
<entry><computeroutput>argClass</computeroutput></entry>
<entry>see argument class types ( <systemitem class="Constant">ARG_CLASS</systemitem>
field)</entry></row>
<row>
<entry><computeroutput>DtActionFile</computeroutput></entry>
<entry><computeroutput>u.file</computeroutput></entry>
<entry>union to a DtActionFile structure</entry></row>
<row>
<entry><computeroutput>DtActionBuffer</computeroutput></entry>
<entry><computeroutput>u.buffer</computeroutput></entry>
<entry>union to a DtActionBuffer structure</entry></row></tbody></tgroup>
</informaltable>
<para>where <emphasis>argClass</emphasis> is <systemitem class="Constant">DtACTION_FILE</systemitem> or <systemitem class="Constant">DtACTION_BUFFER</systemitem>. The action service may set <emphasis>argClass</emphasis> to <systemitem class="Constant">DtACTION_NULLARG</systemitem> for action arguments returned
by a <emphasis>statusUpdateCb</emphasis> to indicate that the argument is
not being updated or has been removed. <systemitem class="Constant">DtACTION_NULLARG</systemitem> cannot be present in action arguments passed to <function>DtActionInvoke</function>.</para>
<para>The <function>DtActionInvoke</function> function accepts a pointer to
an array of <structname role="typedef">DtActionArg</structname> structures
describing the objects to be provided as arguments to the action. The
<symbol role="Variable">args</symbol> structure can be modified or freed after <function>DtActionInvoke</function> returns.</para>
<para>A single call to <function>DtActionInvoke</function> may initiate several
actions or messages. For example, if an action is given three files, but only
needs one, three instances of the action are started, one for each file. As
a result, a single returned <structname role="typedef">DtActionInvocationID</structname> may represent a group of running actions, and subsequent execution
management services <![ %CDE.C.CDE; [(DtAction) ]]>calls operate on that group
of actions.</para>
<para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
the action service first tries to type the buffer <emphasis>*bp</emphasis>
using the <symbol role="Variable">name</symbol> field (see <![ %CDE.C.CDE; [ &cdeman.dtdtsfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.DATAT.anch.3" Role="2">). ]]>The
<symbol role="Variable">name</symbol> field would typically contain a value resembling
a file name with an optional extension describing its type. If the
<symbol role="Variable">name</symbol> field is <systemitem class="Constant">NULL</systemitem>,
then the action service uses the type specified in the <symbol role="Variable">type</symbol> field. If the <symbol role="Variable">type</symbol> field is <systemitem class="Constant">NULL</systemitem>, then the action service types the buffer <emphasis>*bp</emphasis> by content (see <![ %CDE.C.CDE; [&cdeman.dtdtsfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.DATAT.anch.3" Role="2">). ]]>If
the <symbol role="Variable">name</symbol> and <symbol role="Variable">type</symbol>
fields are both non-<systemitem class="Constant">NULL</systemitem>,
then the action service uses the <symbol role="Variable">name</symbol> field
for typing and ignores the <symbol role="Variable">type</symbol> field. If
the buffer pointer <emphasis>bp</emphasis> is <systemitem class="Constant">NULL</systemitem> or <symbol role="Variable">size</symbol> is equal to zero,
a buffer with no contents is used in the resulting action. If returned, the
buffer pointer <emphasis>bp</emphasis> is defined, and <symbol role="Variable">size</symbol> is equal to or greater than zero.</para>
<para>When necessary, <systemitem class="Constant">DtACTION_BUFFER</systemitem>
arguments are automatically converted to temporary files prior to actual action
invocation, and reconverted back to buffers after action termination (this
is transparent to the caller). If a non-<systemitem class="Constant">NULL</systemitem> <symbol role="Variable">name</symbol> field is given, it is
used in the construction of the temporary file name (for example, <Filename>/myhome/.dt/tmp/name</Filename>). If the use of <symbol role="Variable">name</symbol>
would cause a conflict with an existing file, or <symbol role="Variable">name</symbol> is <systemitem class="Constant">NULL</systemitem>, the action
service generates a temporary file name. The permission bits on the temporary
file are set according to the <emphasis>writable</emphasis> field and the <systemitem class="Constant">IS_EXECUTABLE</systemitem> attribute from the action service
associated with the <symbol role="Variable">type</symbol> field.</para>
<para>For <systemitem class="Constant">DtACTION_FILE</systemitem> arguments,
<symbol role="Variable">name</symbol> is required.</para>
<para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
<symbol role="Variable">name</symbol> cannot contain slash characters.</para>
<para>Errors encountered are either displayed to the user in a dialog box
or reported in the desktop errorlog file (<Filename>$HOME/.dt/errorlog</Filename>,
unless configured otherwise).</para>
</refsect1><refsect1><?Pub Caret1>
<title>RESOURCES</title>
<para>This section describes the X11 resources the <function>DtActionInvoke</function> function recognizes. The resource class string always begins with
an upper-case letter. The corresponding resource name string begins with the
lower case of the same letter. These resources can be defined for all clients
using the Action Library API by specifying <literal>*resourceName: value</literal>. <![ %CDE.C.CDE; [For
example, to set the terminal emulator to <command>xterm</command>(1) for all
clients, the application can use <literal>*localTerminal: xterm</literal>.
The resources can also be defined on a per client basis. For example, it can
use <literal>Dtfile*localTerminal: xterm</literal> to set the terminal emulator
to <command>xterm</command>(1) for the <command>dtfile</command> client only.
(See <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>]]></para>
<informaltable remap="center" orient="port">
<tgroup cols="4" colsep="0" rowsep="0">
<colspec align="left" colwidth="155*">
<colspec align="left" colwidth="147*">
<colspec align="left" colwidth="74*">
<colspec align="left" colwidth="81*">
<tbody>
<row>
<entry></entry>
<entry align="center" valign="top"><literal>X11 Resources</literal></entry>
</row>
<row>
<entry align="left" valign="top"><literal>Name</literal></entry>
<entry align="left" valign="top"><literal>Class</literal></entry>
<entry align="left" valign="top"><literal>Value Type</literal></entry>
<entry align="left" valign="top"><literal>Default</literal></entry></row>
<row>
<entry align="left" valign="top"><literal>localterminal</literal></entry>
<entry align="left" valign="top"><literal>LocalTerminal</literal></entry>
<entry align="left" valign="top"><literal>string</literal></entry>
<entry align="left" valign="top">``Dtterm''</entry></row>
<row>
<entry align="left" valign="top"><literal>remoteTerminals</literal></entry>
<entry align="left" valign="top"><literal>RemoteTerminals</literal></entry>
<entry align="left" valign="top"><literal>string</literal></entry>
<entry align="left" valign="top">``Dtterm''</entry></row>
<row>
<entry align="left" valign="top"><literal>waitTime</literal></entry>
<entry align="left" valign="top"><literal>WaitTime</literal></entry>
<entry align="left" valign="top"><literal>number</literal></entry>
<entry align="left" valign="top">3</entry></row></tbody></tgroup></informaltable>
<variablelist>
<varlistentry><term><literal>LocalTerminal</literal></term>
<listitem>
<para>Defines an alternative local terminal emulator for Command actions of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> or <systemitem class="Constant">PERM_TERMINAL</systemitem> to
use. The default terminal emulator is &cdeman.dtterm;.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>RemoteTerminals</literal></term>
<listitem>
<para>Defines a comma-separated list of host and terminal emulator pairs.
When a remote <systemitem class="Constant">COMMAND</systemitem> action is
executed on one of the hosts in the list, the terminal emulator associated
with that host is used for that command. The list is passed to the terminal
emulator using the <literal>-e</literal> argument. (Thus, if another
terminal emulator than <command>dtterm</command> is used, it must support
the <literal>-e</literal> argument. <![ %CDE.C.CDE; [See <command>xterm</command>(1). ]]></para>
</listitem>
</varlistentry>
<varlistentry><term><literal>WaitTime</literal></term>
<listitem>
<para>Used to assign an alternative integer value, in seconds, to the threshold
successful return time interval. If a <systemitem class="Constant">COMMAND</systemitem> action of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> fails, the terminal emulator may be
unmapped before the user has a chance to read the standard error from the
failed command. This resource provides a workaround to this problem. If a <systemitem class="Constant">TERMINAL</systemitem> window command exits before <literal>WaitTime</literal> seconds have elapsed, the terminal emulator window is forced
to remain open, as if it were of <systemitem class="Constant">TYPE</systemitem> <systemitem class="Constant">PERM_TERMINAL</systemitem>. The default value of <literal>WaitTime</literal> is 3 seconds.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1>
<title>RETURN VALUE</title>
<para>Upon successful completion, the <function>DtActionInvoke</function>
function returns a <structname role="typedef">DtActionInvocationID</structname>.
The ID can be used in subsequent execution management services <![ %CDE.C.CDE; [(DtAction) ]]>calls
to manipulate the actions while they are running. <structname role="typedef">DtActionInvocationID</structname>s are only recycled after many have been
generated.</para>
</refsect1><refsect1>
<title>APPLICATION USAGE</title>
<para>The caller should allocate space for the array of structures describing
the objects to be provided as arguments to the action. The caller can free
the memory after <function>DtActionInvoke</function> returns.</para>
<para>Since <function>DtActionInvoke</function> spawns subprocesses to start
local actions, the caller should use <function>waitpid</function>(2) instead
of <function>wait</function>(2) to distinguish between processes started by
the action service and those the caller starts.</para>
</refsect1><refsect1>
<title>EXAMPLES</title>
<para>Given the following action definition:</para>
<informalexample remap="indent">
<programlisting>ACTION Edit
{
        LABEL           "Text Edit Action"
        ARG_CLASS       BUFFER, FILE
        ARG_TYPE        TEXT
        TYPE            COMMAND
        WINDOW_TYPE     TERMINAL
        EXEC_STRING     "textedit %Args%"
        DESCRIPTION     This action invokes the "textedit" command on
                        an arbitrary number of arguments.  A terminal
                        emulator is provided for this action's I/O.
                        EXEC_HOST and CWD are not specified so the
                        defaults are used for both quantities.
}</programlisting>
</informalexample>
<para>The following call invokes the action
<symbol role="Message">Edit</symbol> on the arguments
<emphasis>aap</emphasis> supplies:</para>
<informalexample remap="indent">
<programlisting>        DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
                       myCallback, myClientData);</programlisting>
</informalexample>
<para>The working directory for the action defaults to the current working
directory.
The execution host is the default execution host.</para>
<para>If the variable
<emphasis>aap</emphasis> points to an array of
<literal>ActionArg</literal> data structures
containing the following information:</para>
<informalexample remap="indent">
<programlisting>{
        argClass = DtACTION_FILE;
        struct {
            name="/myhome/file1.txt";
        } file;
}</programlisting>
</informalexample>
<informalexample remap="indent">
<programlisting>{
        argClass = DtACTION_FILE;
        struct {
            name="file2.txt";
        } file;
}</programlisting>
</informalexample>
<informalexample remap="indent">
<programlisting>{
        argClass = DtACTION_BUFFER;
        struct {
            bp=(void *) myEditBuffer;
            size=lengthOfMyEditBuffer;
            type=NULL;
            name="Doc1.txt"
            writable=TRUE;
        } buffer;
}</programlisting>
</informalexample>
<para>and the current working directory is
<Filename>/cwd</Filename>, then the
<symbol role="Message">Edit</symbol> action results in the execution string:
</para>
<informalexample remap="indent">
<programlisting>textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt
</programlisting>
</informalexample>
<para>When the action completes,
<emphasis>myCallback</emphasis> is called and
the callback returns the buffer argument.</para>
</refsect1><refsect1>
<title>SEE ALSO</title>
<para>&cdeman.Dt.Action.h;, <![ %CDE.C.CDE; [ <command>xterm</command>(1), <function>XtFree</function>(3), <function>XtMalloc</function>(3), ]]><![ %CDE.C.XO; [<Function>XtFree</Function>(3), <Function>XtMalloc</Function>(3) in the &str-Zt;;
]]>&cdeman.DtDbLoad;, &cdeman.DtInitialize;, &cdeman.DtActionCallbackProc;, <![ %CDE.C.CDE; [&cdeman.dtactionfile;, &cdeman.dtdtfile;, &cdeman.dtdtsfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">, <XRef Linkend="XCDI.M4DTS.anch.1" Role="3">, <XRef Linkend="XCDI.DATAT.anch.3" Role="2">. ]]></para>
</refsect1></refentry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
<?Pub *0000053895>
