*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> DtActionInvoke (3)              


 DtActionInvoke(library call)                   DtActionInvoke(library call)

 NAME    [Toc]    [Back]
      DtActionInvoke - invoke a CDE action

 SYNOPSIS    [Toc]    [Back]
      #include <Dt/Action.h>
      DtActionInvocationID DtActionInvoke(
      Widget w,
      char *action,
      DtActionArg *args,
      int argCount,
      char *termOpts,
      char *execHost,
      char *contextDir,
      int useIndicator,
      DtActionCallbackProc statusUpdateCb,
      XtPointer client_data);

 DESCRIPTION    [Toc]    [Back]
      The DtActionInvoke 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.

      The actions and data types databases must be initialized and loaded
      (using DtInitialize(3) and DtDbLoad(3)) before DtActionInvoke can run

      The w 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-NULL

      The action 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
      dtactionfile(4)). This argument must have a non-NULL value.

      The args 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 args must be NULL. The items in this
      array are assigned to the option argument keywords referenced in the
      action definition (see dtactionfile(4)). The nth item is assigned to
      keyword %Arg_ n%. For example, the second item is assigned to %Arg_2%.

      The argCount argument is the number of action arguments provided in
      the array args references.

      The termOpts argument is a string providing special execution
      information for the terminal emulator used for COMMAND actions of
      WINDOW_TYPE TERMINAL or PERM_TERMINAL. (See dtactionfile(4)). This

                                    - 1 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

      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

      The execHost argument is a string identifying a preferred execution
      host for this action. The execHost specified here, supersedes the list
      of execution hosts defined in the action definition. If execHost is
      NULL, the execution host for the action is obtained from the action
      definition as described in dtactionfile(4).

      The contextDir 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, /usr/tmp or /net/hostb/tmp).  This value is only used if the
      action definition does not explicitly specify a working directory in
      the CWD field of the action definition. If contextDir is NULL, the
      current working directory of the action is obtained from the action
      definition, as described in  dtactionfile(4).

      If the useIndicator flag is zero, DtActionInvoke does not provide any
      direct indication to the user that an action has been invoked. If the
      useIndicator 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).

      The statusUpdateCb callback may be activated if the invoked actions
      have returnable status (for example, a TT_MSG(TT_REQUEST) returning
      DtACTION_DONE ). At a minimum, a DtACTION_INVOKED status is returned
      when DtActionInvoked has finished processing and has completely
      invoked any resulting actions, and a DtACTION_DONE or equivalent done
      status is returned when all actions terminate. If statusUpdateCb is
      set to NULL, subsequent action status is not returned. (See
      Dt/Action.h - DtAction(5) for a list of all DtActionStatus codes, and
      see DtActionCallbackProc(3) for details on statusUpdateCb and a list
      of specific DtActionStatus codes it can return.)

      The client_data argument is optional data to be passed to the
      statusUpdateCb callback when invoked.

      The DtActionInvoke function searches the action database for an entry
      that matches the specified action name, and accepts arguments of the
      class, type and count provided.

      If DtActionInvoke 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

                                    - 2 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

      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 DtActionArg structure that may have been
      modified by the action are returned by the callback if a
      statusUpdateCb callback is provided. For DtActionBuffer arguments, the
      writable flag acts as a hint that the buffer is allowed to be modified
      and returned.

      The DtActionBuffer structure contains at least the following members:
      void      *bp        location of buffer
      int       size       size of buffer in bytes
      char      *type      optional type of buffer
      char      *name      optional name of buffer
      Boolean   writable   action is allowed to
                           modify and return the

      The DtActionFile structure contains at least the following member:
      char   *name   name of file

      The DtActionArg structure contains at least the following members:
      int              argClass   see argument class types (
                                  ARG_CLASS field)
      DtActionFile     u.file     union to a DtActionFile structure
      DtActionBuffer   u.buffer   union to a DtActionBuffer structure

      where argClass is DtACTION_FILE or DtACTION_BUFFER. The action service
      may set argClass to DtACTION_NULLARG for action arguments returned by
      a statusUpdateCb to indicate that the argument is not being updated or
      has been removed. DtACTION_NULLARG cannot be present in action
      arguments passed to DtActionInvoke.

      The DtActionInvoke function accepts a pointer to an array of
      DtActionArg structures describing the objects to be provided as
      arguments to the action. The args structure can be modified or freed
      after DtActionInvoke returns.

      A single call to DtActionInvoke 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 DtActionInvocationID may
      represent a group of running actions, and subsequent execution
      management services (DtAction) calls operate on that group of actions.

      For DtACTION_BUFFER arguments, the action service first tries to type
      the buffer *bp using the name field (see  dtdtsfile(4)). The name
      field would typically contain a value resembling a file name with an
      optional extension describing its type. If the name field is NULL,

                                    - 3 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

      then the action service uses the type specified in the type field. If
      the type field is NULL, then the action service types the buffer *bp
      by content (see dtdtsfile(4)). If the name and type fields are both
      non-NULL, then the action service uses the name field for typing and
      ignores the type field. If the buffer pointer bp is NULL or size is
      equal to zero, a buffer with no contents is used in the resulting
      action. If returned, the buffer pointer bp is defined, and size is
      equal to or greater than zero.

      When necessary, DtACTION_BUFFER 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-NULL name field is given, it is used in the
      construction of the temporary file name (for example,
      /myhome/.dt/tmp/name). If the use of name would cause a conflict with
      an existing file, or name is NULL, the action service generates a
      temporary file name. The permission bits on the temporary file are set
      according to the writable field and the IS_EXECUTABLE attribute from
      the action service associated with the type field.

      For DtACTION_FILE arguments, name is required.

      For DtACTION_BUFFER arguments, name cannot contain slash characters.

      Errors encountered are either displayed to the user in a dialog box or
      reported in the desktop errorlog file ($HOME/.dt/errorlog, unless
      configured otherwise).

 RESOURCES    [Toc]    [Back]
      This section describes the X11 resources the DtActionInvoke 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 *resourceName:
      value. For example, to set the terminal emulator to xterm(1) for all
      clients, the application can use *localTerminal: xterm.  The resources
      can also be defined on a per client basis. For example, it can use
      Dtfile*localTerminal: xterm to set the terminal emulator to xterm(1)
      for the dtfile client only.  (See dtactionfile(4)).
                              X11 Resources
      Name                  Class               Value Type   Default
      localterminal         LocalTerminal       string       ``Dtterm''
      remoteTerminals       RemoteTerminals     string       ``Dtterm''
      waitTime              WaitTime            number       3

      LocalTerminal    [Toc]    [Back]
                Defines an alternative local terminal emulator for Command
                actions of WINDOW_TYPE TERMINAL or PERM_TERMINAL to use. The
                default terminal emulator is dtterm(1).

                                    - 4 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

      RemoteTerminals    [Toc]    [Back]
                Defines a comma-separated list of host and terminal emulator
                pairs.  When a remote COMMAND 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 -e argument. (Thus, if
                another terminal emulator than dtterm is used, it must
                support the -e argument. See xterm(1).

      WaitTime  Used to assign an alternative integer value, in seconds, to
                the threshold successful return time interval. If a COMMAND
                action of WINDOW_TYPE TERMINAL 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 TERMINAL window
                command exits before WaitTime seconds have elapsed, the
                terminal emulator window is forced to remain open, as if it
                were of TYPE PERM_TERMINAL. The default value of WaitTime is
                3 seconds.

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, the DtActionInvoke function returns a
      DtActionInvocationID.  The ID can be used in subsequent execution
      management services (DtAction) calls to manipulate the actions while
      they are running. DtActionInvocationIDs are only recycled after many
      have been generated.

 APPLICATION USAGE    [Toc]    [Back]
      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 DtActionInvoke returns.

      Since DtActionInvoke spawns subprocesses to start local actions, the
      caller should use waitpid(2) instead of wait(2) to distinguish between
      processes started by the action service and those the caller starts.

 EXAMPLES    [Toc]    [Back]
      Given the following action definition:

      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

                                    - 5 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

                              defaults are used for both quantities.

      The following call invokes the action Edit on the arguments aap

              DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
                             myCallback, myClientData);

      The working directory for the action defaults to the current working
      directory.  The execution host is the default execution host.

      If the variable aap points to an array of ActionArg data structures
      containing the following information:

              argClass = DtACTION_FILE;
              struct {
              } file;

              argClass = DtACTION_FILE;
              struct {
              } file;

              argClass = DtACTION_BUFFER;
              struct {
                  bp=(void *) myEditBuffer;
              } buffer;

      and the current working directory is /cwd, then the Edit action
      results in the execution string:

      textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt

      When the action completes, myCallback is called and the callback
      returns the buffer argument.

 SEE ALSO    [Toc]    [Back]
      Dt/Action.h - DtAction(5),  xterm(1), XtFree(3), XtMalloc(3),
      DtDbLoad(3), DtInitialize(3), DtActionCallbackProc(3),

                                    - 6 -       Formatted:  January 24, 2005

 DtActionInvoke(library call)                   DtActionInvoke(library call)

      dtactionfile(4), dtdtfile(4), dtdtsfile(4).

                                    - 7 -       Formatted:  January 24, 2005
[ Back ]
 Similar pages
Name OS Title
tack Linux terminfo action checker
DtAction HP-UX action service definitions
dtactionaction HP-UX CDE action management actions
DtActionIcon HP-UX get the icon information for an action
sigaction Tru64 Specify the action to take upon delivery of a signal
DtActionExists HP-UX determine if a string corresponds to an action name
DtActionDescription HP-UX obtain the descriptive text for a given action
DtActionLabel HP-UX get the localizable label string for an action
sigaction HP-UX examine and change signal action
DtDtsDataTypeIsAction HP-UX determine if the data type is an action
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service