Multics Technical Bulletin MTB 637
To: MTB Distribution
From: N.S.Davids
Date: 12/20/83
Subject: Executive Service, High Level Design
Comments may be made:
Via forum (method of choice):
>udd>m>nsd>mtgs>eou
Via electronic mail:
Davids.Multics
Via telephone:
862-6643
HVN: 357-6643
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced outside the Multics Project.
Multics Technical Bulletin MTB 637
CONTENTS
1.0 INTRODUCTION. . . . . . . . . . . . . . . . 1
2.0 GENERAL OVERVIEW. . . . . . . . . . . . . . 2
3.0 WINDOW MANAGEMENT . . . . . . . . . . . . . 14
4.0 ASYNCHRONUS OUTPUT. . . . . . . . . . . . . 14
5.0 INTERNAL ERROR HANDLING . . . . . . . . . . 15
6.0 CONDITION HANDLING. . . . . . . . . . . . . 16
7.0 MACRO COMMANDS. . . . . . . . . . . . . . . 17
8.0 NATIVE LANGUAGE SUPPORT . . . . . . . . . . 18
9.0 CONTROL SEQUENCES . . . . . . . . . . . . . 18
10.0 TESTING . . . . . . . . . . . . . . . . . . 19
11.0 APPENDIX 1 Example application function . .
definition. . . . . . . . . . 20
Multics Technical Bulletin MTB 637
1.0 INTRODUCTION
1.1 Purpose Of This Document
This MTB covers the high level design of the Xservice
subsystem and plans for implementing a test driver. It also
contains an example application function definition. This
example is very detailed and is used to show how application
functions will be implemented using the Xservice subsystem.
The companion document MTB636, "Executive Service, User
Interface" discusses the functions that this design will
implement. It also contains a very high level Xservice
project plan, a description of the Xservice prototype, and
the reason for the Xservice project.
1.2 Goals
The design of Xservice has several goals. First, the
interface presented to the user must be easy to learn and
remember. Second, the interface should not get in the way of
the experienced user. Third, the user should be able to
create new applications from existing commands or by writing
new routines to interface with Xservice. Fourth, any text
displayed to the user should be easily replaceable to allow
for native language customization.
1.3 Definitions
1.3.1 Xservice application function
An xservice application function is any group of user screens
and associated executable procedures and commands that can be
grouped together and given a name. Examples would be a forum
or mail system interface. Another example would be the top
level of Xservice, i.e. the first set of menus (and
associated procedures) in the Xservice interface.
MTB 637 Multics Technical Bulletin
2.0 GENERAL OVERVIEW
2.1 Introduction
Xservice executes as a sequence of distinct steps. Each step
is described by a set of step information (step-info) in the
step-info data store. The step-info data store also contains
the information needed to obtain the next set of step
information. There are 7 types of steps. Each step type
causes the driver to execute a different procedure.
2.2 Major Procedures
2.2.1 driver
This module drives the Xservice interface; based on the
current step information it will enable the appropriate
control sequences and execute the appropriate module. It
will also get the next step-info, based on the choice
information returned from the executed procedure, making it
the current step-info. It is responsible for writing to the
per-process value segment any information flaged by the
step-info for the selected choice. Finally, it is
responsible for creating an application function workspace
segment if the step-info indicates that one is needed before
calling the execute_procedure module (workspace creation is
meaningful only if this procedure is being called).
2.2.2 stack_mgr
This module maintains a stack of step-infos for steps that
are still active. A step is active if some subsequent step
may return to it. The push operation will push a step-info
onto the top of the stack making it the current step. The
pop operation will pop the step-info for the current step
(top of stack) from the stack. It will also destroy any
application function workspace that the step-info indicated
should be created and call any indicated cleanup procedure.
The look operation will successively pop step-infos from the
stack (cleaning up if necessary) until a step is found with a
particular name. That step-info will be left on the top of
the stack (making it the current step).
2.2.3 process_ctl_seq
The process control sequence module will perform the
functions for all of the control sequences. In many cases
this will amount to setting a flag (i.e. help, macro
definition in progress, etc.). All flags are stored in the
flags data store and are accessed via the xservice utilities.
In other cases, there will be stack operations, i.e. PREV
SCREEN. There may also be extensive work done as in EXPLAIN
ERROR which outputs texts or INPUT TEXT which sets a value in
the users profile data store.
Multics Technical Bulletin MTB 637
2.2.4 create_display_menu/get_choice_step
This module is executed for a
create_display_menu/get_choice_step step. It creates the
step-info for a display_menu/get_choice step and the menu
info for the menu to be displayed. The step and menu info
must be dynamic since the choices include macro names which
will vary as the user creates and deletes macros. The
execution of a create_display_menu/get_choice_step step is
one of two ways to build a display_menu/get_choice step. The
resultant display_menu/get_choice step is automatically
executed upon completion of this creation step (provided this
step completes without errors). Except for the macros
descriptions all the menu options are pre-defined in the
step-info data store.
2.2.5 create_display_menu/get_choice_step_from_procedure
This module is executed for a
create_display_menu/get_choice_step_from_procedure step and
has exactly the same function as the
create_display_menu/get_choice_step step. The only
difference is that in this step the non-macro menu options
are created dynamically via some procedure instead of
statically from the step-info data store. This allows menus
to contain options based on dynamic structures such as
segments in a dir or the contents of a data base.
2.2.6 execute_command_line
This module is executed for an execute command line step. It
will call cu_$cp to execute a command line. The command line
is static and comes from the step-info. Arguments may be
passed to the command line via active function calls to
value_$get within the command line. This routine also sets
up condition handlers for command_error and command_query.
For command_query the main window will be cleared (via a call
to a utility) and the question displayed on the first line of
that window. For command_error the first N characters of the
error message will be displayed in the Xservice message
window (via another call to a utility). The value of N will
be based on the user's terminal width. If the message is
longer than N characters a flag indicating that a detailed
error message is present will be set and the detailed error
message will be set to the entire error message.
2.2.7 execute_procedure
This module will be executed for an execute procedure step.
It will execute a procedure with a standard calling sequence.
The procedure may be written by a user or be an Xservice
utility. This is the mechanism that is used by the user when
writing an application function that does not use the command
level interface. There are three standard ways that the
executing procedure can get input. The step-info contains a
text string with static information which is passed to the
MTB 637 Multics Technical Bulletin
procedure as an argument. The procedure can also reference
the per-process value segment which the driver may store
things in. The final "standard" way is for the procedure to
get a pointer to the application function workspace via a
call to an Xservice utility. Standard output methods are to
write into the per-process value segment or the application
function workspace or return a text string to the driver. If
the indicated choice returned from the procedure indicates
that the driver is to write into the per-process value
segment the text of the returned string will be used.
2.2.8 display_menu_and_get_choice
This procedure will be executed for a display_menu/get_choice
step. It will display the limited response user screen and
get the user's response. If the user has input text mode set
for this screen, he will be prompted for his response and the
text input converted into a choice index. If the user is in
limited response mode, a menu will be displayed and the
user's choice obtained via calls to the menu system.
2.2.9 display_text
This procedure is executed for a display text step. It is
used to display a text user screen.
2.2.10 create_application_steps
This procedure is executed for a create application step. It
converts the static description of an application (stored in
the application function definition step-info and text data
stores) into a set of step-infos which can be used by
xservice
Multics Technical Bulletin MTB 637
2.3 Module Control Flow
The following diagram depicts the control flow between the
modules. The driver is invoked by a command. The driver
determines which module to execute by looking at the
step-info, the control sequence flag, and choice index
returned by the previous module. It calls the appropriate
module which returns to the driver. If the module returned a
control sequence, the driver will call the process_ctl_seq
module (which has access to the stack).
When Xservice is first invoked, it will have one hard wired
step-info to get things started. This step-info will
indicate that an application function is to be created. This
first application function will be the top levels of the
Xservice interface. This application function will have an
initial step-info that indicates that a menu (the XSERVICE
TOP SCREEN) is to be displayed and a user choice obtained
(display_menu/get_choice). The driver may alter this based
on the data in the user's profile data store or if this is
the first time that the user has invoked Xservice. After the
execution of this first step the driver will follow the path
determined by the step-infos without alteration.
MTB 637 Multics Technical Bulletin
| (COMMAND LEVEL INVOCATION)
|
| |----------------------------------------------|
| | |
V V |
---------- ------------- |
| DRIVER | <-----> | STACK_MGR | <--------| |
---------- ------------- | |
| | | | |
| | | | |
| <---------------| | | |
| V | |
| ------------------- | |
|--------> | PROCESS_CTL_SEQ |-----------------> |
| ------------------- |
| |
| ---------------------------------- |
|--------> | CREATE_DISPLAY_MENU/GET_CHOICE | |
| | _STEP |--> |
| ---------------------------------- |
| |
| ---------------------------------- |
|--------> | CREATE_DISPLAY_MENU/GET_CHOICE | |
| | _STEP_FROM_PROCEDURE |--> |
| ---------------------------------- |
| |
| --------------------------- |
|--------> | DISPLAY_MENU/GET_CHOICE |---------> |
| --------------------------- |
| |
| ---------------- |
|--------> | DISPLAY_TEXT |--------------------> |
| ---------------- |
| |
| ------------------------ |
|--------> | EXECUTE_COMMAND_LINE |------------> |
| ------------------------ |
| |
| --------------------- |
|--------> | EXECUTE_PROCEDURE |---------------> |
| --------------------- |
| |
| ---------------------------- |
|--------> | CREATE_APPLICATION | |
| _FUNCTION_STEPS |--------> |
----------------------------
Multics Technical Bulletin MTB 637
2.4 Utility Modules
The utility modules perform screen manipulation and
housekeeping tasks. They may be called from any of the major
modules or from any user written function executed by the
execute_procedure module. It is expected that more utility
routines will be defined during low level design and during
the implementation of application functions.
2.4.1 xservice_window_mgr
This module manages the contents of the all of the Xservice
windows except the interactive message window. It also
performs all the user input. There will be entries for
clearing and writing to the status, main, and Xservice
messages windows as well as prompting the user for input.
Some of the entry points are:
2.4.1.1 get_text
This module takes as input the location of some text and
returns a pointer to the text and the length of the text.
The length is expressed as total number of characters and
total number of printed pages. The number of pages will
depend on the user's terminal width and main window size.
There will also be an entry for getting a pointer to any
given page of the text.
2.4.1.2 get_new_file_name
This procedure will accept input from the main window. It
interprets that input an a segment name. It checks to be
sure that an entry with that name does not already exist in
the working dir. If it does it generates a recoverable
error. It assumes that a prompt in the status window has
been set up by the step that call it. Also that the error
path is to re-executed the step.
2.4.2 create_work_space
This module will create an application function workspace.
Current plans are for that workspace to be a temporary
segment in the user's process dir. No structure is imposed
on the workspace, i.e. it is not an area. There will also
be an entry point that returns a pointer to the workspace
given the application function's name. It is possible for
the same application function setup step to be executed by
the driver multiple times (the application function might be
recursive) in which case a call to get a pointer to the work
space will result in the pointer to the last workspace
created for that application function. There will be another
entry to destroy the workspace.
2.4.3 reply_editor
The reply editor is different from the user's selected editor
in that it splits the main window in two and displays the
text that the user is replying to in the top window. The
MTB 637 Multics Technical Bulletin
original text is displayed in display_text mode and the
display_text control sequences are enabled for positioning
with the original text. The status window will identify what
the original message is and the current and last page
numbers. In addition the COPY control sequence will be
enabled. The COPY control sequence will copy the original
text into the bottom window so the user can form a reply by
editing the original instead of retyping it. Once all the
windows are set up and loaded, the user's favorite editor is
invoked to create the reply.
The application function will have to call this utility with
the following information: a string identifying the original
message (for display in the status window), a pointer to a
string containing the original message and the number of
characters in the message. The utility will return a pointer
to the reply and the number of characters in the reply. The
data at the pointer location will be valid until the reply
editor is invoked again or the Xservice system is exited.
2.4.4 flag_manager
The flag manager is used to set and query the flags in the
flag data store. Some of the flags will be used to indicate
that Xservice is in a particular state, i.e. HELP mode,
MACRO DEFINITION mode. Other flags will indicate that an
event has happened, i.e. the user has entered a response to
a user screen.
2.4.5 user_profile_manager
This module will be used to set and query the attributes
stored within the users profile data store. See section
2.5.5 for a list of these attributes.
2.4.6 list_all_segs_and_links
This procedure is used to create a list of segments and links
in the working dir to be used in a menu. The standard input
string should contain the star name of the segments and
links.
2.4.7 build_menu_from_list
This procedure is used to create a list of things to be used
in a menu. The list is formed from the lines in a segment, 1
line per menu option. The segment is assumed to be in the
user's process dir. The standard input should contain the
name of the segment.
2.4.8 xservice_interact_msg_mgr
This procedure performs output to the Xservice interactive
message window.
Multics Technical Bulletin MTB 637
2.5 Data Stores
The data stores are logical locations where data is stored.
By referring to these storage locations as data stores it is
possible to talk about the data and its meaning without
implying any given structure to the data. It is possible
that in low level design or implementation several data
stores will be combined into a physical structure. There are
two types of data stores: those that record data between
processes and those that record data only for the given
process.
2.5.1 step-info (per-process)
The step-info data store contains information about each of
the steps that the driver may execute. The information about
a given step will be called a step-info instance. There are
several types of steps corresponding to the different modules
that the driver may execute. The type of data stored in the
step-info instance will depend on the type of step.
The data common to all step types are:
o step name
o step type
There are seven types of steps:
create_display_menu/get_choice_step
create_display_menu/get_choice_step_from_procedure
display_menu/get_choice
display_text
execute_command_line
execute_procedure
create_application_step_info.
o pi flag
If set to true this step will be re-executed if a PI
condition is signaled.
o error path
o name of the next step to be executed in case of
error
o stack operation
Either push the next step-info instance making it
the current step, or look for the preceding instance
of the indicated step. In most cases, the error
path will be doing a look operation (in which case
the rest of the following error path information is
not needed).
o location of next step-info instance
o location of help information about the next step
indicated by this choice
o name of value segment data element that the choice
information will be stored as. If null nothing will
be stored.
o value that will be stored in the value segment with
the above name if different from the name of the
next step name. If null and the data element name
MTB 637 Multics Technical Bulletin
is not null, the name of the next step will be
stored.
o normal path
o name of the next step
o stack operation
Either push the next step-info instance making it
the current step, or look for the preceding instance
of the indicated step.
o location of next step-info instance
o location of help information about the next step
indicated by this choice
o name of value segment data element that the choice
information will be stored as. If null nothing will
be stored.
o value that will be stored in the value segment with
the above name if different from the name of the
next step name. If null and the data element name
is not null the name of the next step will be
stored.
Other information that is used by the
create_display_menu/get_choice_step step:
o info for created step
o pi flag
o line 1 of status window
o line 2 of status window
o step setable control sequences to be enabled
o menu/choice information for each step
o menu option description
o name of next step
o stack operation
o location of next step-info instance
o location of help info
o name of value data element
o value of value data element
Other information that is used by the
create_display_menu/get_choice_step_from_procedure step:
o procedure to execute
o standard input
o info for created step
same as for the create_display_menu/get_choice_step
o choice information
o name of next step
o stack operation
o location of next step-info instance
o location of help info
o name of value segment data element
o value of value segment data element
Other information that is used in the display_menu/get_choice
and display_text steps:
Multics Technical Bulletin MTB 637
o line 1 of status window
o line 2 of status window
o list of step setable control sequences to be enabled
for this step
o location of the menu structure or text information
Other information that is used in the execute procedure step:
o name of function to be executed
o static input
o procedure's text output
o clear main window before execution flag
o clear main window after execution flag
o pause after execution flag
o workspace needed flag
The workspace will be given the same name as the step
o location of cleanup procedure
o line 1 of status window
o line 2 of status window
o step setable control sequences to be enabled
Other information that is used in the execute command line
step:
o text of command line
o clear main window before execution flag
o clear main window after execution flag
o pause after execution flag
o line 1 of status window
o line 2 of status window
Other information that is used in the create application
function step-info step:
o location of the application function definition
step-info data store
o location of the application function definition text
data store
2.5.2 Stack (per process)
The stack is used to keep track of all the steps that
Xservice has been in and which are still active. Steps are
pushed onto the stack whenever the choice information for the
next step indicates a push. Steps are popped from the stack
in response to a PREV SCREEN or TOP SCREEN control sequence.
The former will pop all steps until the previous display type
step is found, the latter will pop all steps until the step
displaying the Xservice top screen is found. Steps will also
be popped off the stack if the choice indicates that the next
step is one of the previous steps or a PI or cleanup
condition is signalled.
2.5.3 application function workspace (per process)
There may be several of these data stores created. A
workspace is created by the driver by calling a utility when
MTB 637 Multics Technical Bulletin
an executable procedure step indicates that a workspace will
be needed. The structure of the workspace is left up to the
application functions executable procedures.
2.5.4 flags (per-process)
This data store is used to store all the flags that are set
during the execution of Xservice. The flags need to be set
and queried from both the Xservice driver and the procedures
that the driver calls. In addition some of the application
functions may need to query the flags.
2.5.5 User profile (permanent)
The user profile contains the information set by the user
when responding to the PERSONALIZE XSERVICE limited response
user screen and the EDIT FUNCTIONS user screens (see MTB
636). It also contains the order of the elements of the
FUNCTIONS user screen menu, all the user's macro definitions,
and the display mode of each limited response user screen
(limited response or input text).
2.5.6 Xservice Text (permanent)
The Xservice text data store will contain all the text that
is application function independent, (that is the labels for
the control sequences, and error/warning message text).
2.5.7 Application Function Definition Step-info (permanent)
The application function definition step-info is slightly
different from the step-info used by Xservice. Since the
application definition is independent of the user's process
all locations must be identified by pathname and entry name
(with perhaps a character offset within the entry). This
data store refers to all text strings by location within the
application function definition text data store.
2.5.8 Application Function Definition Text (permanent)
This data store contains all the text associated with an
application function.
Multics Technical Bulletin MTB 637
2.6 Application Functions
An application function is defined by two special data stores
which contain all the information for constructing the
step-info instances. These application function data stores
will be built via an interactive session with the Xservice
user defined extensions subsystem (see MTB 638). The first
time an application function is executed in a process, the
create application step-info step is executed to convert the
process independent information in the data stores into a
more efficient form.
An application function will generally consist of steps to
display text and menus and steps to execute functions to
perform the user requested operations. These functions may
be either Xservice utilities, procedures written for the
application function, or commands. To allow these functions
to communicate with each other, a special application
function workspace may be created when the first step of the
application function is executed. A pointer to this
workspace may be obtained via a call to an Xservice utility.
What structure the application function imposes on this
workspace is immaterial to Xservice. It is also possible to
indicate to Xservice that the responses to user screens are
to be recorded in the user's per-process value segment. This
allows applications making use of commands to obtain
responses to previous user screens. Of course it is also
possible for an application to have a function which creates
its own workspace, the advantage of having Xservice do it is
that Xservice is then responsible for cleaning it up when the
application exits.
MTB 637 Multics Technical Bulletin
3.0 WINDOW MANAGEMENT
Four of the five Xservice windows are completely managed by
the Xservice utility procedure xservice_window_mgr. The
fifth is the interactive message window. Completely managed
means that all Xservice output to those windows and input to
Xservice from them is done via calls to the
xservice_window_mgr. In addition, the module is responsible
for the creation and destruction of all Xservice windows.
The main window remains attached to the user_io iocb. This
enables applications using existing procedures and commands,
which do I/O directly, to use the main window. The
interactive message window is set up by the
xservice_window_mgr but all output to it is handled via the
xservice_interact_msg_mgr utility procedure.
4.0 ASYNCHRONUS OUTPUT
4.1 Interactive Messages
When the Xservice interactive message window is created, a
call to accept_messages is made with arguments of "-hold" and
"-call xservice_interact_msg_mgr" The module
xservice_interact_msg_mgr will output the message and the
sender's name to the Xservice interactive message window (see
MTB636). If the user removes the interactive message window
from his screen then another call to accept_messages is made
with an argument of "-call" which will cause the output of
interactive messages to behave like any other asynchronous
output (see below).
4.2 Other forms of asynchronous output
Asynchronous output which goes to the user_io switch will be
displayed in the main window. This output will be cleared
whenever Xservice executes a step that writes a user screen.
The user_io switch must be attached to the main window in
order to allow the user to execute commands and user written
functions from the Xservice environment without having to
specially modify those commands and functions.
4.3 System changes allowing a cleaner interface
One way to prevent the output of asynchronous messages to the
main window would be arbitrarily redirecting the output.
This would require that all systems that do asynchronous
output have a way to set and return a pointer to the iocb
that output will be done on. The major systems are the
message facility, memo, and forum. Entries for pushing and
popping the switch would also be useful.
Multics Technical Bulletin MTB 637
5.0 INTERNAL ERROR HANDLING
5.1 Program Logic Errors
Errors returned from calls to system modules that cannot be
handled (or errors which indicate that the current state of
the system is no longer known and cannot be reset) will be
considered internal programming errors. These errors will
signal the XSERVICE_POGRAM_LOGIC_ERROR condition. A handler
for this condition will be established by the Xservice
driver. The action taken by this handler will be to first
output the message:
PROGRAM LOGIC ERROR ENCOUNTERED
Then the context of the error (supplied by the module which
signaled the condition will be output followed by the actual
message as indicated by the returned error code. At this
point the instruction to:
Press RETURN to exit Xservice
will be issued (in fact any character will cause Xservice to
exit). Exiting Xservice will execute all the established
cleanup handlers, destroy all the Xservice created windows
and clear the user_io screen. The error message is output
before the cleanup to make sure that it is output in case the
cleanup procedures fail in some unknown way.
Information about program logic errors will be sent to the
xservice_suggestion mailbox if the site has provided such a
mailbox. If the site has not provided the mailbox the
information is reported only to the user.
5.2 Recoverable Errors
Recoverable errors will be handled by filling an error
message structure and signaling the XSERVICE_REPORT_ERROR
condition. A handler for this condition will be setup in the
Xservice driver. It will display the primary error message
in the Xservice message window and if a more detailed error
message is available a flag will be set to enable the
EXPLAIN_ERROR control sequence. After the message flag is
set, control will be returned to the signaling procedure
which will indicate that the next choice is to be the error
choice. The error message will stay in the Xservice message
window until the user enters a keystroke that indicates that
he wishes to go on to some other step. An example of a
recoverable error is when the user invokes a disabled control
sequence.
MTB 637 Multics Technical Bulletin
6.0 CONDITION HANDLING
6.1 Command_error
The handler for this condition will be set up in the execute
command line procedure. The command error condition is
signaled by com_err_ which will be called if a command that
is executed as part of a user defined application reports an
error. The handler will cause the first N characters of the
error message (where N is the width of the window) to be
displayed in the Xservice message window. If the error
message has more than N characters than the flag indicating
that the EXPLAIN_ERROR control sequence should be enabled is
set. The last thing that the handler will do is go back to
the last step that required user input. If the EXPLAIN_ERROR
control sequence is enabled and the user invokes it the
entire error message is displayed (including the first N
characters).
6.2 Pi
The handler for this condition is set up in the Xservice
driver. At each step the application builder can indicate
whether he wants the step re-executed if a pi condition is
signaled. Xservice will start with the current step and if a
cleanup handler has been established will execute it. Then
if the step has the pi flag set it will re-execute the step
or proceed to the previous step. The function being executed
can establish its own pi handler if it wants to.
6.3 Cleanup
The handler for this condition is setup in the Xservice
driver. When a cleanup is signaled Xservice will start with
the most recently executed step and execute its cleanup
handler if one was indicated. It will then proceed popping
steps off of its stack and executing their cleanup handlers.
When all steps have been removed from the stack, Xservice
will clean itself up. This entails restoring the user_io
window and clearing it, freeing any temporary segments
created for application storage or Xservice working space,
and restoring the video environment.
6.4 Command_query
A handler for this condition will be setup in the execute
command line procedure. The command_query condition is
handled so that any command query issued by a user defined
application is handled correctly. The main window is cleared
and if the query is shorter than the width of the terminal it
is displayed in the Xservice status window. If the query is
longer than the width of the terminal it is displayed
starting at the top of the main window. The user will
respond in the main window.
Multics Technical Bulletin MTB 637
7.0 MACRO COMMANDS
A macro command is a sequence of responses which perform some
set of actions which the user wants to be able to perform
without entering each response individually and without
having each user screen displayed on the terminal. Macros
may be defined only for limited response user screens.
A macro definition is composed of the following:
o the name of the step the macro is defined for
o the macro name
the name is also the menu option description.
o number of responses
for each response:
o the step name the response is for
o dynamic response flag
o response
responses are stored as next-step step names so that
macro responses are independent of changes in the order
of the choices.
The create_display_menu/get_choice_step step will query the
user's profile for any macros and incorporate them into the
menu options along with the static choices.
7.1 Execution of a Macro
A macro is executed in the following way. The first response
in the macro is a response to the menu that contained the
macro. All other responses are associated with the step
generated by the previous response. The step name associated
with the response is checked to be sure that the response is
being applied to the correct step. If the check fails then
an error is reported and execution of the macro stops. The
user is left at the step that the error occurred in. When a
macro is executing, the main window will contain the user
screen that invoked the macro. The status window will
indicate that a macro is executing and the name of the macro.
The second line will list the steps that are being executed.
Only the steps that the user would normally see, i.e.
display steps will be listed. The exception to this is if
the dynamic response flag is set. For that step the status
and main windows will be cleared and the user screen for that
step will be displayed so that the user can respond. Once
the user has responded, the status window will again indicate
that the macro is running and what step is being executed.
The macro completes execution when a step requiring user
input is reached and and all the macro's stored responses
have been used. At this point the windows are updated to
show the user screen which requires the input.
MTB 637 Multics Technical Bulletin
8.0 NATIVE LANGUAGE SUPPORT
All Xservice textual material will be contained in segments
separate from the executable code (the Xservice text and
application function definition text data stores). The
content of these segments will be documented and special
editing tools will be made available to change the text.
This will allow easy conversion of the text from English to
some other language. Special editing tools will be developed
not only to assist (in an Xservice like way) in the
translation but to assure that any non-textual material is
correctly updated to reflect textual changes.
Text that Xservice has no control over, i.e. system error
messages will be output as is.
9.0 CONTROL SEQUENCES
Xservice will have two forms of control sequences. The first
form will use single keys (function keys and the <>? keys).
The second form will use the sequence ESCx_ where "_"
identifies the requested control sequence.
Since there are 23 control sequences and VIP terminals have
only 12 function keys each function key must be used for more
than 1 control sequence. This is done by assigning each
control sequence to the next unused function key. Since no
more than 7 control sequences requiring function keys can
appear in the control window at any one time, the minimum
number of function keys required is 7. Note that the PREV
CONTROL, NEXT CONTROL, and HELP control sequences use the <>?
keys not the function keys.
Each three-character escape sequence is assigned to only 1
control sequence.
When Xservice is invoked, it will issue commands to the video
editor to determine if the ESCx sequence has been defined by
the user (the video line editor will not define it). If the
sequence has been defined, a warning message will be issued
indicating that Xservice will be pre-empting it. All
original information will be saved and restored when Xservice
exits. If the sequence has not been defined no warning will
be issued.
This will require that the capability to get information on a
key-binding be added to the video-editor system.
There are two types of control sequences, step-enabled and
xservice-enabled. The step enabled control sequences are
Multics Technical Bulletin MTB 637
enabled by the current step and are therefore under the
control of the person writing the application function. The
step-enabled control sequences are:
HELP
TOP SCREEN
PREV SCREEN
NEXT SCREEN
OPEN MACRO
MULTICS
These control are disabled at the end of each step.
All other control sequences are enabled or disabled by the
Xservice driver based on the current step-info and the user's
environment, e.g. if the user's site has an
xservice_suggestion mailbox than the suggestion control
sequence will be enabled.
10.0 TESTING
In order to test the Xservice system a test driver will be
built. This driver will cause Xservice to enter one of two
special testing modes. In the first mode (build test mode),
Xservice will record the contents of user's screen (all
lines) after any output to any Xservice window. Also user
input will be recorded. This will allow a developer to
create a test script by executing it once. In the second
mode (execute test mode), a test script will be executed and
the user screens again stored away. After the test completes
the original screen record will be compared with the new
screen record for any discrepancies. It will be possible to
indicate that for an given user screen, certain portions of
the screen are not to be compared. This will allow date-time
or other environment dependant features to be ignored. The
test driver will not be part of the Xservice product.
MTB 637 Multics Technical Bulletin
APPENDIX 1
Example application function definition
The following is an example of the steps and data that would need
to be defined for implementing an archive function using the
archive command interface. This application is similar to the
the archive function implemented by the prototype (MTB 636). The
major difference is that this version will display in the status
window the archive command line that it is executing.
There are two parts to this example. The first part is a flow
chart of the execution of the steps. Note that paths labeled
with an E represent error paths. The second part of this example
is a detail of the information that must be supplied by the user
for each step. Note that the user would define these steps and
data via the Xservice utility for defining application functions
(MTB 638).
Note also that part two does not show the way any data structures
will actually be defined but merely what data will be defined.
Also, not all data elements need to be defined in all cases. For
instance, the values of location of help info, name of value data
element, and value of value data element for a choice need not be
defined if the choice's stack operation is a look. Also the
value of "value of data element" need not be defined if the name
of the value data element is not set (displayed here as NONE).
The value "PATH" stands for some Multics path the user typed in.
The value "BLANKS" stands for a blank line.
Multics Technical Bulletin MTB 637
|
|------------------------------->(1)<---------------------|
| | |
| V |
| xservice functions menu |
| | |
| V |
|<------------------E create main archive menu |
| | |
| V |
| main archive menu |
| | |
| |-------------------------| |
| | | |
| |------------>| | |
| | V V |
| |<-E create a new archive select an existing E-|
| file archive file
| | |
| V |
|<-------E create append archive V
| options menu (2)
| |
| V
| append archive options
| menu
| |
| |---------------|----------------|
| | | |
| V V V
| append append then append then
| | delete force delete
| | | |
| |-------------->|<---------------|
| |
| (3)<------------------------|
| | |
| V |
|<------E list all segs and links |
| | |
| V |
| files menu |
| | |
| V |
|<-----E display append archive command |
| | |
| V |
|<-------E append archive command |
| |
|--------------------------|
MTB 637 Multics Technical Bulletin
(2)
|
V
archive files menu
|
(4)
|
V
(1)<-------E create all archive options menu
|
V
all archive options menu
|
|---------------|--------------------|
| | |
V | |
append | V
append then delete | (5)
append then force delete |
replace |
replace the delete |
| |
V |
(3) |
V
table of contents
long table of contents
brief table of contents
long table with no headings
|
V
(1)<---------E display table archive command
|
V
(1)<------------E table archive command
|
V
(4)
Multics Technical Bulletin MTB 637
|
(5)
|
V
delete
extract
extract then delete
force the extract then delete
force the extract
|
|<---------------|
V |
(1)<--------E get archive component list |
| |
V |
(1)<---E create menu of archive components |
| |
V |
menu of archive components |
| |
V |
(1)<-----E display general archive command |
| |
V |
(1)<--------E general archive command |
| |
|----------------|
MTB 637 Multics Technical Bulletin
Step 1
This first step indicates that a display_menu/get_choice step
and its associated menu are to be created. If an error occurs
control will be returned to the xservice functions step. If
no errors occur control will be transfer to the just created
display_menu/get_choice step. Since the step is being created
no location information is required. Since there is no user
response there is no need for a help path and since no
information is to be recorded there is no need for a data
element name or value. A create_display_menu/get_choice_step
step info produces no visible output (unless an error occurs).
The pi flag setting indicates that this step will be
re-executed in response to a pi condition.
o name: create main archive menu
o type: create display_menu/get_choice step
o pi flag: ON
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: main archive menu
o info for created step
o pi flag: OFF
o line 1 of status window: Xservice first archive menu
o line 2 of status window:
Create a new, or select an existing, archive file
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o menu/choice information
o choice 1
o menu option description:
create a new archive file
o name of next step: create a new archive file
o stack operation: push
o location of help info: PATH
o name of value data element: NONE
o menu option description:
select an existing archive file
o choice 2
o name of next step: select an existing archive file
o location of help info: PATH
o stack operation: push
o name of value data element: NONE
Step 2
This step executes the procedure
xservice_utility_$get_new_file_name. In the event of an
error, control will be returned to the xservice functions
step. Otherwise control will be passed to the create append
archives option menu step. The help path will supply help on
Multics Technical Bulletin MTB 637
what the user is suppose to enter, i.e. the new archive file
to be created. Before control is passed to that step a value
with the name archive_file will be placed in the user's
per-process value segment. Since no static value for
archive_file is recorded the value returned from
get_new_file_name will be used. To allow the user a clear
space to enter the file name (or control sequence) the main
window is cleared before the get_new_file_name procedure is
executed.
o name: create a new archive file
o type: execute procedure
o name of function: xservice_utility_$get_new_file_name
o static input: NONE
o pi flag: OFF
o clear main window before execution flag: ON
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o work space needed flag: OFF
o name of cleanup procedure: NONE
o line 1 of status window:
Xservice creating a new archive file
o line 2 of status window:
The name of the new archive file is ?
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o error path
o name of next step: create a new archive file
o stack operation: push
o location of help info: PATH
o name of value data element: NONE
o normal path
o name of next step:
create append archive options menu
o stack operation: push
o location of help info: PATH
o name of value data element: archive_file
o value of value data element: NONE
Step 3
This step indicates that a menu and display_menu/get_choice
step are to be created. The menu created lists only the
append options of the archive function since those are the
only functions available when you create an archive. The
information supplied with the menu options indicates that a
data value with the name archive_option will be placed in the
user's per-process value segment. The value of that data
element will depend on the user's choice.
o name: create append archive options menu
o type: create display_menu/get_choice step
MTB 637 Multics Technical Bulletin
o pi flag: OFF
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: append archive options menu
o info for created step
o pi flag: OFF
o line 1 of status window: Xservice archive options
o line 2 of status window:
Select the option to be used to archive the file
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o menu/choice information
o choice 1
o menu option description: append
o name of next step: list all segs and links
o stack operation: push
o location of help info: PATH
o name of value data element: archive_option
o value of value data element: a
o choice 2
o menu option description: append then delete
o name of next step: list all segs and links
o stack operation: push
o location of help info: PATH
o name of value data element: archive_option
o value of value data element: ad
o menu option description: append then force delete
o choice 3
o name of next step: list all segs and links
o stack operation: push
o location of help info: PATH
o name of value data element: archive_option
o value of value data element: adf
Step 4
This step creates a menu and a display_menu/get_choice step.
However, instead of the menu options being supplied by the
person creating the step they are dynamically created by a
procedure. In this case the menu will consist of all the
segment and link names in the user's working directory. The
standard input ** represents the star name to match on. The
same information is applied to all choices. Note that since
the name of the value data element is set and the value of the
data element is not set, the name of the choice will be
stored. In this case the name of the choice is the same as
the name of the segment or link.
o name: list all segs and links
o type: create display_menu/get_choice step from procedure
Multics Technical Bulletin MTB 637
o procedure to execute:
xservice_utility_$list_all_segs_and_links
o standard input: **
o pi flag: OFF
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: files menu
o info for created step
o pi flag: OFF
o line 1 of the status window: List of archivible files
o line 2 of status window: Select a file to be archived
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o choice information
o name of next step: display append archive command
o stack operation: push
o location of help info: PATH
o name of value segment data element: seg_to_be_archived
o value of value segment data element: NONE
Step 5
This step will execute a procedure which will query the value
segment to get the archive file name, archive option, and file
to be archived It will also display in the status window the
actual command that the user could have typed in if he were at
command level.
o name: display append archive command
o type: execute procedure
o name of function to be executed:
display_xservice_archive_command
o standard input: NONE
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o work space needed flag: OFF
o name of clean up procedure: NONE
o line 1 of status window: BLANKS
o line 2 of status window: BLANKS
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: append archive command
o stack operation: push
MTB 637 Multics Technical Bulletin
o location of help info: PATH
o name of value data element: NONE
Step 6
This step executes the archive command. The command line
makes a call to value to get the arguments recorded by
previous steps. After a successful execution, control will
return to the list all segs and links step (Step 4) so the
user can select another segment or link for archiving. While
the command is executing, the main and control windows will
continue to show the display from the previous steps. Since
there is no status window text set, the status window will
also continue to show the display from the previous step - in
this case the archive command line output from step 5.
o name: append archive command
o type: execute command line
o command line:
archive [value_get archive_option] [value_get
archive_file] [value_get seg_to_be_archived]
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o line 1 of status window: NONE
o line 2 of status window: NONE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: list all segs and links
o stack operation: look
Step 7
The menu created by this step will list all the archive
segments in the user's working dir. The user's choice will
indicate which archive file he wants to deal with. The choice
is stored under the name archive_file in the user's
per-process value segment.
o name: select an existing archive file
o type: create display_menu/get_choice step from procedure
o procedure to execute:
xservice_utility_$list_all_segs_and_links
o standard input: **.archive
o pi flag: OFF
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
Multics Technical Bulletin MTB 637
o name of next step: archive files menu
o info for created step
o pi flag: OFF
o line 1 of status window: Xservice list of files
o line 2 of status window: Select a file to archive
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o choice information
o name of next step: create all archive options menu
o stack operation: push
o location of help info: PATH
o name of value data segment element: archive_file
o value of value data segment element: NONE
Step 8
This step will create a menu of all the archive options plus
the display_menu/get_choice step (needed to display the menu
and the users choice). Since the menu options are supplied
the choice information for each choice is listed separately.
The user's choice is recorded under the name archive_option.
o name: create all archive options menu
o type: create display_menu/get_choice step
o pi flag: OFF
o error path
o name of next step: xservice_functions
o stack operation: look
o normal path
o name of next step: all archive options menu
o info for created step
o pi flag: OFF
o line 1 of the status window: Xservice archive options
o line 2 of the status window: Select an archive option
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o menu/choice information
o choice 1
o menu option description: table of contents
o name of next step: display table archive command
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: t
o choice 2
o menu option description: long table of contents
o name of next step: display table archive command
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: tl
o choice 3
MTB 637 Multics Technical Bulletin
o menu option description: brief table of contents
o name of next step: display table archive command
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: tb
o choice 4
o menu option description:
long table with no headings
o name of next step: display table archive command
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: tlb
o choice 5
o menu option description: append
o name of next step: list all segs and links
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: a
o choice 6
o menu option description: append then delete
o name of next step: list all segs and links
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: ad
o choice 7
o menu option description: append then force delete
o name of next step: list all segs and links
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: adf
o choice 8
o menu option description: replace
o name of next step: list all segs and links
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: r
o choice 9
o menu option description: replace then delete
o name of next step: list all segs and links
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: rd
choice 10
o menu option description: delete
o name of next step: get archive component list
Multics Technical Bulletin MTB 637
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: d
o choice 11
o menu option description: extract
o name of next step: get archive component list
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: x
o choice 12
o menu option description: extract then delete
o name of next step: get archive component list
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: xd
o choice 13
o menu option description:
force the extract then delete
o name of next step: get archive component list
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: xdf
o choice 14
o menu option description: force the extract
o name of next step: get archive component list
o location of help info: PATH
o stack operation: push
o name of value data element: archive_option
o value of value data element: xf
Step 9
This step will execute a procedure which will query the value
segment to get the archive file name, and archive option. It
will also display in the status window the actual command that
the user could have typed in if he were at command level.
o name: display table archive command
o type: execute procedure
o name of function to be executed:
display_xservice_table_archive_command
o standard input: NONE
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o work space needed flag: OFF
o name of clean up procedure: NONE
MTB 637 Multics Technical Bulletin
o line 1 of status window: BLANKS
o line 2 of status window: BLANKS
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: table archive command
o stack operation: push
o location of help info: PATH
o name of value data element: NONE
Step 10
This step executes an archive command. It is used only if the
user selects a table of contents option so it uses only the
archive_option and archive_file value data elements. In
addition, it clears the main window before executing the
command so that the output from archive will go to a clear
window. It also will pause after the command finishes to
allow the user to read the screen. During the pause a prompt
will be issued telling the user to press the return key to
return to the previous menu. If the output from archive is
longer than the main window then standard more-mode prompting
will be done.
o name: table archive command
o type: execute command line
o command line:
archive [value_get archive_option] [value_get
archive_file]
o pi flag: OFF
o clear main before_execution flag: ON
o clear main after execution flag: OFF
o pause after execution flag: ON
o pause message: return to the previous menu
o line 1 of status window: NONE
o line 2 of status window: NONE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: create all archive options menu
o stack operation: look
Step 11
This step executes a command line to produce a segment with
the names of all the components of the archive. This segment
will be used to input produce a menu at the next step.
Multics Technical Bulletin MTB 637
o name: get archive component list
o type: execute command line
o command line:
file_output [pd]>archive_components -tc; archive_table
[value_get archive file]; revert_output
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o line 1 of the status window: BLANK
o line 2 of the status window: BLANK
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: create menu of archive components
o location of help info: NONE
o stack operation: push
o name of value data element: NONE
Step 12
This step creates a menu out of the list generated in the last
step. The user's choice is stored under the name
seg_to_be_archived.
o name: create menu of archive components
o type: create display_menu/get_choice step from procedure
o procedure to execute:
xservice_utility_$build_menu_from_list
o static input: archive_components
o pi flag: OFF
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: menu of archive components
o info for created step
o pi flag: OFF
o line 1 of status window: NONE
o line 2 of status window: NONE
Select a component from the archive
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o choice information
o name of next step: display general archive command
o location of help info: PATH
o stack operation: push
MTB 637 Multics Technical Bulletin
o name of value data element: seg_to_be_archived
o value of value data element: NONE
Step 13
This step will execute a procedure which will query the value
segment to get the archive file name, archive option and file.
It will also display in the status window the actual command
that the user could have typed in if he had been at command
level.
o name: display general archive command
o type: execute procedure
o name of function to be executed:
display_xservice_archive_command
o standard input: NONE
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o work space needed flag: OFF
o name of clean up procedure: NONE
o line 1 of status window: BLANKS
o line 2 of status window: BLANKS
o step setable control sequences to be enabled:
HELP, TOP SCREEN, PREV SCREEN, MULTICS MODE
o error path
o name of next step: xservice functions
o stack operation: look
o normal path
o name of next step: general archive command
o stack operation: push
o location of help info: PATH
o name of value data element: NONE
Step 14
This step executes the archive command.
o name: general archive command
o type: execute command line
o command line:
archive [value_get archive_option] [value_get archive
file] [value_get seg_to_be_archived]
o pi flag: OFF
o clear main window before execution flag: OFF
o clear main window after execution flag: OFF
o pause after execution flag: OFF
o line 1 of the status window: NONE
o line 2 of the status window: NONE
o error path
o name of next step: xservice functions
Multics Technical Bulletin MTB 637
o stack operation: look
o normal path
o name of next step: get archive component list
o stack operation: look