DtActionInvoke man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

DtActionInvoke(library call)			  DtActionInvoke(library call)

       DtActionInvoke — invoke a CDE action

       #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);

       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 value.

       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  informa‐
       tion  for the terminal emulator used for COMMAND actions of WINDOW_TYPE
       TERMINAL or PERM_TERMINAL. (See dtactionfile(4)). 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 emu‐
       lator recognizes. This argument can be NULL.

       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 cur‐
       rent working directory of the action is obtained from the action	 defi‐
       nition, 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 invo‐
       cation of the action completes (in other words, until the action begins

       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 - DtAc‐
       tion(5) for a list of all DtActionStatus codes, and  see	 DtActionCall‐
       backProc(3)  for details on statusUpdateCb and a list of specific DtAc‐
       tionStatus codes it can return.)

       The client_data argument is optional data to be passed to the statusUp‐
       dateCb 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	 argu‐
       ments  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 argu‐
       ments are supplied to an action requiring zero or one  arguments,  then
       that  action  is invoked once for each of the supplied arguments. Argu‐
       ments 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 argu‐
       ments passed to DtActionInvoke.

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

       A  single  call	to DtActionInvoke may initiate several actions or mes‐
       sages. 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 (DtAc‐
       tion) 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, 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

       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 construc‐
       tion 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 per‐
       mission bits on the temporary file are set according  to	 the  writable
       field  and  the IS_EXECUTABLE attribute from the action service associ‐
       ated 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 con‐
       figured otherwise).

       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*localTer‐
       minal: 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

		 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).

		 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 pro‐
		 vides a workaround to this problem. If a TERMINAL window com‐
		 mand 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 sec‐

       Upon successful completion, the DtActionInvoke function returns a DtAc‐
       tionInvocationID.   The	ID can be used in subsequent execution manage‐
       ment services (DtAction) calls to manipulate the actions while they are
       running.	 DtActionInvocationIDs	are only recycled after many have been

       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.

       Given the following action definition:

       ACTION Edit
	       LABEL	       "Text Edit Action"
	       ARG_CLASS       BUFFER, FILE
	       ARG_TYPE	       TEXT
	       TYPE	       COMMAND
	       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.

       The following call invokes the action Edit on the  arguments  aap  sup‐

	       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.

       Dt/Action.h  -  DtAction(5),   xterm(1),	 XtFree(3),  XtMalloc(3), DtD‐
       bLoad(3),  DtInitialize(3),  DtActionCallbackProc(3),  dtactionfile(4),
       dtdtfile(4), dtdtsfile(4).

						  DtActionInvoke(library call)

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net