TEMPLATE(5)
NAME
template - format of a ClearDDTS template file
SYNOPSIS
Fieldname: ( "format string" | command [arg ...] )
...
DESCRIPTION
A template file is a file used by ClearDDTS to define the
layout, constant text, value types, conditional handling,
and value translation for an interactive dialog or an output
report. For example, template files are used for the input
prompting and output screens by bugs(1) and xddts(1), and
only for output by dumpbug(1).
A template file contains zero or more field definitions.
Each field definition consists of a left-justified field
name, a colon (:), arbitrary whitespace, and one or more
derivation lines, each of which is followed by one or more
newline characters and arbitrary whitespace.
Each derivation line is either a printf(3S)-style format
string enclosed in double quotes ("):
"[text[%spec]text]"
or a data-filtering command with optional arguments:
command [arg ...]
For instance, one field definition might look like:
Customer-name: "Enter customer's name: %-30.30s"
required
help customer.H
oneof -f customers
Multiple field definitions for the same field can appear in
a single template file. The definitions are interpreted in
the order they appear, so the last definition executed for
any given field yields the final value for that field.
The interpretation of the format string lines depends on
whether the template file is being used for input or output
(see Format Strings below).
Input
This section describes the interpretation of a template file
when used for input.
For any field that does not already exist in the template,
its initial value is set to an empty string. The execution
of each derivation line transforms the current value of the
field and returns a status value. A derivation such as:
Foo: echo 1
echo 2
would first set the value of Foo to 1 and return a
successful (0) status and then set the Foo field to 2 and
return a successful (0) status.
The set of derivation lines for each field definition are
executed in order until the status returned by the final
derivation line is 0 (successful). If any derivation line
fails (i.e., the status returned is non-zero), execution
starts over at the first derivation. Thus, an error such as
an invalid value for a field would cause that entire field
derivation to be reexecuted. If a field derivation returns
255 (Abort) the entire template file execution is aborted.
Output
This section describes the interpretation of a template file
when used for output.
For each format string line, the current field value is
formatted according to the format string as in printf(3S).
The special control sequences are displayed as described
above. However, the control sequences \f, \k, and
\([r][,c]) now do something even if the standard output is
not a terminal, or the template is not being used in a
screen-oriented mode. The screen image is maintained
in-memory, the screen position movements are performed, and
when the template is finished, the in-memory screen image is
dumped. This is how utilities such as bugmail(1) and
dumpbug(1) are able to use the screen motion commands in
template files to generate output to files or pipes.
For each filter command line, the current field value is
passed through the filter as on input, but the return status
of the filter is ignored unless it is 255. Thus, "invalid"
field values are just displayed when the template is used
for output instead of looping hoping that the value would
somehow become valid.
When a template file is used for output (such as for
displaying a record or formatting a mail message), the value
of the field being derived is not stored as the new field
value, in contrast to template files used for input. This
is intended to make it easier to write template files
intended only for output in that you don't have to worry
about messing up the fields you are displaying. However,
explicit set and unset filter commands are always effective.
If a definition with the special fieldname Related-file is
encountered in the template file, the derivation lines for
that field are executed once through for every enclosure.
Prior to executing the lines for each enclosure, the current
field value is set to name of the enclosure. Therefore,
different enclosures can be processed differently by testing
the value of $$ with "if equals $$ enclosure-title", and
only executing parts of the derivation if it succeeds. This
is particularly useful with the putfile filter command. See
the end of the master.tmpl file for an example of this.
Note that this is only for operation values other than "f".
Format Strings
These are printf(3) style I/O strings that format input and
output. Each quoted format string encountered on input
contains optional text which may surround an optional field
specification, spec. At most one spec is allowed in each
format string.
The characters constituting the format string are displayed
one at a time until a percent (%) character is reached,
indicating that an input value is to be requested from the
user. Special C-style output control sequences are
supported, and have these effects:
\a bell
\b backspace
\e escape character(0x1b)
\f home up and clear screen
\k clear to end of current line
\n newline
\r carriage return
\ddd character represented by up to 3 octal digits
\([r][,c]) move cursor to screen row r and column c
\[xx] send parameterless termcap(3X) string xx
For example, the following format string
"\(8,42)\kProblem type: %-14.14s"
would position the cursor to row 8 column 42 on the screen,
erase whatever is on the screen from position 8,42 to the
end of line 8 and then position back to 8,42 and prompt with
Problem Type:. It then expects the user to enter a text
string whose length does not exceed 14 characters.
If in \([r][,c]) the arguments r and/or c are omitted, the
current row or column is assumed. The termcap strings can
be used for highlighting, such as \[so] to begin standout
mode, \[se] to end standout mode, \[us] to begin underline
mode, etc. Use of non-highlighting termcap strings may
produce undefined results. The control sequences \f, \k,
\([r][,c]), and \[xx] are still useful for output even if
the standard output is not a terminal, or if the template is
not being used in screen mode, because all output is done
using an in-memory screen image, and then dumped out when it
is complete. However, under those circumstances, cursor
motion and clearing control sequences have no effect during
input, and termcap strings have no effect if the standard
output is not a terminal.
Note that the tty user interface, bugs(1), supports these
termcap options, while the GUI interface, xddts(1),
currently ignores them.
When the user is being prompted for field input the current
field value (if any) is placed in the input stream as if the
user had already typed it. The user may back over or erase
these "default" characters if desired. When the user types
a newline character, the displayed value (if any) is
entered, and it becomes the new value for that field.
If, while being prompted to enter a value, the user instead
types his INTR character (usually control-C, see stty(1)),
the processing of the template file is aborted, and the
value of the current input field is unchanged, although any
previously changed fields remain changed.
The possible input values that will be valid are defined by
the specification characters following the percent
character. The specification characters have the same
syntax as the field specifications of printf(3S), and
describe the valid input values as follows:
- left justify (output only)
blank (ignored)
# (ignored)
m the number m specifies minimum output length
d a decimal digit string with optional sign is allowed
u an unsigned decimal digit string is allowed
f a decimal floating number with optional sign is allowed
e, E, g, G same as f, trailing e[+|-]xx or E[+|-]xx allowed
c any character is allowed
s any string of characters is allowed
Input validation of hexadecimal, octal, and binary numbers
is currently not supported. These and other specific
restrictions on the input value can be enforced using
user-supplied filter commands as described below.
If the input value is valid according to the specification,
the current field value is set equal to the input value and
the status returned by the format string is 0. If the input
value is not valid, the current field value is unchanged and
the status returned is 1.
If a format string does not contain a % and specification
characters, no user input is expected, the string is simply
displayed, the field value is unchanged, and the status
returned is always 0.
Filter Commands
Filter commands are used to validate and/or transform the
current field value. The field value is passed to the filter
command as its standard input and the standard output of the
command becomes the new value of the field. The exit status
of the filter command determines whether the derivation line
is successful; the exitstatus should be 0 if the value is
acceptable, and greater than zero if the value is not
acceptable. The program should expect to read the original
value (if it wants to look at it) from its standard input,
and produce the original or new value on its standard
output. The program should write any diagnostic messages
explaining the invalidity of the value on its standard error
output. If the exit status of any such command is 255, the
entire template file will be aborted and the value of the
current input field will be unchanged, although any
previously changed fields will remain changed.
As in sh(1), single and double quotation marks can be used
to include spaces and special characters in command
arguments. In addition, the following special forms are
recognized (except within single quotes), and replaced with
the indicated values:
$fieldname Value of the named field
$fieldname:n nth word in the value of the named field
(first word is $0)
$$ Value of the current field (or the enclosure
title)
$n nth word in the value of the current field
(or of the enclosure title)
$:n (same as $n)
$! Length of the current field (or of the
enclosure text) in bytes
$% Name of a temporary file containing the
enclosure text
$& Value of an enclosure field's timestamp
$~ The ClearDDTS home directory
$@ The current user's login id
The field called Filter-path is treated specially. It is
interpreted as a colon-separated list of directories to be
searched in order to locate filter commands. This field
should be set to a value at the top of all template files
that execute filter commands. If a filter command cannot be
located or executed, an appropriate message is displayed and
the command is assumed to have returned 255.
Comments
Comments (lines or portions of lines beginning with #,
except within quotes) may be placed anywhere in a template
file, and are ignored completely. This permits you to
document your customized template files, or any additions or
changes you make to the released ClearDDTS template files.
Multiplexed template files
To improve configurability, a single template file can be
used for different purposes. The best example of this is
the ClearDDTS master.tmpl file, which is found in
~ddts/class/classname/master.tmpl. This template file is
used for all screens and messages related to defect records.
This single file is used by bugs(1) and xddts(1) for
painting empty forms, prompting for field values, viewing
existing values, and modifying the values. It is used by
bugmail(1) to send mail notification messages. It is used
by dumpbug(1) to format bugs. Since the template file does
different things at different times, it has a mechanism for
conditional coding.
The ClearDDTS utilities add two special variables called
STATE and OPERATION that can be used to conditional control
the execution of the template file.
The value of STATE is set to the uppercase state letter that
corresponds to the requested Status of the bug record. That
is, when a state transition is being executed the current
status of the bug in defined in the field Status. The
requested status is then contained in the STATE variable.
The value of OPERATION is set to the single character
describing what operation is taking place. Operation values
that are supported are:
f Paint the form for entering a new STATE.
p Prompt for input required when entering the new STATE.
m Modify all fields for states up to and including STATE.
v View a bug in the given STATE, excluding Related-files.
l Dump a bug in the given STATE, including Related-files.
n Format notification mail for a defect in the STATE state.
The master.tmpl file makes heavy use of conditional if ...
fi statements, and uses the STATE and OPERATION variables to
determine which derivation lines to execute for each
situation.
Not all template files used by ClearDDTS are multiplexed.
For some easier-to-understand template files, try looking at
the ones in ~ddts/class/classname/user.index, or those in
~ddts/class/classname/summary.print.
You can use the tmpltest(1) program to see how those work.
You should copy some easier template files, modify them in
different ways, and use tmpltest on them to see what they do
until you are familiar with how to write a template file.
Enclosure Fields
Enclosure fields are used for variable length text. For
example, a user might edit a file that describes in detail
how to reproduce a problem. This variable length text can
be included and modified via appendfile and editfile
commands discussed below.
For enclosure fields, the "current field value" is the
enclosure's title. Thus, prompt strings and filter commands
that affect or use the current field value can be used to
set, change, or display the title of enclosure fields, and
$$ can be used to access the current title. However, only
the appendfile and editfile built-in filter commands affect
the actual text associated with enclosure fields (see
below).
BUILT-IN FILTER COMMANDS
When ClearDDTS executes a line in a field derivation it
first looks to see if the command is a "built-in" command.
Most common filter commands are built-in to improve
performance. If the command in the derivation line is not
one of the built-in commands, ClearDDTS will pass the entire
derivation line to system(3) to execute it.
To bypass a built-in command and use the system's version of
that command, prefix the command with the appropriate path.
For example, to use the system echo(1) command type
/bin/echo. The built-in command is only recognized as echo,
so the command /bin/echo will not be recognized as a
built-in and will be passed to system(3) for execution.
This is mainly useful when certain shell facilities are
required that are not provided by built-in commands, such as
I/O redirection.
Built-in commands have significantly better performance than
other commands, because they do not require the additional
processes that are created by system(3).
The following built-in commands are available:
abort
Never succeeds or fails; returns 255. Therefore,
executing this filter command always causes the
execution of the template description file to abort
without affecting the current field value.
and[if] [-f] command [arg ...]
Valid only within an enclosing if ... fi pair. If the
enclosing if condition is false, it does nothing.
Otherwise, command is executed. If the command fails,
execution continues with the else part of the enclosing
if, if any. If command succeeds, it does nothing and
succeeds. The two forms and and andif are equivalent;
use whichever seems more natural and meaningful to you.
Neither one affects the current field value.
appendfile [-f enclfield] [-t title] [-F file | arg ... ]
Append text to an enclosure, either echo arg arguments
or a file. Execute the echo built-in command (see
below) with the specified arg arguments followed by a
newline or read in the contents of file. Instead of
changing the current field value, append the resulting
text to the current enclosure field (or the enclosure
field named by enclfield).
If the field already exists but is not an enclosure
field, it is changed to be an enclosure field.
A final newline will be added to the enclosure if the
contents of file do not end in a newline.
If no enclfield is specified, but a field named
Log-name exists, the value of that field is used as the
title for the enclosure field, otherwise the title
History is used. If a title is specified, it must
match the enclosure title when searching for an
existing enclosure field, and if none match, it is used
as the title of a newly created enclosure field.
This filter command returns 255 (aborts) if there are
problems writing to the temporary file that represents
the enclosure text. Otherwise it succeeds.
See also the log built-in command.
break
Always succeeds immediately. Executing this filter
command causes the execution of the current field
derivation to cease immediately and return successfully
after updating the current field value. Execution
proceeds with the next field derivation in the file, if
any.
buffer
Turns on buffering mode (on is the default). The
output of the template file is written to an in-memory
screen image to reduce the terminal output necessary to
process cursor addressing, and flushed when the
template file is completed. Causes the output stream
to be flushed and allocates a new in-memory screen
image to be used for subsequent output. Always
successful; does not affect the current field value.
See also nobuffer.
call -i varname value [varname2 value2] ...
call -o varname value [varname2 value2] ...
Recursively invoke the current template file on the
current field values, with different initial values for
the indicated variables. The template file environment
(current field derivation execution, current variable
values, but NOT field values) is saved on a stack, and
the current template file is executed again from the
beginning (at its first field derivation) operating on
the current field values.
If the -i option is used, the new invocation of
template file will be considered to be in input mode;
if the -o option is used, it specifies output mode.
Exactly one of these two options must be specified.
The variable(s) named by varname, etc., if any, are set
to its corresponding value for the duration of that
invocation.
When, in the new invocation, the template file executes
the return filter command, or falls off the end of the
last derivation in the file, the previous template file
enviroment is restored to the way it was before the
call. In particular, the specified variables are
restored to their values prior to the call (or deleted
if they formerly did not exist).
The call command succeeds unless the new invocation of
the template file aborted, in which case the call
command also aborts. If the new invocation ended by
executing a successful return command, the call command
sets the current field value to the "return value"
string provided as the argument to the return command.
Otherwise, the current field value is cleared to an
empty string. See the return filter command, below.
case string1 [string2 ...]
See switch below.
cat file...
This command is built-in for efficiency, but it acts
like the UNIX cat(1) command. It sets the current
field value to the concatenation of the contents of the
file(s) named by its arguments. Always successful
unless one or more of the files does not exist, in
which case it returns 255.
change_history [ -f | -e ] [ "title" ]
Only applies to bugmail(1). When executed by bugmail,
differences between the old bug and the current bug are
calculated and a "field change log" is added at the
current point in the execution of the template file.
An implicit nobuffer and flush filter is run at the
beginning of change_history to flush the current output.
The buffer state is restored after this filter completes.
The -f flag limits differences to just fields. The -e
flag limits differences to just enclosures. If neither
the -e flag or the -f flag are specified, then both
field and enclosure changes will be calculated.
The optional title will be displayed at the beginning
of the field change log.
This filter will not affect the value of any field and
will not do anything in any other ddts program.
See the bugmail manpage for details in how to customize
and control the field change log including suppression
of certain fields and how to compare enclosure text.
combobox value ...
combobox -f filename
combobox -d filename fieldname
This filter command always succeeds. The listed items
are offered as suggestions for the user to enter into
this field. The value that the user selects does not
need to be one of the items from the list. This filter
has the same syntax as the oneof filter (see oneof
below).
The three forms of combobox allow you to specify
suggestions on the filter invocation line, or in a
specified file. The value of a field called Oneof-path
is used to search for the specified file, like for the
oneof filter.
The third alternate form of combobox behaves similarly
to the first two, except that the contents of fieldname
in the file filename is used to construct the list of
choices. If filename doesn't exist or is not readable
or if the fieldname is not found, combobox will offer
an empty list of suggestions. The file filename is
expected to be in dfile format (see dfile(5)).
The list of suggested values does not get displayed in
the bugs interface. The administrator should place the
suggestions in the help file for that field.
continue
Always fails. Executing this filter command causes the
execution of the current field derivation to repeat
from the beginning.
default
See switch below.
deletefile -f fieldname -t title
Deletes the corresponding enclosure field. Always
succeeds. The fieldname and title are mandatory options.
See the unset command to delete fields that are not
enclosure fields.
dialog [-w width] prompt-string
The dialog command is a filter used to prompt the user
for input. width is the maximum number of characters
that can be entered. The default is 40 characters if
width is not specified. prompt-string is the prompt
that will be output just before waiting for input from
the user. This command is just like specifying a format
string of
"prompt-string %-width.widths\n"
except that it will still wait for input from the user
even in output mode. The field value will be set to
the value entered by the user. See the Format Strings
section for more information. In xddts(1) this will
pop up a dialog that the user must respond to before he
can continue.
disable fieldname
Disables fieldname for input or output. Always
succeeds.
echo [string ...]
This command is built-in for efficiency, but it acts
like the UNIX echo(1) command. The -c option or \c
sequence for suppressing the final newline is not
recognized, and should not be used as it is
unnecessary. The current field value is set to the
output of the echo command. This filter command always
succeeds.
editfile [-i sourcefile] [-r | -R] ["enclosure title"]
Edit the text associated with the current enclosure
field. In bugs(1) the text will be edited with the
editor specified by the EDITOR environment variable (or
with vi if there is no EDITOR variable). In xddts(1)
the text will be edited using the editor as specified
in the Enclosure Editor dialog brought up from the
Options|Editor... menu option.
If the field already exists, it must be an enclosure
field. If the field does not already exist, the
initial text is copied from the sourcefile named with
the -i option, if any. If there is another argument
and the enclosure does not already have a title (that
is, the current field value is empty), the enclosure's
title is set to that argument. If there is a title,
and no existing field with the current field name and
that title, a new enclosure field is created.
Starting with version 4.2, the editfile syntax has been
extended to include the -r and the -R options. When
specified, the -r and -R options turn on "required"
checking, meaning that the editfile will fail if the user has not edited
the enclosure. "Edit" means that the enclosure cannot
be empty, it cannot contain only whitespace, and it
cannot be the same text that is in the sourcefile named
with the -i option if it was specified. The -R option
has the additional requirement that the enclosure cannot
contain the same text that was there before the editfile
was executed.
NOTE: The ability to make the web browser automatically
wrap an enclosure can conflict with the -R and -i options.
If the initial text file has lines longer than the
enclosure wrap width, then the browser will wrap those
lines and the -R flag will consider that a change to the
enclosure and not catch the required change.
This filter command fails if the current field exists
and is not an enclosure field. It returns 255 (aborts)
if there are problems copying the sourcefile.
Otherwise it succeeds.
elif [-f] command [arg ...]
Valid only within an enclosing if ... fi pair. If the
last enclosing if condition is true, execution
continues after the matching fi. Otherwise, command is
executed. If command succeeds, the if condition is now
considered to be true, and execution continues with the
next derivation line, up to the matching fi. If
command fails, the elif command does nothing more and
execution continues with the else part of the enclosing
if, if any. This command does not affect the current
field value.
enable fieldname
Enables fieldname for input or output. Always
succeeds.
end See switch below.
equals val1 [val2]
equal val1 [val2]
If both val1 and val2 are supplied, succeeds if val1
and val2 are equal strings, fails if they are
different. If only val1 is supplied, succeeds if the
current field value is equal to val1, fails if they are
different. The two forms equals and equal are
equivalent; use whichever seems more natural and
meaningful to you. Neither form affects the current
field value.
export [name] ...
Puts each named variable into the environment so that
it will be exported to programs invoked by filter
commands in the template file. If no name is
specified, the current field name is exported as an
environment variable. The name can be the name of a
parameter, an existing field, or an already existing
environment variable.
Note that the value placed in the environment is the
variable's current value, and future changes to the
value of the variable do not affect the value exported
to the environment, unless a subsequent export command
is executed for that variable name.
The export filter command returns 255 (aborts) if the
name does not already exist as a parameter, a field
name, or an environment variable; otherwise, it
succeeds. Does not affect the current field value.
filesb
This command is specific to xddts(1). It pops up a file
selection box and sets the current field value to the
files that were selected by the the user. Always
succeeds.
flush
If the template is being used for output to a terminal,
flushes the output so that the screen is current.
Otherwise, does nothing. Does not affect the current
field value. Always succeeds.
fullname [user]
Changes the field value to the user's real name as
defined in the gcos-field of the /etc/passwd(5) file.
If user is omitted, the invoking user is assumed.
Always succeeds.
The full name is obtained by extracting characters from
the beginning of the gecos portion of the password file
entry for that user, up to the first comma. If the
gecos portion is empty or begins with a comma, this
filter leaves the current value alone (possibly empty).
gooddate
Succeeds if the current field value is empty or if it
contains a valid date. All dates entered will be
converted to the ClearDDTS date format of YYMMDD.
See the class/software/helps/est-fix-date.H help file
for a complete definition of the date formats that are
recognized.
goodgroup
Succeeds if the current field value is empty or if it
is a valid group name found in /etc/group.
gooduser
Succeeds if the current field value is empty or if it
is a valid user name found in /etc/passwd.
goto fieldname
Never succeeds or fails. Executing this filter command
causes the execution of the current field derivation to
cease immediately without changing the current field
value. Execution then proceeds with next field
derivation that matches fieldname. The template file is
searched starting at the next field derivation,
wrapping to the beginning of the file, and stopping at
previous field derivation.
NOTE: The goto command discards any changes that have
been made to the current field value. This is a bug.
Note that the goto command can now be used to branch to
any field derivation in the template file. The
restriction that fieldname must be after the current
field has been removed. Note that infinite loops are
now possible, so be careful to provide a way to exit
the loop.
gui Succeeds if the template is being run from a graphical
application such as xddts(1). Does nothing to the
current field value. This can be used to modify the
behavior of a template that is used for both tty mode
and gui mode.
help filename
If the current field value is anything other than a
single question mark (?), this filter command succeeds
without affecting the current field value.
If the current field value is ?, the contents of the
file named by filename is piped through more(1) to the
user's terminal. The ? is removed from the current
field value, and the filter command fails (so that the
user will be reprompted for a real value after viewing
the help file). If the field called Help-path exists
and has a value, its value is interpreted as a
colon-separated list of directories to search to locate
the help file.
If filename does not refer to a readable file, or there
are other problems running the pager program, the
filter returns 255.
homedir [user]
Sets the current field value to the home directory of
the user ddts, or to the home directory of the named
user if one is provided. Succeeds if the specified
user exists and has a home directory, othewise it
fails.
hostname
Sets the current field to the hostname of the ClearDDTS
server. This does NOT return the host name of the
system executing the template file. See realhostname
below to do this.
if [-f] command [arg ...]
then
derivation line
[ else
derivation line
fi Executes the given command (or builtin) with optional
args, using the current field value as input. If
command succeeds (returns 0), the derivation lines after
then are executed, up to the matching fi or else. If
command fails (returns non-zero), and the optional else
part is present, the derivation lines after else are
executed, up to the matching fi. The -f option (in
input mode) allows the field value to be changed as a
result of executing command; it also suppresses any
messages command writes to standard error.
The if command itself always succeeds unless one of the
enclosed derivation lines returns 255. It does not
allow the command to change the current field value
unless the -f option is used.
See also and, or, elif.
inc [fieldname]
Increments the value of the current field (or the
specified field) by 1. If the field did not previously
exist, or did exist but its value is not numeric, it is
set to 1. Note that floating point numbers can also be
incremented. Always succeeds.
input
Succeeds if the template is being used for input, fails
otherwise. Does nothing to the current field value.
This can be used to modify the behavior of a template
that is used for both input and output, depending on
which way it is being used at the time.
interact [-u] cmd [arg ...]
This command allows external programs to temporarily
take over the screen and interact with the user, after
which control returns to the template file and the
screen is refreshed.
The arguments must be the name and arguments of a UNIX
command (that is, not a built-in filter command). This
causes the named command to be executed with normal
standard input, standard output, and standard error.
The -u option runs the command as the real user
executing the command. If the -u option is not used the
command is executed suid ddts. Be careful. You may not
wish your users to run externals programs with ddts's
permissions.
The current field value is fed to the command on its
file descriptor 3, and the resulting field value is
expected to be written by the command on its file
descriptor 4.
Note that ClearDDTS does not generate a [Hit any key to
continue] after running the script; if it wants the user
to look at its output, it should make its own
arrangements to let him look at it before returning from
the interaction.
The interact filter command returns the exit status of
the command that was executed, so the command should
exit 0 for success and non-zero for non-success, as
usual.
isfile
Succeeds if the current field is an enclosure field,
fails otherwise. It does not affect the current field
value.
log [-f enclfield] [-t title] echoarg ...
Causes a message to be appended to the named enclosure
field, which is created if it did not already exist. If
the field already exists but is not an enclosure field,
it is changed to be an enclosure field. The message
consists of the name of the program executing the
template file (such as bugs, xddts, or batchbug) the
current date and time, and the values of all of the
echoargs. As for every filter command, the arguments
can be fixed strings or can include field name values or
other values expanded via the "$" expansion mechanism.
If no enclfield is specified, but a field named Log-name
exists, the value of that field is used as the field
name of the enclosure field, otherwise History is used.
If title is specified, it must match the enclosure title
when searching for an existing enclosure field, and if
none match, it is used as the title of a newly created
enclosure field.
This filter command returns 255 (aborts) if there are
problems writing to the temporary file that represents
the enclosure text. Otherwise it succeeds.
See also the appendfile built-in command.
match val value ...
This filter command succeeds if val is a prefix of one
of the listed values. An individual value may contain
spaces if they are escaped or the value is enclosed in
quotation marks. The match filter fails if there are no
matches, and an appropriate message is output to
standard error.
See also the oneof filter command.
myname
Functions the same as fullname.
myphone
Functions the same as phone.
newbugid
This command allocates a new bug identifier and sets the
field value to its value. It returns success if a new
bug identifier was allocated successfully. It returns
255(abort) if an error was encountered.
nobuffer
Causes the in-memory screen image to be dumped and
flushed to the output stream, and causes all subsequent
output to be written directly to the output stream
instead of kept in an in-memory screen image. Always
successful; does not affect the current field value.
See the buffer filter command for more information about
output screen image buffering.
not command [arg ...]
The command not executes command with optional arguments
args. If command fails then not will return a successful
exit status. If command passes then not will return an
unsuccessful exit status. Does not affect the current
field value.
null ["value"]
The command null succeeds if the current field value is
empty, and fails if it is not. If value is supplied then
it will succeed if value is null. Be sure to quote value
so in the case it is is empty it will still be
recognized as an argument.
Neither form affects the current field value.
oneof [-i] value ...
This filter command succeeds if the current field value
is a prefix of exactly one of the listed values. The
field value is set to the matched value. An individual
value may contain spaces if they are escaped or if the
value is enclosed in quotation marks. The oneof filter
fails and an appropriate message is output to standard
error if if there are multiple matches or no matches.
The -i option makes the match comparison case
insensitive. See also the match filter command. See
also the someof filter command.
oneof -f filename
This alternate form of oneof behaves similarly to the
first, except that it succeeds if the current field
value is a prefix of exactly one of the lines in the
text file specified by filename. If a field called
Oneof-path has a value, its value is interpreted as a
colon-separated list of directories to search to locate
filename. The oneof filter command fails if there are
multiple matches or no matches, or returns 255 if
filename does not refer to a readable file. An
appropriate message is output to standard error if it
fails, or if it aborts.
oneof -d filename fieldname
This alternate form of oneof behaves similarly to the
first two, except that the contents of fieldname in the
file filename is used to construct the list of choices.
If filename doesn't exist or is not readable or if the
fieldname is not found, oneof will return 255. The file
filename is expected to be in dfile format (see
dfile(5)).
optional
Always succeeds. Does nothing to the current field
value. For example, this can be used as a placeholder
if there are no other derivation lines, or as a comment
for fields that used to be required.
or[if] [-f] command [arg ...]
Valid only within an enclosing if ... fi pair. If the
last enclosing if condition is true, this does nothing.
Otherwise, command is executed. If command succeeds,
execution continues with the next derivation line. If
command fails, the or command does nothing and execution
continues with the else part of the enclosing if. The
two forms or and orif are equivalent; use whichever
seems more natural and meaningful to you. Neither one
affects the current field value.
output
Succeeds if the template is being used for output, fails
otherwise. Does not modify the current field value.
This can be used to modify the behavior of a template
that is used for both input and output.
phone [user]
Always succeeds. Changes the current field value to
user's phone number if any is defined in /etc/passwd;
otherwise leaves the current value alone (possibly
empty). If user is omitted, the invoking user is
assumed.
The phone number is derived by extracting characters
from the gecos field of the passwd(5) file entry. Any
characters in the gecos field between the second comma
(if any) and the next comma or the end of the field are
assumed to be the phone number. If the gecos portion of
the user's passwd(5) file entry is empty, or contains
fewer than two commas, the phone filter leaves the
current field value alone (possibly empty).
popscreen
This command restores the screen and the cursor position
saved by a prior call to pushscreen. It is used in
conjunction with pushscreen and call.
printenv env-variable
Sets the field value to the value of the environment
variable env_variable. If env-variable doesn't exist in
the environment then the field value will be set to an
empty string. Always succeeds.
projassert -o projectname
This filter succeeds if projectname is owned by the
current system and fails if it is not. The field value
is set to projectname on success. On failure an error
message is output to standard error.
projassert -s projectname
This filter succeeds if projectname is subscribed to by
the current system and fails if it is not. The field
value is set to projectname on success. On failure an
error message is output to standard error.
projassert -b projectname
This filter succeeds if you are able to log bugs against
projectname and fails if you cannot. The field value is
set to projectname on success. On failure an error
message is output to standard error.
projassert -e projectname
This filter succeeds if projectname exists on the
current system and fails if it doesn't. The field value
is set to projectname on success. On failure an error
message is output to standard error.
projassert -n projectname
This filter succeeds if projectname doesn't exist on the
current system and fails if does. The field value is set
to projectname on success. On failure an error message
is output to standard error.
pushscreen
This command saves the current screen and cursor
position into an in memory stack. It is used in
conjunction with popscreen and call.
putfile [-m]
Succeeds if the current field is an enclosure field,
otherwise it writes an error message to standard error
and returns 255 (aborts). If it succeeds, it also has
the effect of displaying the contents of the related
file whose title is the current value, if any. If the
-m option is used, any lines of the enclosure text that
would confuse mail sending programs (such as lines
beginning with ~ or .) are output such that they won't.
realhostname
Returns the real host name of the system that is
executing the template file. The hostname command
returns the hostname of the ClearDDTS server.
required
Succeeds if the current field value is not empty; fails
otherwise.
resetuid command
Executes command as the actual user instead of the user
ddts. Returns the exit status of command.
return [string]
Never succeeds or fails. Executing this filter command
causes the execution of the current template file to
cease immediately and return successfully without
changing the current field value, and without examining
any of the remaining field derivations in the file.
In addition, if a second argument, string, is provided,
it is made available to the template file's calling
environment as the "return value" of the template file
execution. See the call filter command, above. If the
string argument is not provided, or when execution of a
template file "falls off the end" after the last field
without a return command, the return value of the
template file is an empty string.
securitytoken
Returns the users security token from the
~ddts/etc/security file.
set fieldname value [fieldname2 value2] ...
Adds, or updates the existing value of fieldname so that
its value is equal to the corresponding value. If
fieldname is one of the special variable, such as
OPERATION, the special variable is updated instead of
creating a new field. Always succeeds.
setfile [fieldname ...]
Causes the current field (or fieldname) to be converted
to an enclosure field. If fieldname does not exist it
will be created as an enclosure field. Always succeeds.
skip
Never succeeds or fails. Executing this filter command
causes the execution of the current field derivation to
cease immediately without changing the current field
value. Execution proceeds with the next field
derivation in the file, if any. This differs from break
in that it does not update the current field value
before going on.
someof value ...
This filter command assumes that the field value is
composed of a list of values separated by spaces. This
command succeeds when there is a match for each value in
the field value list with a value in the someof's value
list. This command fails when any of the values in the
field value list does not have a match in the someof's
value list. See also the oneof filter command.
someof -f filename
This alternate form of someof behaves similarly to the
first, except that the value list is read from the lines
in the text file specified by filename. If a field
called Oneof-path has a value, it is interpreted as a
colon-separated list of directories to be searched to
locate filename. The someof filter will return 255 if
filename does not exist or is not readable. See also
the oneof filter command.
someof -d filename fieldname
This alternate form of someof behaves similarly to the
others, except that the contents of fieldname in
filename is used as the someof value list. The someof
filter returns 255 if filename does not exist or is not
readable, or if fieldname is not found in filename. See
also the oneof filter command.
WARNING: The someof filter does NOT support imbedded
spaces in the list values (e.g. "hello world"). Initial
input will succeed but later validation will fail. You
may instead use an underscore (e.g. "hello_world").
switch [text]
[ case string1 [string2 ...]
derivation line
...
[ case -f filename
derivation line
...
[ default
derivation line
end The given text (or if none, the current field value) is
used to select which of the associated groups of
derivation lines to execute. Each group of derivation
lines is preceded by either a case command or a default
command. The group of lines selected to execute is the
first group whose case line contains a string argument
matching the switch text. The comparison is done as if
oneof were used for the case strings, so the text will
match any string of which it is a prefix. The case -f
option can be used to specify a file of strings to be
matched instead of listing them, as in oneof.
If no case string matches, the group of lines following
default is executed, up until the next case or end
command. If no case string matches, and there is no
default case, nothing is executed.
CAUTION: Note that multiple case strings can be used in
a single case line and that the group of lines for each
case is terminated by the next case, default, or end
command. Therefore, using separate, adjacent case
commands to introduce a group of lines shared by those
cases will not have the desired effect. Instead, all
the cases to be associated with the same group of
derivation lines must appear together on the same case
command line, or the -f option should be used to name a
file containing the case strings to be matched.
CAUTION: If multiple strings on a single case line match
the switch text, that case is considered NOT to match.
CAUTION: the break command should not be used to end
each group of derivation lines, as that would cause the
entire current field derivation to succeed immediately
without executing anything else in that derivation.
Cases should be separated by case and default commands.
The switch, case, default, and end commands themselves
always succeed, but any of the selected derivation lines
can fail, abort, return, break, or continue as usual.
The case -f command returns 255 if filename does not
refer to a readable file, otherwise it succeeds. The
selected derivation lines can modify the current field
value, but the control statements themselves do not
modify it.
today [arg]
Sets the field value to today's date in ClearDDTS format
of YYMMDD if arg is not supplied or in YYMMDDHHMMSS if
arg is supplied. Always succeeds.
uniquetitle [-q] [-f fieldname] [title]
Succeeds if no enclosure field with indicated fieldname
and title exists in the current field table. If no
fieldname is specified, the current field name is
assumed. If no title is specified, the current field
value is assumed. (Note that until the successful
completion of the current derivation, the current field
name and value are not entered into the table.) This
filter command fails if there is already such a field
with that name and title in the table. The -q option
suppresses the error message ordinarily displayed when
the title is not unique.
unset fieldname
Deletes the named field, if any, from the field table
being used. If the field is an enclosure field, its
associated text is removed. Always succeeds.
whoami
Generates the user name of the invoking user. Always
succeeds.
yesno
Succeeds if the current field value is empty or begins
with y, Y, n, or N. Sets the current field value to Y
or N as appropriate.
The built-in commands do not understand the special features
of sh(1), such as output redirection, pipes, or filename
pattern expansion. To force the shell to interpret a filter
command (and thus enable the use of these features), ensure
that the first word of the line does not match one of the
built-in command names. For example, to use the UNIX
command echo instead of the built-in version of echo, the
command /bin/echo (or /usr/bin/echo, as appropriate) could
be used.
BUGS
Placing the # in a field name will have undefined results,
and should not be used there. Example:
Field#1: echo $Field#2
Field#1 will be set to the value of $Field. The #2 is a
comment, but the #1 is part of a field name.
If the first line in the template file begins with
#:
then a field by then name of # will be saved to the
database. This ONLY occurs on the first line.
The phone command doesn't modify the field value unless its
current value is null. So this calls must be preceeded by
an echo command to clear it out. That is:
echo ""
phone
The goto directive discards the changes to the current field
value.
The following error
Error in template file
/usr/ddts/class/software/master.tmpl,
field "Engineer": WARNING: Unclosed ' quote
can occur if a field value that contains a single quote(')
is expanded within a derivation line in the template file.
This is known bug with the template file parser and has no
ill effects on the execution of the template file.
SEE ALSO
tmpltest(1), bugs(1), dumpbug(1), xddts(1), dfile(5)
ClearDDTS Administrator's Guide