 |
Index for
Section 4 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dtactionfile(4)
CDE
NAME
dtactionfile - define the content of desktop action definition records
SYNOPSIS
set DtDbVersion=version_number
set VariableName=variable_value
ACTION action_name
{
# Comment
FieldName field_value
FieldName field_value
.
.
.
}
DESCRIPTION
CDE actions define the behavior of icons, front panel controls and
operations on data objects. Actions are defined in a set of text files with
the .dt suffix. Each action definition consists of the word ACTION followed
by an action name and a list of Field and Value pairs (one per line) on
lines by themselves and enclosed in brackets.
3 Action File Syntax
The general syntax of the actions files is as follows:
set DtDbVersion=version_number
set VariableName=variable_value
ACTION action_name
{
# Comment
FieldName field_value
FieldName field_value
.
.
.
}
These text files may also contain data typing information as described in
dtdtsfile(4). (See dtdtfile(4) for the general syntax and location of the
actions and data types database.)
Actions are of one of the following classes: command actions, ToolTalk
message actions or map actions. These action classes are described in the
following sections.
Command Actions
Command actions are identified by a TYPE COMMAND field. This field defines
an execution string to invoke and a set of related information, such as the
current working directory for the command and the host where the command
should be executed. The following field names are unique to command
actions: EXEC_STRING, EXEC_HOST, CWD, WINDOW_TYPE and TERM_OPTS.
ToolTalk Message Actions
ToolTalk message actions are identified by a TYPE TT_MSG field. This field
defines a ToolTalk message to be sent. The following fields are unique to
ToolTalk message actions: TT_CLASS, TT_SCOPE, TT_OPERATION, TT_FILE,
TT_ARGn_MODE, TT_ARGn_VTYPE, TT_ARGn_REP_TYPE and TT_ARGn_VALUE.
Map Actions
Map actions are identified by a TYPE MAP field. This field does not define
any specific behavior; instead, this field specifies a different action
name that should be invoked in place of the original action. Multiple map
actions can be chained together, but the chain must ultimately terminate in
a non-map action. The following field is unique to map actions: MAP_ACTION.
Common Fields
In addition to the unique action fields listed above, all actions support
the following fields: LABEL, ICON, DESCRIPTION, ARG_CLASS, ARG_MODE,
ARG_TYPE, ARG_COUNT and TYPE.
Keywords
The value string for certain action fields may reference special keywords
enclosed within percentage character (%) delimiters. These keywords are
evaluated when the action is invoked and replaced with the appropriate
value. In fields that do not evaluate keywords, the keyword is taken
literally. The valid keywords are:
%DatabaseHost%
The name of the host where the action definition file is located. This
hostname is specified by the host portion of the host:/path searchpath
used to find the action.
%DisplayHost%
The name of the host where the X server displaying the CDE session is
running.
%LocalHost%
The name of the host where the application invoking the action is
executing.
%SessionHost%
The name of the host where the controlling login manager dtlogin(1))
runs.
Argument References
Arguments passed to actions can be referenced in certain action fields
using special argument keywords enclosed within percent character (%)
delimiters. These argument keywords are evaluated when the action is
invoked and replaced with the appropriate value. In fields that do not
evaluate keywords, the keyword is taken literally. The valid argument
keywords are:
%Arg_n%
The nth (starting with 1) argument of the action. If the action was
invoked with fewer than n arguments, the value of the keyword is NULL.
%Args%
All remaining arguments of the action. If any arguments of the action
have already been referenced within this field by an %Arg_n% keyword,
those arguments are not referenced a second time by %Args%.
%"prompt"%
Prompt the user for a value, using prompt as the label of a text field.
%Arg_n"prompt"%
The nth (starting with 1) argument of the action. If the action was
invoked with fewer than n arguments, prompt the user for a value using
prompt as the label of a text field.
If a keyword references the name of a file argument, the value of the
keyword is expanded to an absolute pathname prior to substitution. In
addition, if the file name is to be passed to a remote system, the file
name is first mapped appropriately (see tt_file_netfile(3) and
tt_netfile_file(3)).
If the keyword references a buffer argument, the buffer data is placed in a
temporary file and the name of the temporary file is substituted, as
described above. Some action fields provide direct support for data buffers
and do not require use of a temporary file. This behavior is noted in the
description of the appropriate fields.
If the keyword references a string obtained from the user, it is treated as
a simple string and the value substituted without any transformation.
Argument references can be forced to be treated as file names or simple
strings by using the (File) or (String) qualifier immediately after the
opening % of the keyword. For example:
%(String)Arg_n%
%(File)"prompt"%
If an action is invoked with more than one argument, and the action
definition only references one or zero arguments, the action is iteratively
invoked with each of the supplied arguments. If the action definition
references more than one argument, any extra arguments are ignored.
Action Selection
Multiple actions can be defined with the same name. When the action is
invoked, the appropriate action definition is chosen based on the number
and class of arguments supplied. For example, the Open action may invoke
dtpad(1) if a text file is supplied as an argument, or it may invoke
dticon(1) if a bitmap file argument is supplied. The ARG_COUNT, ARG_CLASS,
ARG_MODE and ARG_TYPE fields specify the number, mode and types of
arguments that are accepted by a particular action. Because these fields
can have shell pattern-matching values such as *, it is possible that the
action database contains multiple actions that have the same name and are
all capable of accepting the arguments that are supplied. In this case, the
following precedence rules are used to choose a single action definition to
invoke:
· Actions with more specific attribute values take precedence over more
general attribute values.
· For the ARG_COUNT field, an exact numerical value (N) is more specific
than a less-than range (<N). A less-than range (<N) is more specific
than a greater-than range (>N). And a greater-than range (>N) is more
specific than a shell pattern-matching character (*).
· For the ARG_CLASS and ARG_TYPE fields, a single item is more specific
than a list of items and a list of items is more specific than a shell
pattern-matching *.
· For the ARG_MODE field, w (writable) and !w (not writable) are more
specific than a shell pattern-matching *.
· The fields have the following precedence, from high to low: ARG_CLASS,
ARG_TYPE, ARG_MODE, ARG_COUNT.
· If two action definitions have equal specificity, the action
definition appearing first in the database load order takes
precedence. Database directories are loaded in the order specified by
the DTDATABASESEARCHPATH environment variable, and are loaded in the
collation order of their file names.
ARG_CLASS Field
The ARG_CLASS field is optional for all types of actions. This field
specifies the class of arguments the action accepts. If an action is
invoked with more than one argument, the class of only the first argument
is checked against the value of the ARG_CLASS field. The valid values for
this field are:
BUFFER
The action accepts arguments that are blocks of data held in memory.
FILE
The action accepts arguments that are file names.
* The action is defined for all classes of arguments.
A comma-separated list of valid values is also allowed and specifies that
the action accepts arguments of any of the listed classes.
If an action is defined to accept a buffer argument, yet the implementation
of the action requires a file name, the buffer is automatically converted
into a temporary file for the action to use. See the description of the
DtTmpDir resource for information on configuring the location of these
temporary files.
Keywords are not evaluated in the ARG_CLASS field. The default value of
the ARG_CLASS field is *.
ARG_COUNT Field
The ARG_COUNT field is optional for all types of actions. The ARG_COUNT
field specifies the number of arguments that the action accepts. The valid
values for this field (where N denotes any non-negative integer) are:
N The action accepts exactly N arguments.
<N The action accepts any number of arguments less than N.
>N The action accepts any number of arguments greater than N.
* The action accepts any number of arguments.
Keywords are not evaluated in the ARG_COUNT field. The default value of
the ARG_COUNT field is *.
ARG_MODE Field
The ARG_MODE field is optional for all types of actions. This field
specifies the mode of arguments the action accepts. If an action is invoked
with more than one argument, the mode of only the first argument is checked
against the value of the ARG_MODE field. The valid values for this field
are:
w The action accepts arguments that writable by the user.
!w The action accepts arguments that are not writable by the user.
* The action is defined for all classes of arguments.
Keywords are not evaluated in the ARG_MODE field. The default value of the
ARG_MODE field is *.
ARG_TYPE Field
The ARG_TYPE field is optional for all types of actions. This field
specifies the types of arguments the action accepts. If the action is
invoked with more than one argument, the type of only the first argument is
checked against the value of this field. Valid values for this field are *
(all data types are accepted), a single data type name or a comma-separated
list of data types. The set of valid data types are those defined by
DATA_ATTRIBUTE records in the data typing database. (See dtdtsfile(4) for
more information.)
Keywords are not evaluated in the ARG_TYPE field. The default value of the
ARG_TYPE field is *.
CWD Field
The CWD field is optional for all types of actions. This field specifies
the current working directory to be used when the execution string is
invoked. Valid values include any absolute pathname. If this field is not
specified, the current working directory for the execution string is
determined by the following:
· If the application invoking the action specifies a current working
directory, that directory is used.
· If arguments are supplied to the action and the first argument is a
directory, that directory is used.
· If arguments are supplied to the action and the first argument is a
file, the directory where the file is located is used.
· The current working directory of the application invoking the action
is used.
Keywords are not evaluated in the CWD field.
DESCRIPTION Field
The DESCRIPTION field is optional for COMMAND actions. This field specifies
a textual description of the action that is suitable for presentation to a
user requesting information about the action. The description should
contain no formatting information such as tab or newline characters. The
application that presents the information to the user formats the
information.
Keywords are not evaluated in the DESCRIPTION field. There is no default
value for the DESCRIPTION field.
EXEC_HOST Field
The EXEC_HOST field is optional for COMMAND actions. This field specifies
the host where the execution string should be invoked. Valid values for
this field include actual hostnames, as well as any of the hostname
keywords. If a comma-separated list of hostnames is provided, execution is
attempted on each of the hosts in the order specified until execution
succeeds.
Keywords are evaluated in the EXEC_HOST field. The default value of the
EXEC_HOST field is %DatabaseHost%,%LocalHost%. (See the description of the
ExecutionHosts resource for information on how to change this default
value.)
EXEC_STRING Field
The EXEC_STRING field is required for COMMAND actions. This field specifies
an execution string to be invoked. The string is parsed using the same
quoting rules as defined by sh(1); however, the execution string is not
automatically passed to any shell. Therefore, if the execution string
requires shell features such as redirection of standard input, redirection
of standard output, or pipes, the appropriate shell must be specified
explicitly in the execution string. For example:
EXEC_STRING sh -c 'ls -l | more'
Keywords are evaluated in the EXEC_STRING field. There is no default value
for the EXEC_STRING field.
ICON Field
The ICON field is optional for all types of actions. This field specifies
the name of an icon that represents the action.
Icons are found by using the standard CDE icon search path, so the value
can be either an absolute pathname (for example, /foo/icons/myicon.bm), a
relative pathname (for example, icons/myicon.bm) or a partial filename (for
example, myicon). Partial filenames are preferred because they allow the
CDE icon search path to find the icon with the optimum size and depth for
the current environment.
Keywords are not evaluated in the ICON field. The default value of the ICON
field is Dtactn. (See the description of the ActionIcon resource for
information on how to change this default value).
LABEL Field
The LABEL field is optional for all types of actions. This field specifies
a user-visible label for the action. When actions are presented to the
user, the localized LABEL field is used to identify the action instead of
the non-localized action name.
Keywords are not evaluated in the LABEL field. The default value of the
LABEL field is the name of the action.
MAP_ACTION Field
The MAP_ACTION field is required for MAP actions. This field specifies the
name of an action that should be invoked in place of the current action.
The specified action is invoked with the same set of arguments that were
passed to the original action.
Keywords are not evaluated in the MAP_ACTION field. There is no default
value for the MAP_ACTION field.
TERM_OPTS Field
The TERM_OPTS field is optional for COMMAND actions. This field specifies
command-line options that are passed to the terminal emulator for all
COMMAND actions that are terminal based. (That is, any COMMAND action other
than those that specify WINDOW_TYPE NO_STDIO.) These command-line options
are typically used to specify a unique terminal-window geometry, font,
color or title.
The value of the TERM_OPTS field must be an option string in a form the
terminal emulator supports and it must only affect the appearance of the
terminal window. For example, options such as -e, which affect the behavior
of the terminal window, must not be used.
Keywords are evaluated in the TERM_OPTS field. The default value of the
TERM_OPTS field is
-title action_label
where action_label is the LABEL field for the action. See dtterm(1) (or
xterm(1X)) for the meaning of -title.
TT_ARGn_MODE Field
The TT_ARGn_MODE field is optional for TT_MSG actions. This field specifies
the value of the ToolTalk mode attribute for the nth message argument,
where n is zero for the first message argument. The valid values for this
field are: TT_IN, TT_INOUT and TT_OUT.
(See Tt/tt_c.h for a description of these values).
Keywords are not evaluated in the TT_ARGn_MODE field. There is no default
value for the TT_ARGn_MODE field.
TT_ARGn_REP_TYPE Field
The TT_ARGn_REP_TYPE field is optional for TT_MSG actions. This field
specifies the representation type of the nth ToolTalk message argument,
where n is zero for the first message argument. The valid values for this
field are:
TT_REP_UNDEFINED
If TT_ARGn_VALUE references a buffer argument, the representation type
is a buffer; otherwise, it is a string.
TT_REP_INTEGER
The representation type is an integer.
TT_REP_BUFFER
The representation type is a buffer.
TT_REP_STRING
The representation type is string.
Keywords are not evaluated in the TT_ARGn_REP_TYPE field. The default value
of the TT_ARGn_REP_TYPE field is TT_REP_UNDEFINED.
TT_ARGn_VALUE Field
The TT_ARGn_VALUE field is optional for TT_MSG actions. If there is no
corresponding TT_ARGn_MODE field, the TT_ARGn_VALUE field is ignored. If
there is a TT_ARGn_MODE field, the TT_ARGn_VALUE field specifies the value
of the nth ToolTalk message argument, where n is zero for the first message
argument. If there is a TT_ARGn_MODE field with no corresponding
TT_ARGn_VALUE field, the value of the nth ToolTalk message argument is set
to NULL.
The value of the TT_ARGn_VALUE field must be a single string or action
argument. Keywords that reference a single action argument are evaluated in
the TT_ARGn_VALUE field, however %Args% is not allowed as it references
multiple action arguments. There is no default value for the TT_ARGn_VALUE
field.
TT_ARGn_VTYPE Field
The TT_ARGn_VTYPE field is required to accompany any TT_ARGn_MODE fields in
TT_MSG actions. This field specifies the value of the ToolTalk vtype
attribute of the nth message argument, where n is zero for the first
message argument. If this field references an argument keyword, the MEDIA
attribute of the specified argument is used. If the MEDIA attribute is not
defined, the DATA_ATTRIBUTE name of the data type is used.
Keywords are evaluated in the TT_ARGn_VTYPE field. There is no default
value for the TT_ARGn_VTYPE field.
TT_CLASS Field
The TT_CLASS field is required for TT_MSG actions. This field specifies the
value of the ToolTalk class message field. The valid values for this field
are:
TT_NOTICE
The action defines a ToolTalk notification message.
TT_REQUEST
The action defines a ToolTalk request message.
Keywords are not evaluated in the TT_CLASS field. There is no default
value for the TT_CLASS field.
TT_FILE Field
The TT_FILE field is optional for TT_MSG actions. This field specifies the
value of the ToolTalk file message field. The value of this field must be a
single file name and can either be a specific file name (for example,
/tmp/foo) or an argument keyword (for example, %Arg_1%). %Args% is not
allowed because it references multiple action arguments. If an argument
keyword is specified and the corresponding argument is not a file (that is,
it is a buffer), the action invocation fails.
Keywords are evaluated in the TT_FILE field. There is no default value for
the TT_FILE field; if it is not set, the file attribute of the ToolTalk
message is set to NULL.
TT_OPERATION Field
The TT_OPERATION field is required for TT_MSG actions. This field specifies
the value of the ToolTalk operation message field. Typical values are
operations such as Display or Edit that are defined by the Media Exchange
Message Set.
Keywords are not evaluated in the TT_OPERATION field. There is no default
value for the TT_OPERATION field.
TT_SCOPE Field
The TT_SCOPE field is required for TT_MSG actions. This field specifies the
value of the ToolTalk scope message field. (See Tt/tt_c.h for a description
of these values.) The valid values for this field are: TT_BOTH, TT_FILE,
TT_FILE_IN_SESSION and TT_SESSION.
Keywords are not evaluated in the TT_SCOPE field. There is no default
value for the TT_SCOPE field.
TYPE Field
The TYPE field is optional for COMMAND actions and required for MAP or
TT_MSG actions. This field specifies the type of behavior defined by the
action. Valid values for this field are:
COMMAND
The action invokes a command.
MAP The action specifies a different action name to invoke in place of the
current action.
TT_MSG
The action defines a ToolTalk message to be sent.
Keywords are not evaluated in the TYPE field. The default value of the TYPE
field is COMMAND.
WINDOW_TYPE Field
The WINDOW_TYPE field is optional for COMMAND actions. This field specifies
the type of windowing support the execution string requires. Valid values
for this field are:
NO_STDIO
No windowing support is required. This value is appropriate for
execution strings that have no output or are X Windows applications.
PERM_TERMINAL
The execution string requires a terminal window. When the execution
string exits, the terminal window is left open until the user
explicitly closes it. This value is appropriate for applications that
write their output to standard output and then terminate, such as
ls(1).
TERMINAL
The execution string requires a terminal window. When the execution
string exits, the terminal window is closed. If the execution string
exits ``quickly'' (see the description of the waitTime resource), the
terminal window is left open to allow the user to view any error
messages that were written to standard output or standard error. This
value is appropriate for full-screen terminal applications such as the
vi(1) editor.
Keywords are not evaluated in the WINDOW_TYPE field. The default value of
the WINDOW_TYPE field is PERM_TERMINAL.
RESOURCES
The following resources are available to control the behavior of actions.
These resources must be set for the application that is invoking the
action. They can be set for all applications that invoke actions by
omitting the application name or class name.
_____________________________________________________________________________
Name Class Type Default
_____________________________________________________________________________
actionIcon ActionIcon string ``Dtactn''
dtEnvMapForRemote DtEnvMapForRemote string
``DTAPPSEARCHPATH:
DTHELPSEARCHPATH:
DTDATABASESEARCHPATH:
XMICONSEARCHPATH:
XMICONBMSEARCHPATH''
dtexecPath DtexecPath string ``/usr/dt/bin/dtexec''
dtTmpDir DtTempDir string ``$HOME/.dt/tmp''
ExecutionHostLogging string ``False''
executionHostLogging
executionHosts ExecutionHosts string
``%DatabaseHost%,
%LocalHost%''
localTerminal LocalTerminal string ``dtterm''
remoteTerminals RemoteTerminals string None
waitTime WaitTime number 3
_____________________________________________________________________________
actionIcon
Specifies the default value of the ICON field for actions that do not
define the field. The default value of this resource is Dtactn.
dtEnvMapForRemote
Specifies a colon-separated list of environment variables names. Each
variable contains a colon-separated list of pathnames to be mapped for
remote actions (see tt_file_netfile(3) and tt_netfile_file(3)
Only environment variables in the user's current environment (see
environ(5) are mapped. Supplemental environment variables such as those
added by dtspcdenv(4), for example, are not mapped.
If a pathname contains substitution characters, only the portion of the
path up to the first percent character is mapped, with the remaining
portion appended to the resulting mapped portion. For example, if
NLSPATH is set to /system/nlslib/%L/%N.cat, it maps to
/net/host/system/nlslib/%L/%N.cat.
dtexecPath
Specifies the location of the dtexec(1) command that is used for
terminal-based actions. The default value is /usr/dt/bin/dtexec.
dtTmpDir
Specifies the full pathname of the directory to be used for holding
temporary files created during action invocation. The directory must be
visible to remote hosts used for action execution.
executionHostLogging
Turns on and off detailed logging to the user's $HOME/.dt/errorlog of
action invocation events. The default value is False, which disables
logging. Logging is enabled if this resource is set to True.
executionHosts
Specifies the default value of the EXEC_HOST field for COMMAND actions
that do not define the field. The default value is
%DatabaseHost%,%LocalHost%.
localTerminal
Specifies an alternative terminal emulator for terminal-based actions
that execute locally. Any terminal emulator specified by this resource
must support the -title and -e options as described in dtterm(1). The
default value is dtterm(1).
remoteTerminals
Specifies the terminal emulator to use for terminal-based actions that
execute on the named system. The value of this resource is a comma-
separated list of the form host:terminal-path where terminal-path is
the terminal emulator used when invoking terminal-based actions on host
host. The default terminal emulator used for any host not specified by
this resource is the emulator specified by the localTerminal resource.
waitTime
Specifies the time threshold used for COMMAND actions that specify
WINDOW_TYPE TERMINAL. If the command exits in less than waitTime
seconds, the terminal window is left open. The default value is 3.
APPLICATION USAGE
Errors encountered when loading database files are written to the user's
$HOME/.dt/errorlog. Errors encountered in the value of an action field
cause the field to be rejected. If the field is a required field, the
entire action definition is rejected. Errors encountered when an action is
invoked cause an error dialog to be displayed to the user.
EXAMPLES
1. The following action is defined to pipe its argument through the pr(1)
and lp(1) commands:
ACTION PrintText
{
ICON printer
DESCRIPTION Paginate and print a text file to the \
default printer.
ARG_TYPE Text
TYPE COMMAND
EXEC_STRING sh -c 'pr %Arg_1"File to print:"% | lp'
WINDOW_TYPE NO_STDIO
}
2. The following action defines that Open on Text files use the EditText
action:
ACTION Open
{
ARG_TYPE Text
TYPE MAP
MAP_ACTION EditText
}
3. The following action is defined to send the ToolTalk Display request
message for non-writable objects:
ACTION Display
{
ARG_CLASS BUFFER
ARG_MODE !w
TYPE TT_MSG
TT_CLASS TT_REQUEST
TT_SCOPE TT_SESSION
TT_OPERATION Display
TT_ARG0_MODE TT_IN
TT_ARG0_VTYPE %Arg_1%
TT_ARG0_VALUE %Arg_1%
}
SEE ALSO
Commands: dtterm(1)
Functions: DtActionInvoke(3), tt_file_netfile(3), tt_netfile_file(3)
Files: dtdtfile(4), dtdtsfile(4)
Others: Tttt_c(5)
|
Index for
Section 4 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|