/usr/dt/share/man/cat4/dtactionfile.4
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
NAME
dtactionfile - define the content of desktop action defini-
tion records
SYNOPSIS
set DtDbVersion=version_number
set VariableName=variable_value
ACTION action_name
{
# Comment
FieldName field_value
FieldName field_value
.
.
.
}
DESCRIPTION
TED actions define the behavior of icons, front panel con-
trols 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.
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 direc-
tory for the command and the host where the command should
be executed. The following field names are unique to com-
mand 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
Unix System LaboratoLast change: 10 June 1994 1
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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, DESCRIP-
TION, 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 TED 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 argu-
ments, the value of the keyword is NULL.
%Args%
Unix System LaboratoLast change: 10 June 1994 2
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
All remaining arguments of the action. If any
arguments of the action have already been refer-
enced 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 argu-
ments, 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.
Unix System LaboratoLast change: 10 June 1994 3
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 particu-
lar 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 sup-
plied. In this case, the following precedence rules are
used to choose a single action definition to invoke:
o Actions with more specific attribute values take pre-
cedence over more general attribute values.
o 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
(*).
o 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
*.
o For the ARG_MODE field, w (writable) and !w (not writ-
able) are more specific than a shell pattern-matching
*.
o The fields have the following precedence, from high to
low: ARG_CLASS, ARG_TYPE, ARG_MODE, ARG_COUNT.
o 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 DTDATABASESEAR-
CHPATH 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 argu-
ment, 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.
Unix System LaboratoLast change: 10 June 1994 4
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
FILE The action accepts arguments that are file
names.
* The action is defined for all classes of argu-
ments.
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 argu-
ment, 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.
Unix System LaboratoLast change: 10 June 1994 5
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
* 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 argu-
ment, 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 informa-
tion.)
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 deter-
mined by the following:
o If the application invoking the action specifies a
current working directory, that directory is used.
o If arguments are supplied to the action and the first
argument is a directory, that directory is used.
o If arguments are supplied to the action and the first
argument is a file, the directory where the file is
located is used.
o 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 format-
ting information such as tab or newline characters. The
application that presents the information to the user for-
mats the information.
Unix System LaboratoLast change: 10 June 1994 6
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 execu-
tion 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 TED icon search path,
so the value can be either an absolute pathname (for exam-
ple, /foo/icons/myicon.bm), a relative pathname (for exam-
ple, icons/myicon.bm) or a partial filename (for example,
myicon). Partial filenames are preferred because they allow
the TED 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.)
Unix System LaboratoLast change: 10 June 1994 7
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 termi-
nal 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(1)) 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 mes-
sage 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.)
Unix System LaboratoLast change: 10 June 1994 8
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 argu-
ments. 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
Unix System LaboratoLast change: 10 June 1994 9
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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.
Unix System LaboratoLast change: 10 June 1994 10
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 out-
put or are X Windows applications.
PERM_TERMINAL
The execution string requires a terminal window.
When the execution string exits, the terminal win-
dow 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 win-
dow 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
Unix System LaboratoLast change: 10 June 1994 11
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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.
X11 Resources That Modify Action Behavior
___________________________________________________________________
Name | Class | Type | Default
_______________|_________________|________|________________________
actionIcon | ActionIcon | string| ``Dtactn''
dtEnvMap- | DtEnvMap- | string| ``DTAPPSEARCHPATH:
ForRemote | ForRemote | | DTHELPSEARCHPATH:
| | | DTDATABASESEARCHPATH:
| | | XMICONSEARCHPATH:
| | | XMICONBMSEARCHPATH''
dtexecPath | DtexecPath | string| ``/usr/dt/bin/dtexec''
dtTmpDir | DtTempDir | string| ``$HOME/.dt/tmp''
executionHost- | ExecutionHost- | string| ``False''
Logging | Logging | |
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. Supple-
mental 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 per-
cent character is mapped, with the remaining por-
tion 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
Unix System LaboratoLast change: 10 June 1994 12
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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 speci-
fied 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.
EXAMPLES
The following action is defined to pipe its argument through
the pr(1) and lp(1) commands:
ACTION PrintText
{
Unix System LaboratoLast change: 10 June 1994 13
dtactionfile(4) DEVICES AND NETWORK INTERFACES dtactionfile(4)
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
}
The following action defines that Open on Text files use the
EditText action:
ACTION Open
{
ARG_TYPE Text
TYPE MAP
MAP_ACTION EditText
}
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%
}
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.
SEE ALSO
Tttt_c,(5) dtdtfile(4), dtdtsfile(4), DtActionInvoke(3),
tt_file_netfile(3), tt_netfile_file(3), dtterm(1).
Unix System LaboratoLast change: 10 June 1994 14
See also dtactionfile(4)
Man(1) output converted with
man2html