idl(4) DG/UX 5.4R3.00 idl(4)
NAME
idl - interface description language
DESCRIPTION
Idl is a language for describing interfaces without respect to the
display mechanism which is used to present the information. The
interface is described in terms of the menus, screens, and queries
that are presented to the user. The language contains statements
which can be used to define the entire menu hierarchy.
Idl files are read by the interface description interpreter and
compiler, idi(1) and idc(1).
Syntax
The language is free format, with whitespace separating tokens.
Whitespace is one or more spaces, tabs, or newlines. The character #
indicates that the remainder of a line is a comment.
The language is built up from several primitive token types: names,
values, numbers, and keywords.
A name is a sequence of letters, digits, and underscores. A value is
a sequence of characters other than double quote ("). If the value
contains whitespace, it must be surrounded by double quotes. A
number is a sequence of one or more digits (with an optional leading
sign character) which is interpreted as a base 10 number.
The following keywords are reserved, and may not be used otherwise:
add boolquery end export
menu operation querygroup rangequery
screen selectquery set text
textquery to
The syntax of the language is described below:
statement:
menu name [ menu-attributes ] ... end
operation name [ operation-attributes ] ... end
text name [ text-attributes ] ... end
screen name [ screen-attributes ] ... end
querygroup name [ querygroup-attributes ] ... end
textquery name [ textquery-attributes ] ... end
boolquery name [ boolquery-attributes ] ... end
selectquery name [ selectquery-attributes ] ... end
rangequery name [ rangequery-attributes ] ... end
set name = value
add name1 to name2
export name
These statements, except the set, add, and export statements, create
an instance of a database class. For example, a menu statement
Licensed material--property of copyright holder(s) 1
idl(4) DG/UX 5.4R3.00 idl(4)
creates an instance of the menu class; the instance is named name and
has the attributes specified by menu-attributes.
Each of the attribute lists ( menu-attributes, operation-attributes,
and so on ) are of the form:
attribute-list:
[ attribute-list ] attribute-item
attribute-item:
name = value
Below are the other "types" which the value of an attribute may take.
name-list:
name
"[ name-list ] name"
value-list:
value
"[ value-list ] value"
command:
value
A command is different from a value in that a command is a string
which has meaning if passed to the shell (sh(1)) for execution.
boolean:
${YES}
${NO}
direction:
${HORIZONTAL}
${VERTICAL}
menu Class
Instances of the menu class are simple containers for operations.
Menus are used to specify the hierarchy of operations. Menus are
added to other menus with the add statement.
The following attributes are allowed for the menu class:
Licensed material--property of copyright holder(s) 2
idl(4) DG/UX 5.4R3.00 idl(4)
+-----------------------------------------------------+
| menu Attribute Set |
+--------------+-----------+--------------------------+
|Name | Type | Default |
+--------------+-----------+--------------------------+
|access-groups | name-list | "" |
|access-names | name-list | "*" |
|access-roles | name-list | "administrator" |
|default | value | "" |
|description | value | "No description" |
|help | value | "No help for this menu." |
|mnemonic | value | "" |
|name | value | "Unnamed" |
|title | value | "Untitled" |
|visible | boolean | "${YES}" |
+--------------+-----------+--------------------------+
The attributes have the following meanings:
access-groups
A whitespace-separated list of group names which are
allowed access to this menu. A star ("*") means that all
groups are allowed access.
access-names
A whitespace-separated list of user names which are allowed
access to this menu. A star ("*") means that all users are
allowed access.
access-roles
A whitespace-separated list of administrative roles which
are allowed access to this menu. A star ("*") means that
users with any role are allowed access.
default The name or number of the item within the menu to be
displayed as the default for the menu. The interface
driver may ignore this attribute.
description
A one-line description of the menu and what is contained
under it. The description is displayed by the parent menu
before this menu is selected, and may be displayed at the
same time as the menu's name.
help A message to display if the user requests help on this
menu.
mnemonic A one-character abbreviation for the menu's name.
name A one or two word name for the menu. The name is displayed
in the parent menu to identify this menu.
title A string, such as "Main Menu" which is used as the title
for the menu. This string may be displayed above the items
Licensed material--property of copyright holder(s) 3
idl(4) DG/UX 5.4R3.00 idl(4)
in the menu when this menu is selected.
visible A boolean indication of whether this menu will be
displayed. If the value is ${NO}, the menu will not be
shown by idi(1).
operation Class
Instances of the operation class are the basic actions which can be
performed by the user. Operations may contain queries which must be
answered before performing the action. Operations are added to menus
with the add statement.
The following attributes are allowed for the operation class:
+--------------------------------------------------------------------+
| operation Attribute Set |
+-----------------------+------------+-------------------------------+
|Name | Type | Default |
+-----------------------+------------+-------------------------------+
|access-groups | name-list | "" |
|access-names | name-list | "*" |
|access-roles | name-list | "administrator" |
|action | command | "" |
|action-batch-mode | boolean | "${NO}" |
|action-error-policy | value | "" |
|action-input | value | "" |
|action-message | value | "Operation failed." |
|action-output-filter | command | "" |
|action-targets | value-list | "" |
|action-timeout | value | "" |
|allow-multiple-targets | boolean | "${NO}" |
|allow-remote-target | boolean | "${YES}" |
|cancel-action | command | "" |
|cancel-action-message | value | "" |
|confirm | value | "" |
|description | value | "No description" |
|entry-action | command | "" |
|entry-action-message | value | "Entry action failed." |
|exit-action | command | "" |
|exit-action-message | value | "Exit action failed." |
|help | value | "No help for this operation." |
|mnemonic | value | "" |
|name | value | "Unnamed" |
|persistent | boolean | "${NO}" |
|repeat | value | "" |
|undefined-variables | value-list | "" |
|visible | boolean | "${YES}" |
+-----------------------+------------+-------------------------------+
The attributes have the following meanings:
access-groups
A whitespace-separated list of group names which are
allowed access to this operation. A star ("*") means that
Licensed material--property of copyright holder(s) 4
idl(4) DG/UX 5.4R3.00 idl(4)
all groups are allowed access.
access-names
A whitespace-separated list of user names which are allowed
access to this operation. A star ("*") means that all
users are allowed access.
access-roles
A whitespace-separated list of administrative roles which
are allowed access to this operation. A star ("*") means
that users with any role are allowed access.
action A shell command line to execute when this operation is
selected (after any queries for the operation are answered
and confirmed). This command is not executed if the
operation is canceled.
action-batch-mode
A boolean indication of whether or not this command should
be performed in the background. If the value of this
attribute is empty, the session Batch Mode (as set via the
:Target builtin command) is used.
action-error-policy
The policy to follow if one of the action-targets is
unreachable. The value of this attribute must be empty, or
one of ${ABORT}, ${RETRY}, or ${CONTINUE}. If the value of
this attribute is empty, the session Error Policy (as set
via the :Target builtin command) is used.
action-input
The text to use as the standard input to the action for the
operation.
action-message
The error message to display if the action for the
operation fails.
action-output-filter
The command line to execute to process any output produced
by the operation's action. This command is expected to
read its standard input and write to its standard output.
action-targets
The comma-separated list of targets on which the action is
to be performed. If the value of this attribute is empty,
the action is performed on the local host.
action-timeout
The amount of time, in seconds, to wait for the command to
finish on a remote host before concluding that the host is
unreachable. If the value of this attribute is empty, the
session Timeout (as set via the :Target builtin command) is
used.
Licensed material--property of copyright holder(s) 5
idl(4) DG/UX 5.4R3.00 idl(4)
allow-multiple-targets
A boolean indication of whether this operation may be
applied to more than one target at time. If the value is
${NO}, the operation may be applied only to a single target
host at a time.
allow-remote-target
A boolean indication of whether this operation may be
applied to a target host other than the one on which idi is
running.
cancel-action
A shell command line to execute if processing of the
operation is aborted at the user's request. This command
is performed before the exit-action for the operation.
cancel-action-message
The error message to display if the cancel-action for the
operation fails.
confirm A string to use as a confirmation prompt which must be
answered before the operation is executed. If the value of
this attribute is the empty string, no confirmation is
performed.
description
A one-line description of the operation. The description
is displayed by the parent menu before this operation is
selected, and may be displayed at the same time as the
operation's name.
entry-action
A shell command line to execute as soon as the operation is
selected, before any screens or queries are presented. If
the value of the repeat attribute is not empty, the entry-
action is performed once for each iteration of the
operation.
entry-action-message
The error message to display if the entry-action for the
operation fails.
exit-action
A shell command line to execute after all processing of the
operation has completed. This command is executed after
the action command, and is executed even if the operation
is canceled. If the value of the repeat attribute is not
empty, the exit-action is performed after all iterations of
the operation.
exit-action-message
The error message to display if the exit-action for the
operation fails.
Licensed material--property of copyright holder(s) 6
idl(4) DG/UX 5.4R3.00 idl(4)
help A message to display if the user requests help on the
operation.
mnemonic A one-character abbreviation for the operation's name.
name A one or two word name for the operation. The name is
displayed in the parent menu to identify this operation.
persistent
A boolean indication of whether this operation should be
repeated continuously until the user explicitly cancels the
operation.
repeat A string to present before repeating the operation. If the
value of this attribute is the empty string, the operation
is performed only once. Otherwise, the string is
presented, and the user is given the opportunity to repeat
or cancel the operation.
undefined-variables
A list of idl variables which are referenced by the
operation, or any of its children, but which are not
defined in the operation. Such variables may cause
warnings when compiling with certain idc options; this
attribute provides a way of silencing those idc warnings.
visible A boolean indication of whether the operation will be made
available. If the value is ${NO}, the operation will
appear in the parent menu but will not be available.
An operation may have up to three actions. These are identified by
the second-action attribute and the corresponding second-action-
batch-mode, second-action-error-policy, second-action-input, second-
action-message, second-action-output-filter, second-action-targets,
and second-action-timeout attributes. The same is true for the
third-action.
text Class
Instances of the text class are simple text holders. Text objects
may be added to querygroups with the add statement.
The following attributes are allowed for the text class:
+-----------------------------+
| text Attribute Set |
+--------+---------+----------+
|Name | Type | Default |
+--------+---------+----------+
|value | value | "" |
|visible | boolean | "${YES}" |
+--------+---------+----------+
The attributes have the following meanings:
Licensed material--property of copyright holder(s) 7
idl(4) DG/UX 5.4R3.00 idl(4)
value A text string to display.
visible A boolean indication of whether the text will be displayed.
screen Class
Instances of the screen class are holders for querygroups. All of
the querygroups of a certain screen are guaranteed to be evaluated at
the same time and before the querygroups of any later screens. The
interface driver may also display screens as separate windows.
Screens may be added to operations with the add statement.
The following attributes are allowed for the screen class:
+---------------------------------------------------------+
| screen Attribute Set |
+----------------------+---------+------------------------+
|Name | Type | Default |
+----------------------+---------+------------------------+
|cancel-action | command | "" |
|cancel-action-message | value | "" |
|entry-action | command | "" |
|entry-action-message | value | "Entry action failed." |
|exit-action | command | "" |
|exit-action-message | value | "Exit action failed." |
|title | value | "Untitled" |
|validation | command | "" |
|validation-message | value | "Validation failed." |
|visible | boolean | "${YES}" |
+----------------------+---------+------------------------+
The attributes have the following meanings:
cancel-action
A shell command line to execute if processing of the screen
is aborted at the user's request. This command is
performed before the exit-action for the screen.
cancel-action-message
The error message to display if the cancel-action for the
screen fails.
entry-action
A shell command line to execute when entering the screen.
entry-action-message
The error message to display if the entry-action fails.
exit-action
A shell command line to execute when leaving the screen.
This is executed after all queries for the screen are
validated, and is executed even if the user terminates the
screen.
Licensed material--property of copyright holder(s) 8
idl(4) DG/UX 5.4R3.00 idl(4)
exit-action-message
The error message to display if the exit-action fails.
title A string such as "Add a User" which is used as a title for
the screen. This string may be displayed above the queries
and querygroups which compose the screen.
validation
The command string to execute on the administered host to
determine if the values entered for the screen are valid.
The command must return zero if all values in the screen
are valid, and return non-zero if the values are not valid.
validation-message
The custom error message to display if the screen
validation fails.
visible A boolean indication of whether the screen (and any
querygroups below it) will be displayed. This attribute is
evaluated after an operation is chosen, at the same time as
all other screens for the operation, and before the visible
attributes of the querygroups are evaluated.
querygroup Class
Instances of the querygroup class are used to group similar queries.
The interface driver may use querygroup information to display
related queries in a more attractive manner. Querygroups may be
added to screens with the add statement.
The following attributes are allowed for the querygroup class:
+------------------------------------------------------+
| querygroup Attribute Set |
+-------------------+-----------+----------------------+
|Name | Type | Default |
+-------------------+-----------+----------------------+
|orientation | direction | "${VERTICAL}" |
|title | value | "" |
|validation | command | "" |
|validation-message | value | "Validation failed." |
|visible | boolean | "${YES}" |
+-------------------+-----------+----------------------+
The attributes have the following meanings:
orientation
The preferred layout of queries within the querygroup. The
value may be either $VERTICAL or $HORIZONTAL. The default
is $VERTICAL. This attribute may be ignored by the display
driver.
title A string describing the queries within the querygroup.
This string may be displayed above the queries which
compose the querygroup.
Licensed material--property of copyright holder(s) 9
idl(4) DG/UX 5.4R3.00 idl(4)
validation
The command string to execute on the administered host to
determine if the values entered for the querygroup are
valid. The command must return zero if all values in the
querygroup are valid, and return non-zero if the values are
not valid.
validation-message
The custom error message to display if the querygroup
validation fails.
visible A boolean indication of whether the querygroup (and any
queries below it) will be displayed. This attribute is
evaluated after a screen is entered, and is evaluated at
the same time as the visible attributes of all other
querygroups for the screen.
Queries
The following attributes are allowed for all query types: textquery,
boolquery, selectquery, and rangequery:
+-----------------------------------------------+
| Query Attribute Set |
+--------------+---------+----------------------+
|Name | Type | Default |
+--------------+---------+----------------------+
|confirm | value | "" |
|confirm-value | value | "" |
|default | value | "" |
|help | value | "No help available." |
|preserve | boolean | "${NO}" |
|prompt | value | "" |
|variable | value | "" |
+--------------+---------+----------------------+
The attributes have the following meanings:
confirm The string to use as a confirmation prompt which must be
answered by the user before execution continues.
Confirmation is performed if the value entered for the
query matches the confirm-value.
confirm-value
An ed(1)-style regular expression. If the value entered
for a query matches confirm-value, confirmation of the
value is sought (using the confirm string as the prompt).
default The default value of the variable.
help The text string to display if the user requests help on the
query.
preserve An indication of whether the value of variable should be
saved in a global variable. If the value of this attribute
Licensed material--property of copyright holder(s) 10
idl(4) DG/UX 5.4R3.00 idl(4)
is ${YES}, the variable's value (after being validated and
confirmed) is saved in a global idl variable named
variable. If the value of this attribute is ${NO}, the
variable is destroyed when the operation is complete.
prompt The text string to be displayed when the query is
presented.
variable The name of an idl variable that is set by the query.
variables may be referenced in other attribute strings by
using the $variable notation.
textquery Class
Instances of the textquery class describe how to retrieve an
arbitrary text entry from the user. Textqueries may be added to
querygroups or to selectqueries with the add statement.
The following attributes are allowed for the textquery class:
+---------------------------------------------------+
| textquery Attribute Set |
+------------------+---------+----------------------+
|Name | Type | Default |
+------------------+---------+----------------------+
|confirm | value | "" |
|confirm-value | value | "" |
|default | value | "" |
|help | value | "No help available." |
|max-columns | number | "40" |
|max-lines | number | "1" |
|preserve | boolean | "${NO}" |
|prompt | value | "Enter text" |
|semantics | command | "" |
|semantics-message | value | "" |
|show-columns | number | "40" |
|show-lines | number | "1" |
|syntax | command | "" |
|syntax-message | value | "" |
|variable | value | "Text" |
+------------------+---------+----------------------+
The confirm, confirm-value, default, help, preserve, prompt, and
variable attributes are generic Query Attributes. The other
attributes have the following meanings:
max-columns
The maximum number of columns of text accepted for the
query.
max-lines The maximum number of lines of text accepted for the query.
semantics A command string to execute on the administered host to
determine if the value entered for the query is
semantically correct. The command must return zero if the
Licensed material--property of copyright holder(s) 11
idl(4) DG/UX 5.4R3.00 idl(4)
value is correct, and return non-zero if the string is not
correct. The command may be a builtin command.
semantics-message
The custom error message to display if the semantics check
fails. If the value of this attribute is empty, the error
message is generated by idi from the prompt and the entered
value.
show-columns
The maximum number of columns to display at one time. The
default value for this attribute is the value of max-
columns. This attribute may be ignored by the display
driver.
show-lines
The maximum number of lines to display at one time. The
default value for this attribute is the value of max-lines.
This attribute may be ignored by the display driver.
syntax A command string to execute on the administering host to
determine if the value entered for the query is
syntactically correct. The command must return zero if the
value is correct, and return non-zero if the value is not
correct. The command may be a builtin command.
syntax-message
The custom error message to display if the syntax check
fails. If the value of this attribute is empty, the error
message is generated by idi from the prompt and the entered
value.
boolquery Class
Instances of the boolquery class describe how to retrieve a positive
or negative response from the user. Boolqueries may be added to
querygroups with the add statement.
The following attributes are allowed for the boolquery class:
+-----------------------------------------------+
| boolquery Attribute Set |
+--------------+---------+----------------------+
|Name | Type | Default |
+--------------+---------+----------------------+
|confirm | value | "" |
|confirm-value | value | "" |
|default | boolean | "${YES}" |
|help | value | "No help available." |
|preserve | boolean | "${NO}" |
|prompt | value | "Enter yes or no" |
|variable | value | "Bool" |
+--------------+---------+----------------------+
The confirm, confirm-value, default, help, preserve, prompt, and
Licensed material--property of copyright holder(s) 12
idl(4) DG/UX 5.4R3.00 idl(4)
variable attributes are generic Query Attributes.
selectquery Class
Instances of the selectquery class describe how to retrieve one or
more choices from a list of choices. Selectqueries may be added to
querygroups with the add statement.
The following attributes are allowed for the selectquery class:
+----------------------------------------------------------+
| selectquery Attribute Set |
+---------------------+------------+-----------------------+
|Name | Type | Default |
+---------------------+------------+-----------------------+
|abbreviation-message | value | "" |
|abort-message | value | "No possible values." |
|assign-values | value-list | "" |
|confirm | value | "" |
|confirm-value | value | "" |
|default | value | "" |
|exclusive | boolean | "${YES}" |
|help | value | "No help available." |
|input-separator | value | ", " |
|number | boolean | "${YES}" |
|output-separator | value | "," |
|packed | boolean | "${YES}" |
|possible-values | value-list | "" |
|preserve | boolean | "${NO}" |
|prompt | value | "Enter selection" |
|translation | value | "" |
|show-columns | value | "0" |
|show-lines | value | "0" |
|variable | value | "Selection" |
+---------------------+------------+-----------------------+
The confirm, confirm-value, default, help, preserve, prompt, and
variable attributes are generic Query Attributes. The other
attributes have the following meanings:
abbreviation-message
The message to display if the user enters an abbreviation
for one of the values in the possible-values list. The
variable is set to the value of the matching item in the
possible-values list before the abbreviation-message is
displayed.
abort-message
The message to display if an operation must be aborted
because the value of possible-values for this query is
empty.
assign-values
A newline-separated list of values which may be assigned to
the variable when the user selects one of the possible-
Licensed material--property of copyright holder(s) 13
idl(4) DG/UX 5.4R3.00 idl(4)
values. The value of this attribute may be a backquoted
string which is executed to dynamically produce the list
described.
exclusive If the value of this attribute is ${YES}, only one of the
possible-values for the query may be selected. If the
value of this attribute is ${NO}, more than one of the
values may be selected.
input-separator
The set of characters which may be used by the user to
separate multiple selections when selecting more than one
possible-value. This attribute is used only if the value
of the exclusive attribute is ${NO}.
number If the value of this attribute is ${YES}, the possible-
values of the query will be automatically numbered by the
interface driver. If the value of this attribute is ${NO},
the possible-values will not be numbered. This attribute
should be set to ${NO} when the possible-values are numbers
so that there is no confusion between the possible-values
and the automatically-generated numbers.
output-separator
The character string which is used to separate multiple
selections when assigning a value to the query's variable.
This attribute is used only if the value of the exclusive
attribute is ${NO}.
packed If the value of this attribute is ${YES}, the interface
driver may conserve screen space when presenting the query.
If the value is ${NO}, screen space may not be conserved.
possible-values
A newline-separated list of choices for the query. The
value of this attribute may be a backquoted string which is
executed to produce the list of values.
show-columns
The maximum number of columns to display. The default
value for this attribute, 0, means that the display driver
should determine an appropriate maximum. This attribute
may be ignored by the display driver.
show-lines
The maximum number of lines to display at one time. The
default value for this attribute, 0, means that the display
driver should determine an appropriate maximum. This
attribute may be ignored by the display driver.
translation
A string which may be evaluated if text entered for the
query does not match any of the choices for the query.
This string should evaluate to a valid choice for the
Licensed material--property of copyright holder(s) 14
idl(4) DG/UX 5.4R3.00 idl(4)
query.
rangequery Class
Instances of the rangequery class describe how to retrieve a number
within a given range from the user. Rangequeries may be added to
querygroups with the add statement.
The following attributes are allowed for the rangequery class:
+------------------------------------------------------+
| rangequery Attribute Set |
+------------------+-------------+---------------------+
|Name | Type | Default |
+------------------+-------------+---------------------+
|confirm | value | "" |
|confirm-value | value | "" |
|default | value | "0" |
|help | value | "No help available" |
|preserve | boolean | "${NO}" |
|prompt | value | "Enter value" |
|range | number-list | "0 1" |
|semantics | command | "" |
|semantics-message | value | "" |
|syntax | command | "" |
|syntax-message | value | "" |
|variable | value | "Range" |
+------------------+-------------+---------------------+
The confirm, confirm-value, default, help, preserve, prompt, and
variable attributes are generic Query Attributes. The other
attributes have the following meanings:
range A whitespace-separated list of two numbers which are the
minimum and maximum values for the query. The value of
this attribute may be a backquoted string which is executed
to produce the list of numbers.
semantics A command string to execute on the administered host to
determine if the value entered for the query is
semantically correct. The command must return zero if the
value is correct, and return non-zero if the value is not
correct. The command may be a builtin command.
semantics-message
The custom error message to display if the semantics check
fails. If the value of this attribute is empty, the error
message is generated by idi from the prompt and the entered
value.
syntax A command string to execute on the administering host to
determine if the value entered for the query is
syntactically correct. The command must return zero if the
value is correct, and return non-zero if the value is not
correct. The command may be a builtin command.
Licensed material--property of copyright holder(s) 15
idl(4) DG/UX 5.4R3.00 idl(4)
syntax-message
The custom error message to display if the syntax check
fails. If the value of this attribute is empty, the error
message is generated by idi from the prompt and the entered
value.
set Statement
The set statement causes the idl variable named name to take on the
value value. The value is available globally for the duration of the
program.
add Statement
The add statement causes the database object named name1 to be added
as a sub-object of the database object named name2.
The following rules apply:
a. Both names must be defined previously.
b. Any number of menus or operations may be added to a menu.
c. Any number of screens may be added to an operation.
d. Any number of querygroups may be added to a screen.
e. Any number of queries ( textquery, boolquery, selectquery, or
rangequery ) may be added to a querygroup.
f. Any number of texts may be added to a querygroup.
g. At most one textquery may be added to a selectquery.
export Statement
The export statement exports the idl variable named name (along with
the variable's value) into the environment of all sub-shells. This
is a function similar to the export command of the shell (sh(1)).
Compiler Directives
The following compiler directives can be used to alter the behavior
of the compiler or interpreter.
%dir name Interpret subsequent %include lines relative to name. Such
a line overrides any previous %dir directive.
%include name
Read the contents of the file name as if the contents were
present in the current file.
%print [ object ]
If object is given, print debugging information about
object. Otherwise, print information about all objects.
Licensed material--property of copyright holder(s) 16
idl(4) DG/UX 5.4R3.00 idl(4)
Variable Substitution
The action, assign-values, confirm, default, help, possible-values,
preserve, prompt, range, semantics, and syntax attributes are
processed so that idl variables may be used inside of the values for
these attributes.
Variable expansion may be indicated by any of these forms:
$var or ${var}
If var is set, substitute the value of var. Otherwise,
substitute an empty string.
$#var or ${#var}
Substitute the number of words found in the value of var.
Words are separated by whitespace.
${var:-val}
If var is set and non-null, substitute the value of var.
Otherwise, substitute val.
${var:+val}
If var is set and non-null, substitute val. Otherwise,
substitute an empty string.
${var:?val1:val2}
If var is set and non-null, substitute val1. Otherwise,
substitute val2.
${var:<prefix}
If var is set and non-null, substitute its value prefixed
by prefix. Otherwise, substitute an empty string.
${var:=text1:value1;text2:value2;textn:valuen}
Compare the value of var with each of the texts, and
substitute the value associated with the matching text. As
many text and value pairs as are required may be included.
An empty text may be specified to indicate a default case.
If var matches none of the texts, substitute an empty
string.
If the colon (:) is omitted from the above expressions, idi only
checks whether var is set or not.
In all cases, var must be a sequence of alphanumeric characters and
underscores, optionally followed by an index specification of the
form
name[index]
where the index is used to select only some of the words or lines
from the value of name. If the index begins with =, the index-th
line is substituted; otherwise, the index-th word is substituted.
Words are separated by one or more whitespace characters. The index
is subjected to variable substitution and may consist of a single
Licensed material--property of copyright holder(s) 17
idl(4) DG/UX 5.4R3.00 idl(4)
number or two numbers separated by a -. The first word or line of a
variable's value is numbered 1. If the first number of a range is
omitted, it defaults to 1. If the last member of a range is omitted,
it defaults to $#name. The index * selects all words or lines.
If a val or prefix contains any of colon (:), semi-colon (;), or
right brace (}), the character must be preceded by a backslash (\) to
escape its special meaning.
Any variables found within double quotes (") are expanded. All
characters between back quotes (`) are expanded and passed to the
shell (sh(1)) for execution, and the result of the shell execution is
inserted in place of the back-quoted string. A backslash (\)
preceding either $ or ` causes the character to lose its special
meaning.
The value or text part of any of the above expressions may contain
other variable references.
Pre-defined Variables
The following variables are used internally by idi(1) and should not
be changed. These variables should be used in place of the strings
they represent (for example, always use "${YES}" instead of "yes").
YES This is defined to be the affirmative string, yes.
NO This is defined to be the negative string, no.
HORIZONTAL
This is defined to be horizontal. This may be used as the
value for the orientation attribute of querygroups.
VERTICAL This is defined to be vertical. This may be used as the
value for the orientation attribute of querygroups.
NODEFAULT
This is defined to be [ No default ]. This may be used as
the value for the default attribute of selectqueries. When
this is used, the interface driver will leave the default
for the selectquery empty if possible.
SKILLLEVELS
This is defined to be the list of possible skill levels:
Novice Intermediate Expert. Note that this variable's
value varies based on the current locale.
RETRY This is defined to be retry. This may be used when setting
the error policy with the :Target builtin command.
ABORT This is defined to be abort. This may be used when setting
the error policy with the :Target builtin command.
CONTINUE This is defined to be continue. This may be used when
setting the error policy with the :Target builtin command.
Licensed material--property of copyright holder(s) 18
idl(4) DG/UX 5.4R3.00 idl(4)
DGRUNNINGTRUSTED
This is set to ${YES} if any of the DGRUNNINGWITH feature
below are enabled.
DGRUNNINGWITHAA
This is set to ${YES} if the system is configured for
Trusted DG/UX Authentication and Authorization.
DGRUNNINGWITHACL
This is set to ${YES} if the system is configured for
Trusted DG/UX Access Control Lists.
DGRUNNINGWITHAUDIT
This is set to ${YES} if the system is configured for
Trusted DG/UX Auditing.
DGRUNNINGWITHCAP
This is set to ${YES} if the system is configured for
Trusted DG/UX Least Capability.
DGRUNNINGWITHMAC
This is set to ${YES} if the system is configured for
Trusted DG/UX Mandatory Access Control.
The following global variables are set by idi at run-time:
Argc The number of arguments passed to the idi process.
Argv The argument vector passed to the idi process. The first
item of the vector is referenced as $Argv[ 1 ].
Batch The current value for the flag indicating whether
operations should be performed in a batch mode. This is
set through the :Target builtin command.
ErrorPolicy
The current error policy for remote management, as
specified as an argument to the :Target builtin command.
InterfaceName
The name of the chosen interface. This will be either
ascii or motif. This is the only means for changing the
behavior of the program based on the chosen interface.
LeadTarget
The name of the target selected by idi as the lead target
for remote operations.
Locale The locale string returned from setlocale(3C).
OperationName
The value of the name attribute of the current operation.
This may be used to generalize query prompts:
Licensed material--property of copyright holder(s) 19
idl(4) DG/UX 5.4R3.00 idl(4)
prompt = "Host Name to ${OperationName}"
Role The current role, or the empty string if the user has not
assumed a role.
Targets The comma-separated list of current targets.
Timeout The current timeout value for remote procedure calls, in
seconds.
The following global variables may be set by the idl programmer:
SkillLevel
The chosen level of expertise. This must be one of the values
from the ${SKILL_LEVELS} variable. The default is
Intermediate.
TitlePrefix
The string which precedes the actual title of windows and
screens. The default is the empty string.
TitleSuffix
The string which follows the actual title of windows and
screens. The default is the empty string.
Builtin Commands
Several builtin commands are provided for use in values for the
action, semantics, and syntax attributes. The builtin commands are
the following:
:Confirm [ default ] confirmation-string
Present the confirmation-string to the user using the
appropriate interface driver. Return zero if the string is
confirmed; return non-zero if it is not confirmed. The
default, if used, must be either ${YES} or ${NO}.
:DoOp operation-name [ confirmation-string ]
Perform the operation-name operation. If the confirmation-
string is used, ask for confirmation before the operation
is performed. If the confirmation fails, exit with status
0; otherwise, exit with the exit status of the operation.
:Echo message
Echo the message to the display.
:Error message
Display the error message in a way appropriate for the
interface driver.
:Help help-text
Present a help message to the user. The help-text is a
text object containing the text of the help message.
Licensed material--property of copyright holder(s) 20
idl(4) DG/UX 5.4R3.00 idl(4)
:Log message
Append the message to the log file. The message is written
regardless of the verbosity level chosen by the user.
:Match regexp string
Return zero if the string matches the given egrep(1)-style
regular expression, regexp; otherwise, return non-zero.
This command is useful in the syntax attribute of queries.
:Numeric lower-bound upper-bound value
Return zero if the integer value given is within the range
specified by lower-bound and upper-bound. This command is
useful in the syntax attribute of queries.
:Quit exit-code
Terminate the program with exit-code as the status code.
:Restart [ command-line ]
Restart the interface driver, optionally using the supplied
command-line. If the command-line is not given, the
current command line is used. This operation may be used
to take into account new or changed description files.
:Run command
Execute an interactive command on the host system. The
standard input, output, and error file descriptors are set
appropriately.
:Set variable value
Set the global variable to value. The variable is then
available for use by other queries. The variable is
created if it does not exist, or modified if it does exist.
:Show Dump the values of all variables to stdout. This is useful
for debugging.
:Target hosts policy timeout batch
Set the remote execution environment. The hosts is a list
of comma-separated host names on which subsequent actions
should be performed. The policy is the method to use when
an operation action cannot be performed on a target; the
value must be one of ${RETRY}, ${ABORT}, or ${CONTINUE}.
The timeout is the time, in seconds, to wait before
concluding that a host cannot be reached. The batch
parameter is a boolean indication of whether commands
should be scheduled in the background for later execution.
:Unimp message
Display a message indicating that some feature is
unimplemented. message should describe the feature not
implemented.
:Unset variable
Remove the global variable and its value. This command
Licensed material--property of copyright holder(s) 21
idl(4) DG/UX 5.4R3.00 idl(4)
should only be used for variables which are set using the
:Set builtin command.
:Warning message
Display the warning message in a way appropriate for the
interface driver.
EXAMPLES
Below is a sample idl file which creates a single menu with several
operations which could be used to manage the /etc/ethers database
file.
##################################################################
#
# Some patterns used here
#
##################################################################
set STDHOSTNAMEPATTERN = "^[a-zA-Z][-.a-zA-Z0-9]*\$"
set STDHOSTNAMEHELP =
"Enter an Internet host name. A host name may contain the characters:
a-z A-Z 0-9 . -
It should begin with a letter (a-z or A-Z) and be no more
than 32 characters in length. It should not contain a . or -
as the last character."
set STDETHERADDRESSPATTERN =
"^[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+\$"
set STDETHERADDRESSHELP =
"Enter an Ethernet address. An Ethernet address has the form:
aa:bb:cc:dd:ee:ff
where a, b, c, d, e, f are two-digit hexadecimal numbers 00 and ff.
The numbers are separated by colons. You must enter all 17 characters."
set dgEthersFile = "/etc/ethers"
##################################################################
#
# Main menu
#
##################################################################
menu main
name = "Main"
title = "Main Menu"
description = "Top level menu"
help =
"This is the first level menu. It contains a sub-menu for
manipulating the ethers database."
end
##################################################################
Licensed material--property of copyright holder(s) 22
idl(4) DG/UX 5.4R3.00 idl(4)
#
# Ether menu
#
##################################################################
menu dgEther
name = "Ether"
mnemonic = E
title = "Ethers Menu"
description = "Manipulate the ethers databases"
help =
"This menu provides access to the ethers databases. There are
operations for adding, deleting, modifying, and listing entries
from the database."
end
##################################################################
#
# Operations
#
##################################################################
operation dgEtherAdd
name = Add
mnemonic = A
action = "admether -o add -a ${NetAddress}
description = "Add an entry to the ethers database"
help =
"The Add operation takes a host name and an Ethernet address and adds
an entry to the ethers database."
exit-action = ":Unset DefaultString"
end
operation dgEtherDelete
name = Delete
mnemonic = D
action = "admether -odelete
description = "Delete entry from the ethers database"
confirm = "Delete ${HostName} from the ethers database?"
help =
"The Delete operation takes one or more host names and
deletes the corresponding entry or entries from the
ethers database."
end
operation dgEtherModify
name = Modify
mnemonic = M
action =
"admether -o modify -n ${NewHostName} -a ${NetAddress}
description = "Modify an entry in the ethers database"
help =
"The Modify operation takes a host name and allows the user to modify
the corresponding entry in the ethers file.
Licensed material--property of copyright holder(s) 23
idl(4) DG/UX 5.4R3.00 idl(4)
The user may modify the host name and the Ethernet address."
exit-action = ":Unset DefaultString"
end
operation dgEtherList
name = List
mnemonic = L
action = "admether -o list"
description = "List entries from the ethers database"
help =
"The List operation displays the contents of the ethers database
for one or more hosts."
end
##################################################################
#
# Screens, querygroups, and queries
#
##################################################################
screen dgAddEtherScreen
title = "Add an Ethers Entry"
entry-action = ":Set DefaultString 00:00:00:00:00:00 NewName"
end
#
# This querygroup and its queries are used for entering a
# new ether entry. The defaults are stored in the DefaultString
# variable, and should be set by the screen.
#
querygroup dgNewEtherEntryQG
end
textquery dgHostNameText
prompt = "Host Name"
variable = HostName
syntax = ":Match ${STDHOSTNAMEPATTERN} ${HostName}"
help = "${STDHOSTNAMEHELP}
This is the name of the host as it should appear in the
ethers database."
#
# Do different checks based on whether we're adding or
# listing.
#
semantics = "${OperationName=Add:test -z '`grep ${HostName} ${dgEthersFile}`';\
:test -n '`grep ${HostName} ${dgEthersFile}`'}"
default = "${DefaultString[2]}"
end
textquery dgEthernetText
prompt = "Ethernet address"
variable = NetAddress
Licensed material--property of copyright holder(s) 24
idl(4) DG/UX 5.4R3.00 idl(4)
syntax = ":Match ${STDETHERADDRESSPATTERN} ${NetAddress}"
help = "${STDETHERADDRESSHELP}
This is the Ethernet address of the host as it should appear
in the ethers database."
default = "${DefaultString[1]}"
end
#
# This screen, querygroup, and query are shared between Delete
# and List, because both operations need to choose one or more
# existing host names.
#
screen dgHostNameListScreen
title = "${OperationName} Ethers Entry(ies)"
end
querygroup dgHostNameListQG
end
selectquery dgHostName
prompt = "Host Name(s)"
possible-values = "all
`admether -o list -q | cut -f2 -d' '`"
exclusive = "$NO"
variable = HostName
default = "${NODEFAULT}"
help = "
This is the name of the host(s) to ${OperationName}."
end
#
# This screen and its queries are used for getting a single
# existing entry which will be modified.
#
screen dgModifyEtherScreen1
title = "Modify an Ethers Entry"
end
querygroup dgModifyEtherQG1
end
screen dgModifyEtherScreen2
title = "Modify an Ethers Entry"
entry-action = ":Set DefaultString `admether -o list -q ${HostName}`"
end
selectquery dgOldHostName
prompt = "Old Host Name"
possible-values = "`admether -o list -q | cut -f2 -d' '`"
exclusive = "$YES"
variable = HostName
Licensed material--property of copyright holder(s) 25
idl(4) DG/UX 5.4R3.00 idl(4)
help = "
This is the name of the host whose database entry is to
be modified."
end
add dgEther to main
add dgEtherAdd to dgEther
add dgAddEtherScreen to dgEtherAdd
add dgNewEtherEntryQG to dgAddEtherScreen
add dgHostNameText to dgNewEtherEntryQG
add dgEthernetText to dgNewEtherEntryQG
add dgEtherDelete to dgEther
add dgHostNameListScreen to dgEtherDelete
add dgHostNameListQG to dgHostNameListScreen
add dgHostName to dgHostNameListQG
add dgEtherModify to dgEther
add dgModifyEtherScreen1 to dgEtherModify
add dgModifyEtherQG1 to dgModifyEtherScreen1
add dgOldHostName to dgModifyEtherQG1
add dgModifyEtherScreen2 to dgEtherModify
add dgNewEtherEntryQG to dgModifyEtherScreen2
add dgEtherList to dgEther
add dgHostNameListScreen to dgEtherList
SEE ALSO
ed(1), egrep(1), idi(1), idc(1), sh(1), dgrunningwith(3C).
Licensed material--property of copyright holder(s) 26