SCIENCE AND ENGINEERING RESEARCH COUNCIL AON/4.8
ROYAL OBSERVATORY EDINBURGH
and UNIVERSITY OF EDINBURGH
ADAM Project Issued by
ADAM Observer Note 4.8
J A Cooke
25 January 1989
----------------------------------------------------------------------
Using the ADAM Screen Management System
---------------------------------------
The Screen Management System (SMS) is a user interface for ADAM. This
document describes SMS in outline, how to use it, and how to write the
control tables which configure it.
Intended readership: observers; programmers writing SMS control
tables
This document has been revised for SMS version 1.2.
Contents page
Recent enhancements 2
1. Introduction 3
2. An outline of SMS 3
3. How to use SMS 5
4. How to write control tables for SMS 9
5. Stand-alone table compiler 11
6. Features of the system which may change 11
Appendices
A: Specification of the control table entry types 12
B: An example control table 27
- 1 -
AON/4.8 Page 2
RECENT ENHANCEMENTS
Enhancements to SMS made in 1988 to date are:
o The CLI prompt is now configurable using "cli_prompt"
o Prompts and "information" output are now logged
o The stand-alone table compiler now produces formatted
printouts of menus and parameter lists which provide
hardcopy for previews or documentation.
o Inline editing of parameter list items has been added
o An "expert user" facility has been added
o SMS may now be configured to provide one-line help
automatically as the cursor is moved around menu items
or parameter list entries
o Bugs in the routine which handles SMS parameter
substitution causing integer overflow errors have been
fixed; errors in parameter substitution are now reported.
o The internal mechanism for SMS system configuration
changes made using the keypad "COMMA" key facility has
been changed. To make use of this facility, new
"+config+" entries are needed in the system part of the
control table. See the example in Appendix B.
o Equivalences have been set up for those using SMS on a
VT220 terminal as follows (by JHF@JACH):
VT100 key VT220 key
ENTER NEXT_SCREEN
PF1 DO
PF2 INSERT_HERE
PF3 FIND
PF4 PREV_SCREEN
keypad "." key SELECT
"?" key HELP
"ctrl-U" REMOVE
o Help entries can include the help file name (by JHF@JACH).
o Continuation lines can be used within action entries.
o A file "include" facility has been added.
- 2 -
AON/4.8 Page 3
1 INTRODUCTION
SMS is a part of the ADAM system. It is one of the user interfaces on
the system, and is intended to be a general purpose user interface.
It is general purpose because the same program (SMS) can be configured
to give different views of the ADAM system to the user at a terminal.
For example, there could be an SMS configuration set up for one
particular instrument. Note that SMS was originally designed for
VT100 or VT100 compatible terminals, but is now implemented on top of
the DEC screen management facility.
SMS can be used for instrument control, data acquisition and data
analysis. In the ADAM system these functions are accomplished in the
command language (e.g. ADAMCL) by issuing commands. SMS can be used
to package these commands in more complex ways than is possible in
command language procedures, so that, for example, by selecting a
single menu item from several displayed on the screen, a particular
set of command language commands would be issued.
2 AN OUTLINE OF SMS
SMS provides a menu-driven control system which has a user-defined
structure; it can be set up to be hierarchical but this is not
essential. The structure is defined in a "control table". Menu
entries may select other menus, or parameter lists, or actions. Menus
and parameter lists are "pasted" on the terminal screen, with the most
recently used item on top. The layout is determined by the SMS
control table, so these may or may not overlap.
SMS is mostly single keystroke driven; for example, the arrow keys to
move the cursor, or the keypad keys for a whole range of functions.
Note in particular the use of the "PF" keys of the VT100 terminal; the
current function of these keys is always shown in status fields at the
bottom of the screen (in the default control table).
The user can be prompted for information as a result of some SMS
operations or in response to requests from tasks. During prompting,
the "current position" of the cursor on a menu or parameter list
display is marked by a reversed video block. This enables the user to
see where he has got to in the menu or parameter list.
2.1 Definitions
A "menu" is simply a list of items which are displayed on the screen
in any rectangular format, with or without a box drawn around them.
The screen cursor points at menu items; by using the "arrow" keys on
the terminal the cursor can be made to jump around the menu items.
Pressing the "ENTER" key selects a menu item; pressing the "PF1" key
- 3 -
AON/4.8 Page 4
escapes from the menu.
A "parameter list" has one or more parameter entries whose values may
be set either to one of a set of predefined constants or to a single
typed value as required.
An "action" can be one or many command language commands; the actual
commands are defined in the SMS control table being used. Values from
parameter list entries may be substituted in the command language
commands before they are executed.
Both menus and parameter lists can have actions set up which will be
executed on entry or on exit, so that, for example, after SMS
parameters have been set up in a parameter list the appropriate
command language commands can be executed to change the state of an
instrument according to the parameter values selected. On pressing
"PF1" to exit, these actions are executed; on pressing "PF4", the menu
or parameter list is left but the actions are not executed.
2.2 Macros
SMS is a macro system; in fact, a "keystroke" macro system, something
like a programmable calculator. At any time the system can be asked
to "learn" a macro as a set of keystrokes; this macro can then be
assigned to one of the keypad numeric keys. The macro can then be
"called" at any time by pressing the appropriate keypad key. This
allows, for example, a particular place in the SMS menu tree to be
"remembered" as a macro keystroke, and subsequently returned to at any
time by pressing the correct keypad key. It also allows a whole
instrument configuration to be "remembered" as a macro and re-used on
the following night. (Macro definitions can, of course, be stored in
files). Note that macros can be called from within other macros, but
users defining macros should be careful about possible recursion.
For some applications, macros may be unnecessary and the possibility
of using them inappropriate. The macro function of SMS can be turned
off by an entry in the control table.
2.3 Online Help
SMS uses the ADAM "help" system. At any time help may be requested by
typing the "?" key. The help given is controlled from entries in the
control table for each menu item and each SMS parameter, and two
levels of help information may be accessed as required. This help
information is extracted from the ADAM help structure. More detailed
help on the use of SMS itself may be obtained by pressing the keypad
"-" key, unless this help information has been removed or replaced by
the person who constructed the control table being used.
- 4 -
AON/4.8 Page 5
It is possible to configure SMS to give "one-line" help automatically,
through an entry in the system part of the control table. This
facility can also be turned on or off whilst SMS is running through
the configuration menu (see 2.5).
2.4 Direct Command Language Commands
SMS allows single command language commands to be issued at any time
by pressing the keypad "." key; this gives a prompt for the command.
This of course may also allow access to DCL commands through the
command language. Commands prefixed by "$" are sent to DCL for
interpretation.
2.5 SMS System Configuration
SMS allows some interactive configuration of its behaviour by pressing
the keypad "," key; this enters a parameter list which allows the SMS
"beep" to be turned on and off, allows the automatic one-line help
facility to be turned on or off, allows the SMS "scroll region" to be
made temporary or permanent (in which case it is not erased on new
keyboard input), and also allows redirection of scroll region output
to other terminals (this feature is disabled at present; redirected
output will not be displayed). The current ADAM help file may also be
selected here (but note that "exit" and not "quit" must be used to set
it up).
3 HOW TO USE SMS
The bare essentials needed to run SMS are:
- a VT100 compatible terminal to run it on (or a terminal
set up with appropriate features specified in an SMG
'TERMTABLE'
- SMS itself on a full or partial ADAM system
- a "control table", pointed to by the logical name "SMSTABLE"
- an associated ADAM help file (which is an HDS structure),
pointed to by the logical name "ADAM_HELPFILE"
The logical names must be set up before starting up. SMS is started
by typing the ADAM-defined symbol "SMS" in response to the VAX DCL
prompt:
$ ADAMSTART
- 5 -
AON/4.8 Page 6
$ SMS
This starts up the system, displays the "welcome" page, and then
compiles the control table. Once the table is compiled (large tables
take several seconds) the top level (or root) menu of the table is
displayed on the terminal screen.
You are now ready to start using SMS. The terminal cursor will be
positioned on the first item in the top-level menu. By positioning
the cursor using the terminal's "arrow" keys, you can point at the
various items in the SMS displays; by using the terminal's keypad you
can execute functions of the SMS system. Most of the time, ordinary
alphanumeric keys have no effect on the system, apart from simply
counting as a keystroke; any keystroke which is not recognised can be
made to sound the terminal bell (or, more usually, beep); this is
normally the default setting.
3.1 Obtaining Online Help
Help information must be provided along with the control table by the
author of the control table in use. Normally, there is existing help
available about how to use SMS, obtained by pressing the "MINUS" key,
but help for any application must be written and set up in an ADAM
help file. "One-line" help information on the item indicated by the
cursor is given if the "?" key is pressed; if this key is pressed
again, any "full" help information is written into the screen
scrolling region.
"One-line" help is given for EVERY menu or parameter list entry
automatically if the automatic help feature is enabled. This feature
is disabled by default; it may be enabled or disabled explicitly in
the "fields" entry of the control table, and may also be enabled or
disabled whilst SMS is running (section 2.5). The help line is
removed by pressing keys other than the "arrow" keys and the
entry/exit control keys; this is simply a feature of SMS.
3.2 The Terminal Keypad
The VT100 keypad contains the following: four "programmable function"
or "PF" keys; ten digit keys; an "ENTER" key; and three punctuation
keys, "MINUS", "COMMA" and "DOT". The use of these keys in SMS is as
follows:
3.2.1 The ENTER Key - The ENTER key is used to select a menu item.
In a menu display, the cursor will be lying on one of the menu items;
pressing ENTER will cause one of three things to happen. If the menu
- 6 -
AON/4.8 Page 7
item points to another menu, then this new menu will be displayed. If
the menu item points to a parameter list, then this parameter list
will be displayed. If the menu item corresponds to an SMS action,
then this action (a series of command language commands) will be
executed. In each case, the menu item will be highlighted until
either exit from the new display or termination of the action.
3.2.2 The PF Keys - The function of these keys varies, but is always
indicated on the screen (at the bottom of the screen, by default).
3.2.3 The DOT Key - Pressing the DOT key makes SMS give the command
language prompt which allows any single command language command to be
given.
3.2.4 The COMMA Key - allows the user to configure some SMS system
parameters, described in 2.5.
3.2.5 The MINUS Key - Pressing the MINUS key normally enters a help
menu which gives help on the SMS system. This should be self
explanatory. Press "exit" (PF1) to leave this menu, as "quit" (PF4)
will not restore the help file needed for the control table in use.
Note that the author of the control table in use may have supplied an
alternative to the default SMS help menu.
3.2.6 The Digit Keys - These keys are used to run pre-defined macros.
See 2.2, "Macros".
3.3 Refreshing The Screen
The SMS screen display may be refreshed at any time (e.g. after a
system broadcast message) by pressing "ctrl-R".
3.4 Parameter Lists
If you enter a parameter list, then the parameters there are set in
one of two ways. If the control table specifies a set of possible
values for the parameter, then the value required is selected simply
- 7 -
AON/4.8 Page 8
by using the "arrow" keys: up or down to select the parameter, left
or right to select a particular value. If the control table specifies
just one value, then this value may be altered as follows: "LF"
(ctrl-J) or "ctrl-U" will delete the current value, characters typed
will appear at the cursor position, and the "DEL" key allows the
character to the left of the cursor to be deleted. The left and right
"arrow" keys may be used to perform "in-line" editing, with
insert/overstrike modes toggled using "ctrl-A".
The parameter values given in the parameter list may be set up by a
mechanism which interrogates named tasks for the values of named
parameters or from a command language variable; for examples of this
see the "switch" field specification in Appendix A. The syntax is
simply to specify "from taskname parametername" or "from adamcl
variablename" on the line following the parameter definition in the
list.
3.5 Control-C Behaviour
Pressing "control-C" on the keyboard can be used to interrupt the user
interface. The effects of this are as follows:
Macros: the macro is aborted at the present point; the screen display
is not changed
Parameter requests: this is equivalent to "!!" (cancel)
The command language is also interrupted, and will interrupt command
language procedures
The message "Cancel" is echoed on the terminal screen; this can be
removed by typing "ctrl-R" ("refresh").
3.6 Expert User Facility
WARNING: control tables intended for use with this facility must be
designed very carefully!
It is possible to configure SMS to enable an "expert" user who knows
the control table names for menus and parameter lists used internally
by SMS to "jump" to a named menu or parameter list. This is done by
pressing the DOT key (section 2.4) and using the escape character "@"
to prefix a menu or parameter list name. SMS will then paste up the
named menu or parameter list, just as a normal entry to such.
Pressing "exit" will unpaste the new display and return to where SMS
was before; stacking operates as normal. A well-designed control
table should not normally need to use this feature, but it may be
useful to an expert using a particularly complicated system. This
- 8 -
AON/4.8 Page 9
facility is disabled by default; it may be enabled or disabled
explicitly in the "fields" section of the control table.
4 HOW TO WRITE CONTROL TABLES FOR SMS
The format of menus displayed on the screen, the switchable parameters
used in SMS, the ADAM commands sent by SMS, and the definition of the
function of parts of the screen are all defined in an ASCII text file
called the "control table". This file is read by SMS at run-time and
compiled into an internal, quickly accessed form. (It will be
possible eventually to save the compiled form of the table so that SMS
will start up faster.)
To create a control table you use a text editor. The best plan is to
take the useful parts from an existing table to save re-typing them.
The control table syntax is fairly straightforward but it is best to
look at an example to see what a control table looks like; for
example, the table in appendix B.
At present all the SMS configuration is in one control table. It is
likely that in some future release the first part of the configuration
will be removed to a separate control table, as the first part relates
to the screen positions of essential parts of the SMS system, such as
the position of the text describing the "PF" key functions. The rest
of the configuration relates to the menus, parameter lists and actions
for a particular application.
Thus there are currently four types of entry in a control table.
These are introduced by the following keywords:
fields - the definitions for the location of SMS system
information on the screen. There will only be
one "fields" entry.
menu - a menu definition entry
switch - a "parameter list" entry
action - an entry with containing one or more
command language commands
These keywords MUST be in lower case starting in the first character
position on the line.
Comments may appear in the control table, identified by "*" in the
leftmost character position.
Items on the lines in the table may be separated by spaces or tabs or
both.
- 9 -
AON/4.8 Page 10
Lines in the table within an action entry may be continued with the
continuation character "-" in the usual DCL manner.
An "include file" facility is provided, so that sections of control
tables can be brought together from different sources. Include files
can be nested to a maximum depth of 16. The syntax is simply
include filespec
where the keyword "include" MUST be in lower case and MUST start in
column 1, as for the other keywords. Note that there are no quotes
around the file specification.
Detailed specifications of the types of table entry are given in
Appendix A.
There are internal limits set on the size of control tables, which can
only be changed by re-compiling SMS. These limits are:
maximum number of menus 200
maximum number of parameter lists 200
maximum number of actions 400
maximum number of list entries (names etc.) 1500
The table compiler has explicit checks for these limits being reached,
and reports when this occurs.
The table compiler also identifies references in the table to
undefined menus, actions or parameter lists, and outputs messages to
inform the user of these.
- 10 -
AON/4.8 Page 11
5 STAND-ALONE TABLE COMPILER
A stand-alone version of the table compiler is available, which allows
control tables to be compiled for checking purposes without running
SMS.
This produces listings of the data stored in the internal structures
of SMS, a listing of the control table (with error messages inserted,
if any!) and listings of the formats of menus and parameter lists
which give a "hard-copy" preview of what will appear on the screen.
Note that in the "action table" the lines are truncated in the listing
to 80 characters; these lines may in fact be up to 132 characters
long.
This is invoked by obeying the commands:
$ ADAMSTART ! Start up ADAM
$ ADAMDEV ! Define symbol COMPSCT
$ DEFINE SMSTABLE file_description ! Define control table
$ COMPSCT ! Run the compiler
Output from the compiler will be into a file in the user's current
directory with the same filename as the control table and filetype
.LIS.
6 FEATURES OF THE SYSTEM WHICH MAY CHANGE
Storing compiled tables so that start-up is quicker.
Saving the whole of a "current configuration".
- 11 -
APPENDIX A
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES
There are four types of entry in an SMS control table. One of these
describes the configuration of the SMS system components on the
screen, and will not usually be changed much from one application to
another. This entry is introduced by the keyword "fields", and is put
at the beginning of the control table file. (It is likely that at
some time in the future this entry in the table may be moved to
another file, since it is not part of the application.)
The other three entry types describe what appears on the screen when
running a particular application. They are introduced by the keywords
"menu", "switch" and "action". The "menu" and "switch" entries
describe displays which are pasted on the terminal screen when
required. The "switch" entry consists of a list of parameters which
can have switched or manually entered values; it is thus referred to
as a parameter list. The "action" entries consist of one or more
command language commands which can be executed as a consequence of
the user's keystrokes at the terminal. These "action" entries may be
called up in three ways:
- on entry to a menu or parameter list
from a higher level menu
- on exit from a menu or parameter list
back to a higher level menu
- by selecting a menu option which is explicitly
associated with a particular action
Mechanisms are provided to:
o Take the values of parameters from SMS parameter lists and
substitute them in command language command lines. This
allows communication of parameter values from SMS to the
command language.
o On entry to a parameter list from a menu, take the value of
any SMS parameter from the current value of a named
- 12 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-2
parameter in any ADAM task. This allows communication of
parameter values back from the ADAM system to SMS.
o On entry to a parameter list from a menu, take the value of
any SMS parameter from the current value of a named command
language variable. This allows communication of the values
of variables back from ADAMCL to SMS.
Names used within the table entries are allowed to be up to 60
characters long, with the exception of help keywords; these are of the
form helpname or @helpname or @helpfile.helpname where each of
helpfile and helpname can be up to 15 characters long (an HDS limit).
If the help keyword is not prefixed by @, then help information is
taken from the current ADAM help file, using the help keyword given in
the menu item or parameter entry. If this keyword cannot be located
in the current help file, then SMS will inform the user that no help
is available.
If the help keyword is of the form @helpname, then the current help
file is set to the default (the logical name SMS_HELPFILE) and
searched for helpname.
If the help keyword is of the form @helpfile.helpname, then the
current help file is set to helpfile and searched for helpname.
A detailed specification of the four entry types follows.
- 13 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-3
A.1 The "fields" entry.
This entry consists of a list of instructions which configure the SMS
_ _system. Some of these must be present, others have defaults and need
not be given.
A.1.1 Required entries:
pf<n> <line> <column>
specifies where on the screen the descriptive text for the keypad
"PF" keys appears; <n> takes the values 1 to 4, <line> and <column>
specify the screen position
pf_width <n>
<n> is the number of characters allowed for descriptive text in the
PF key display
scroll_top <n>
<n> is the top line on the screen to be allocated to a scrolling
region
scroll_bot <m>
<m> is the bottom line on the screen to be allocated to a scrolling
region
prompt_line <line>
<line> specifies the screen line where parameter prompts are to
appear
err_line <line>
<line> specifies the screen line where error messages are to appear
- 14 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-4
msg_line <line>
<line> specifies the screen line where one-line messages (e.g.
from the message system) are to appear
cmd_line <line>
<line> specifies the screen line where the command language prompt
is to appear
help_line <line>
<line> specifies the screen line where one-line help is to appear
A.1.2 Optional entries:
txt_<type> <text required>
These entries allow the default text for the PF key labels to be
over-ridden. If no entries are present, the internal default
values will be used. One or more of the defaults may be changed by
appropriate entries.
There are four sets of the PF key labels:
- the "base" set, used for menus
- the "switch" set, used for parameter lists
- the "macro definition" set; replaces the base set
when defining macros
- the "macro display" set, used for the macro display function
The names for these text entries (as used in SMS control tables)
and their default values are as follows:
txt_base_pf1 = PF1: exit
txt_base_pf2 = PF2: learn macro
txt_base_pf3 = PF3: show macros
txt_base_pf4 = PF4: quit
txt_swit_pf1 = PF1: exit
txt_swit_pf2 = PF2: defaults
txt_swit_pf3 = PF3:
txt_swit_pf4 = PF4: quit
- 15 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-5
txt_mdef_pf1 = PF1: exit
txt_mdef_pf2 = PF2: end macro
txt_mdef_pf3 = PF3: show macros
txt_mdef_pf4 = PF4: quit
txt_mdis_pf1 = PF1:
txt_mdis_pf2 = PF2:
txt_mdis_pf3 = PF3: load macro
txt_mdis_pf4 = PF4:
macros <enabled/disabled>
This entry enables the macro facility to be disabled. The entry
macros disabled
will disable the PF2 and PF3 keys (in a menu) and the keypad
numeric keys so that macros cannot be used. Macros can be enabled
explicitly by the entry
macros enabled
but this is also the system default, so no "macros" entry means
that macros will be enabled.
If use is made of this facility to disable macros, then the PF2 and
PF3 key labels for menus should also be altered, e.g. with entries
txt_base_pf2 PF2:
txt_base_pf3 PF3:
to leave these blank.
scroll_switch <on/off>
The SMS system sets up the scroll region as "permanent" by default,
i.e. it does not go away if the user presses a key when it is on
the screen. This can be changed in the SMS configuration parameter
list (accessed from the keypad "comma" key), to make the scroll
region "temporary", i.e. it is only displayed until the next
keystroke.
The system default can be over-ridden by this entry, e.g.
scroll_switch on
sets up SMS with the scroll fields "permanent" once text is written
to it. It can be set up to be "temporary" with "scroll_switch
- 16 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-6
off".
cli_prompt <prompt>
The SMS system sets up the command language prompt to be "Command:
" by default. This can be changed to reflect the actual command
language which SMS is linked with.
The system default can be over-ridden by this entry, e.g.
cli_prompt Adamcl:
sets up SMS with the command language prompt "Adamcl: ". Note
that this used to be the default.
show_task <on/off>
determines whether the task name is displayed along with incoming
messages. This is "off" by default, so that only the value part of
an incoming message is displayed.
auto_help <on/off>
This sets up the initial state of the automatic one-line help
facility, which is disabled by default. This can be changed in the
SMS configuration parameter list (accessed from the keypad "comma"
key).
expert_user <on/off>
See section 3.6. This enables or disables the expert user facility
(on to enable, off to disable).
A.1.3 An example of the "fields" entry:
fields
* definition of field locations ...
* keypad "pf" keys ...
* (specifies where on the screen the descriptive text appears)
* i.e. <key> <line> <column>
- 17 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-7
pf1 24 1
pf2 24 21
pf3 24 41
pf4 24 61
* no of characters allowed for descriptive text
pf_width 19
* pf key text replacement ...
txt_base_pf1 PF1: go back one
txt_base_pf4 PF4: go away entirely
txt_swit_pf3 PF3: no function
* scroll field ...
scroll_top 5
scroll_bot 15
scroll_switch on
* parameter prompt field ...
prompt_line 19
* error message line ...
err_line 20
* one-line message display ...
msg_line 21
* prompted command field ...
cmd_line 22
cli_prompt ICL:
* one-line help ...
help_line 23
* macro operation ...
macros disabled
* "expert user" facility ...
expert_user off
- 18 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-8
A.2 The "menu" entry.
The "menu" entry is introduced by
menu <name> <title if any>
where <name> is the name of the menu to be referenced in the "option"
entries of other menus in the control table. The title, if given, is
displayed at the top left border of the menu.
A.2.1 Required entries:
format <box/nobox>
determines whether or not a box is drawn around the menu
position <line> <column>
gives the position of the top left corner of the menu on the screen
(N.B. the box goes OUTSIDE this if present)
field_width <number of characters>
gives the width of the field for each menu item
columns <number of columns in the menu>
note the number of columns could be one, giving a tall thin menu!
option <option name> <action/menu/switch> <name> <help key>
There must be at least one "option" entry; these are the "items" in
the menu. They can point to actions, parameter lists, or other
menus.
<option name> appears on the screen as the menu item
"action", "menu" or "switch" specifies the entry type
<name> specifies which action, menu or parameter list is selected
- 19 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-9
<help key> specifies the help keyword to be used in the current
help file when the user requests help by pressing "?" with the
cursor on this menu entry
A.2.2 Optional entries:
entry <action name for action on entry>
allows one or more command language commands (specified in the
given "action" entry) to be obeyed on entry to an SMS menu.
exit <action name for action on exit>
allows one or more command language commands (specified in the
given "action" entry) to be obeyed on exit from an SMS menu.
pre_entry <action name for action before entry>
pre_exit <action name for action before exit>
In ADAMCL, these entries are like "entry" and "exit", but allow the
control of access to menus and parameter lists by using command
language variables as flags. The control variables are called
"ENTER_SCREEN" and "EXIT_SCREEN"; they are "real" ADAMCL variables.
For normal entry or exit, they are set to 1.0; to bar entry or
exit, set the required variable to 0 in the appropriate "pre_entry"
or "pre_exit" action.
Note that, in parameter lists, the "from" mechanism for setting SMS
parameters from external values is called before the "pre_entry"
action, and thus is called even if entry to the display is barred.
This may well be the required action in many cases.
A.2.3 An example of the "menu" entry
menu main_node This is the title
* whether or not a box is drawn around the menu ...
format box
* position of top left corner of the menu on the screen ...
position 5 10
* width of field on screen of each menu item ...
field_width 10
- 20 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-10
* the number of columns could be one, giving a tall thin menu!
columns 4
* the next four need not be present ...
pre_entry check_permit
entry setup1
pre_exit check_exit
exit save1
* the menu items which can point to actions, parameter
* lists, or other menus ...
option observe action do_it obs_help
option ... and so on ...
- 21 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-11
A.3 The "switch" entry.
The "switch" entry is introduced by
switch <name> <title if any>
where <name> is the name of the parameter list to be referenced in the
"option" entries of menus in the control table. The title, if given,
is displayed at the top left border of the parameter list.
A.3.1 Required entries:
position <line> <column>
gives the position of the top left corner of the parameter list on
the screen
field_width <number of characters>
gives the width of the field to hold the parameter name
parameter <parameter name> <help key> [<default>] <another> <next>
a "switched value" parameter (default indicated by [ ]);
<parameter name> appears on the screen as the list item name,
<help-key> is the help keyword for the parameter,
the 'default' value has square braces around it,
<another> and <next> are other possible 'switched' values for the
parameter
parameter <parameter name> <help key> <single value>
A "single valued" parameter; the value is a string with no white
space included. If data is typed for a parameter list
single-valued entry such that the data typed would go beyond the
rhs of the pasted display, then the data typed is stored, and on
exit from the display its width is updated so that on next entry it
will be wider and will show what was typed. At present,
"shrinking" of the display if smaller length items are typed is not
implemented ! (It's a bit more difficult, though not much)
- 22 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-12
There must be at least one 'parameter' entry, which can be of
either type.
- 23 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-13
A.3.2 Optional entries:
from <task> <parameter>
After a parameter list parameter definition, the "from" entry can
be used to set the parameter value from the value of a parameter in
an external task, e.g.
parameter myparm help_key 0 [1] 2 3
from <task_name> <parameter_name>
from adamcl <variable_name>
will pick up the value of any command language variable as a
character string. In fact, <variable_name> can be any valid
command language expression (provided it does not include "white
space", i.e. spaces or tabs).
maxchars <parameter_value_length>
The SMS system maximum for name lengths (and parameter value
lengths) is set up at 60 characters (changing this needs a system
recompile). Additionally, the maximum length of individual
parameter values can be specified by this 'maxchars' mechanism.
After the parameter entry in the table, a line is added which
specifies the maximum value length the user can type (this applies,
of course, only to single-valued parameters), e.g.
parameter object_name help_key The_Moon
maxchars 25
sets up a parameter with initial value "The_Moon" and will not
allow the user to change this value to anything longer than 25
characters. If a "maxchars" entry is not present, then the
parameter value will be allowed to "grow" to the system maximum
(i.e. 60 at present).
entry <action name>
exit <action name>
- 24 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-14
pre_entry <action name>
pre_exit <action name>
These behave in an identical way to the corresponding entries for
menus.
A.3.3 An example of the "switch" entry:
switch sw_1 Title on screen
* this is a "parameter list"
* position on the screen ...
position 10 10
* width of field to hold parameter name ...
field_width 15
* parameters: note that "help-key" is the help keyword for that
* parameter; it may, of course, be the same as the parameter
* name.
*
* a "switched value" parameter (default indicated by [ ] at
* present)
parameter <parameter name> <help key> [<default>] <another> <next>
* a "single valued" parameter with size limit ...
parameter heading head_help Observation
maxchars 32
* this next parameter gets its value from a named task ...
parameter ...
from mytask filter_name
* this next parameter gets its value from the command language ...
parameter ...
from adamcl myvariable
* note these next two are not present if not required ...
* if any action is to be called on entry to this field
entry enter_sw1
* and if any action to be called on exit
exit exit_allsw
- 25 -
SPECIFICATION OF THE CONTROL TABLE ENTRY TYPES Page A-15
A.4 The "action" entry.
An action entry is introduced by
action <name>
where <name> is the name used inside the SMS control table to refer to
this action from a menu item or in 'entry' and 'exit' directives.
This is followed by a list of command language command lines, which
SMS sends to the command language for execution. This is basically
what SMS is: a means of packaging command language commands so that
they can be executed by a single keystroke rather than by having to
type them all in. Note that DCL commands can be placed here, just as
at the "DOT key" prompt, if the underlying command language supports
the "$" escape.
There is a special escape pattern, "+config+", which when used as the
first word in an action line attempts to configure an internal SMS
parameter. This should normally only be used in the exit action of
the SMS system configuration parameter list (see the example in
Appendix B). This pattern must not be used as the first word on the
line for any other action lines.
A.4.1 An example of the "action" entry:
action doit
* an action definition may contain one or more command language
* commands:
load atasks:junktask junk
send junk obey something
etc ...
* and SMS parameter substitution is done to allow variables in
* these ADAMCL lines as follows ...
send junk set something <<switch_name:parameter_name>>
* where "switch name" is the name of a parameter list,
* and "parameter name" is the name of a parameter in that
* list. The characters held in SMS representing the current
* value of the parameter are simply substituted in the ADAMCL
* command line.
- 26 -
APPENDIX B
EXAMPLE OF A CONTROL TABLE
What follows is a simple example of a control table for SMS. It can
be edited out and used as a base from which to experiment! The basic
structure of this example is
"home_menu"
|
+---------------+-----------------+
| |
a_menu a_param_list
"some_actions" parameters:
| choice_letter
+-------+-+---------+ choice_number
| | | choice_value
hi_there choices directory
Actions:
hi_there - print "Hi there"
choices - print choices in 'a_parm_list'
directory - do DCL "directory" command
Note that there is an include file containing directives needed for
SMS system operation.
.page
* Example control table to go with the document AON004.
*
* John Cooke (REVAD::JAC) 30Sep88
* include the system part of the table ...
include smssystab.inc
* This is where the "application part" of the control table
* starts. The first menu becomes the SMS "top level" menu,
- 27 -
EXAMPLE OF A CONTROL TABLE Page B-2
* i.e. the one displayed first on the screen ...
menu home home_menu
position 2 2
field_width 15
columns 2
format box
option a_menu menu action_menu action_help
option a_param_list switch a_parm_list param_help
* entry action to set up the help file ...
entry start_action
action start_action
help @aon004
menu action_menu some_actions
position 8 2
field_width 15
columns 1
format box
option hi_there action hi_there hi_there
option choices action choices choices
option directory action directory directory
switch a_parm_list
position 9 12
field_width 15
parameter choice_letter help_letter A [B] C D E F
parameter choice_number help_number 1 2 3 [5] 7 11 1986
parameter choice_value help_value 42.0
* Actions:
action hi_there
print "Hi there"
action choices
print "Letter: <<a_parm_list:choice_letter>>"
print "Number: <<a_parm_list:choice_number>>"
print "Value: <<a_parm_list:choice_value>>"
action directory
$directory
.page
This next section is the file "smssystab.inc" included at the top
of the main control table:
*=================================================================
* Note that this section determines where SMS system components
* appear on the screen; it should probably appear in a
* separate file as it is not really part of the "application".
fields
* definition of field locations ...
- 28 -
EXAMPLE OF A CONTROL TABLE Page B-3
* keypad "pf" keys ...
pf1 24 1
pf2 24 21
pf3 24 41
pf4 24 61
pf_width 19
* scroll field ...
scroll_top 5
scroll_bot 15
* parameter prompt field ...
prompt_line 19
* error message line ...
err_line 20
* one-line message display ...
msg_line 21
* prompted command field ...
cmd_line 22
cmd_column 1
* one-line help ...
help_line 23
* automatic one-line help ...
auto_help on
switch sms_sys_config SMS configuration
position 4 10
field_width 15
entry sms_config_entry
exit sms_config_exit
* do not alter these parameters without making corresponding
* alterations inside SMS routine "sysconfig" ...
parameter beep term_beep [on] off
* note that the next must match the "auto_help" switch ...
parameter auto_help auto_help [on] off
* and this must match the "scroll_switch" (default permanent) ...
parameter scroll_region scroll_region temporary [permanent]
parameter scroll_device scroll_device TT
* you can change the next line to change the system default help
* file; you will also need an entry action "help @<your file>"
* to get it initialised as the code itself uses "sms_helpfile"
* e.g. change this to
* parameter help_file sms_help_file your_file
parameter help_file sms_help_file aon004
.page
action sms_config_entry
help @sms_helpfile
action sms_config_exit
help @<<sms_sys_config:help_file>>
* these lines must be present otherwise the SMS internal
* parameters are not configured ...
+config+ beep <<sms_sys_config:beep>>
+config+ auto_help <<sms_sys_config:auto_help>>
- 29 -
EXAMPLE OF A CONTROL TABLE Page B-4
+config+ scroll_region <<sms_sys_config:scroll_region>>
+config+ scroll_device <<sms_sys_config:scroll_device>>
menu sms_help_menu SMS help topics - press ENTER to get help
position 2 2
field_width 14
columns 5
* on entry, select SMS helpfile ...
entry sms_help_select
* on exit, restore current help file ...
exit sms_help_restore
* help topics ...
option keypad action sms_h_keypad sms_keypad
option menus action sms_h_menu sms_menu
option param_lists action sms_h_param sms_param
option macros action sms_h_macro sms_macro
option cursor action sms_h_cursor sms_cursor
option helpfile action sms_h_hfile sms_hfile
option actions action sms_h_action sms_action
action sms_help_select
help @sms_helpfile
action sms_help_restore
help @<<sms_sys_config:help_file>>
action sms_h_keypad
fullhelp sms_keypad
action sms_h_menu
fullhelp sms_menu
action sms_h_param
fullhelp sms_param
action sms_h_macro
fullhelp sms_macro
action sms_h_cursor
fullhelp sms_cursor
action sms_h_hfile
fullhelp sms_hfile
action sms_h_action
fullhelp sms_action
*=================================================================
- 30 -