MULTICS TECHNICAL BULLETIN MTB-646
To: MTB Distribution
From: Gary C. Dixon
Date: December 19, 1983
Subject: Command Argument Processing (CAP): An Overview
This MTB introduces Command Argument Processing (CAP), a
facility: for providing command interfaces which are friendlier
to use; for simplifying the coding of command-level interface
routines (commands, active functions, subsystem requests and
active requests, I/O modules, and exec_coms); and for
standardizing argument handling. The full implementation of the
facility includes: forms interfaces to commands, exec_coms,
subsystem requests, etc; command line completion capabilities;
and prompting for omitted arguments.
This MTB discusses the problems with current interfaces, gives
requirements for a solution to solve these problems, and presents
a possible solution. Implementation details will be described in
subsequent MTBs, after discussion of this MTB produces an agreed
upon set of requirements.
Comments on this MTB should be placed in the ease_of_use forum on
System M:
>udd>m>Davids>mtgs>ease_of_use (eou)
or directed by Multics mail to:
System M: GDixon.Multics
MIT: GDixon -at pco
or by phone to:
Gary Dixon
HVN: 357-6645
DDD: 602-862-6645
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced or distributed outside the Multics Project.
MTB-646 CAP: Overview
CONTENTS
Page
0 Preface . . . . . . . . . . . . . . . . . . . . . 1
1 Problem: Multics is Unfriendly . . . . . . . . . 2
1.1 Multics, Unfriendly to End-Users . . . . . . 2
1.2 Multics, Unfriendly to Programmers . . . . . 3
1.3 Is there a Solution? . . . . . . . . . . . . 4
1.4 CAP is Only Part of the Solution . . . . . . 5
2 CAP Targets . . . . . . . . . . . . . . . . . . . 7
2.1 Audience . . . . . . . . . . . . . . . . . . 7
2.2 Requirements for CAP . . . . . . . . . . . . 7
3 Possible Design for CAP . . . . . . . . . . . . . 9
3.1 User Interfaces and Operating Environments . 9
3.2 Overview of the Design . . . . . . . . . . . 10
3.3 Operational Scenarios and Flow of Control . 12
3.3.1 Command Line- No Options :
Interactive- Command Level . . . . . . . . . 12
3.3.2 Command Line- With Prompting :
Interactive- Command Level . . . . . . . . . 14
3.3.3 Command Line- With Completion :
Interactive- Command Level . . . . . . . . . 14
3.3.4 Form : Interactive- Command Level . . 16
3.3.5 Command Line- With Options :
Interactive- ssu_ . . . . . . . . . . . . . 20
3.3.6 Form : Interactive- ssu_ . . . . . . . 20
3.3.7 Form : Interactive- Xservices . . . . 20
3.3.8 Command Line or Form : Keyword Syntax-
archive, etc . . . . . . . . . . . . . . . . 21
3.3.9 Command Line or Form : Keyword Syntax-
exec_com . . . . . . . . . . . . . . . . . . 21
3.3.10 Command Line or Form : Keyword
Syntax- io_call . . . . . . . . . . . . . . 23
3.3.11 Command Line : Subroutines- iox_ . . 25
3.3.12 Command Line : Other Subroutines . . 26
3.3.13 Command Line- No Options : Absentee
Environment . . . . . . . . . . . . . . . . 26
3.4 Common Aspects of the Flow of Control . . . 26
3.5 Online Documentation from the BID
Information . . . . . . . . . . . . . . . . . . 27
3.6 The CAP Translation Mechanism . . . . . . . 28
3.6.1 Goals for Translation . . . . . . . . . 29
3.6.1.1 BID Should Be an Object Segment . 29
CAP: Overview MTB-646
CONTENTS (cont)
Page
3.6.1.2 Translation Mechanism Should be
Simple to Use . . . . . . . . . . . . . . 30
3.6.1.3 Programs Using CAP Should Be Easy
to Understand . . . . . . . . . . . . . . 30
3.6.1.4 The Translation Mechanism Should
Be Simple to Code . . . . . . . . . . . . 30
3.6.2 Possible Translation Mechanisms . . . . 30
3.6.2.1 Design 1: Separate Source and
Object . . . . . . . . . . . . . . . . . 30
3.6.2.2 Design 2: Integrated Source and
Object . . . . . . . . . . . . . . . . . 31
3.6.2.3 Other Designs . . . . . . . . . . 34
3.6.3 How Translation Works for Programs . . 34
3.6.4 How Translation Works for Exec_coms . . 36
3.6.5 Detecting a CAP Interface . . . . . . . 36
3.7 Support for Existing Programs . . . . . . . 37
3.7.1 How Translation Works for Existing
Programs . . . . . . . . . . . . . . . . . . 38
3.7.2 Detecting a CAP Interface for Existing
Programs . . . . . . . . . . . . . . . . . . 39
3.8 A Sample CAP Program . . . . . . . . . . . . 39
4 Other Possible Interfaces . . . . . . . . . . . . 45
4.1 The Stratus Interface . . . . . . . . . . . 45
4.1.1 Example . . . . . . . . . . . . . . . . 45
4.1.2 Critique . . . . . . . . . . . . . . . 47
4.2 The process_arguments_ Interface . . . . . . 48
4.2.1 Example . . . . . . . . . . . . . . . . 49
4.2.2 Critique . . . . . . . . . . . . . . . 50
4.3 The Ford Clic Interface . . . . . . . . . . 51
4.3.1 Example . . . . . . . . . . . . . . . . 52
4.3.2 Critique . . . . . . . . . . . . . . . 54
5 Questions for the Technical Review . . . . . . . 55
6 Other Questions . . . . . . . . . . . . . . . . . 56
6.1 Foreign Language Support . . . . . . . . . . 56
6.2 Novice vs. Expert Users . . . . . . . . . . 58
6.3 Interacting with New Error Reporting
Mechanism . . . . . . . . . . . . . . . . . . . 58
7 Future Development Plans . . . . . . . . . . . . 59
CAP: Overview MTB-646
0 PREFACE
This MTB is being written to introduce various possibilities for
enhancing the Multics command interface. Possible enhancements
include a forms interface, as well as ease-of-use additions to
our current command line interface (prompting for missing
arguments, and automatic completion of partially typed words in
the command line). The interface enhancements might be used in a
variety of operating environments, including commands and
exec_coms used at command level, subsystem requests and
exec_coms, I/O module interfaces, and the proposed Xservices
environment. Initial investigation indicates that such
enhancements must be carefully designed to properly integrate
them with existing Multics software.
This MTB does not attempt to present a design for these
enhancements. The overall objective of the MTB is to provide
information for the Multics MR11/MR12 Technical Review Board,
which will judge the merits of command interface enhancements,
and decide whether such enhancements should be pursued further.
Specific objectives include:
o Defining the audience to which command interface
enhancements are addressed. (Section 2)
o Defining the requirements for such enhancements.
(Section 2)
o Exploring how new command interfaces might interact
with the existing Multics environment, highlighting
major unresolved issues and design alternatives.
(Section 3)
o Reviewing other implementations for command interface
enhancements. (Section 4)
o Outlining a set of issues which should be addressed by
the review board. (Section 5)
o Defining a plan for future work and resource
requirements. (Section 7)
In essence, this MTB pulls together much of the preliminary work
on command interface enhancements so we can judge how to proceed
from here.
MTB-646 CAP: Overview
1 PROBLEM: MULTICS IS UNFRIENDLY
One of the biggest problems Multics faces today is its
unfriendliness. I'm stressing that ugly word "unfriendly"
because we must convince ourselves that Multics needs to be
friendlier before we can make it so. Here are some of the ways
in which Multics is unfriendly.
1.1 Multics, Unfriendly to End-Users
Multics has a good reputation as an operating system which allows
programmers to be highly productive; but it is fast gaining a bad
reputation as a system which is difficult for end users to use.
End users are people who want to do a particular job on a
computer without becoming computer experts. To such end-users,
Multics presents a bewildering number of commands; and many of
its most important commands (eg, print, list, dprint or
enter_output_request, read_mail and send_mail) are complicated by
myriads of control arguments and options. There is little
organization of commands (either in the documentation or in the
system itself) to guide the user to the command he needs. The
Multics system of forcing novice users to construct complex
command lines from memory seems a cold and unforgiving world when
compared with the command menu hierarchies, built-in prompting
and help systems becoming popular on many personal computers
FACT: Most user-friendly systems have forms or menu
interfaces to the entire system; Multics provides only a
menu interface to the xmail subsystem.
FACT: The Number One marketing requirement for MR11 is
to enhance the Ease of Use of Multics, including such
aspects as: prompting techniques for question/answer
sessions; menus; forms; decision trees; commands which
are consistent in their interactive display, and
forgiving in their response to incomplete or erroneous
input, which are tutorial in nature when the user is in
doubt, instructional when she needs clarification.
FACT: Multics has a bewildering array of commands, many
of which use differing conventions for processing their
arguments, many having overly complex or nonstandard
syntax. It is quite difficult for system programmers to
keep all of these differences and complexities straight;
it is impossible for end users. Why else would the mail
CAP: Overview MTB-646
command be used so heavily, three years after
read_mail/send_mail was released?(1)
If Multics is to survive in the competition for systems serving
end-users, we must make our system more friendly, with standard
interfaces that guide the user in doing what he wants,
self-documenting interfaces that can be used without manuals,
simple interfaces that aren't cluttered with myriads of control
arguments to confuse the end user.
1.2 Multics, Unfriendly to Programmers
Despite its record of high programmer productivity, Multics is
also not very friendly to programmers, especially to the
application programmer who is trying to interface to users on the
Unfriendly System. Today when programmers on other systems are
using automatic programming and self-learning systems to write
applications, Multics programmers must still do things the hard
way.
FACT: The new MPM Subroutines (AG94-04) is now 697
pages long (excluding I/O modules). It contains 17
subroutines for pathname manipulation, 52 subroutines
for access manipulation, 47 subroutines for segment
manipulation, 26 entries for directory manipulation, 18
subroutines for storage management/area manipulation, 16
subroutines for command environment manipulation, more
than 60 subsystem management entrypoints, 22 routines
dealing with I/O (not counting the 23 I/O module
writeups in section 3), 30 error and condition handling
subroutines, 37 data conversion subroutines, and the
list could go on. The average application program is
bewildered by such a vast array of routines. System
programmers have difficulty knowing the best way to
handle problems from one day to the next, because the
vast array above keeps changing.
_________________________________________________________________
(1) Even on System M, the use of the mail command is high. Based
upon command_usage_count data, the mail command was used
13.7% of the time:
mail invocations
------------------------------------------ = .137
rdm + sdm + prm + xmail + mail invocations
The use of Emacs MAIL/RMAIL could not be measured, and so it
isn't included in the statistics above.
MTB-646 CAP: Overview
FACT: 25% of the TRs submitted against Multics
software(1) are related to simple programming errors in
commands, active functions, requests, etc. I'm talking
about errors like misspelled control arguments, error
messages not identifying the program issuing them,
program not agreeing with the documentation, active
function results not being properly requoted, old
programs not following new standards like implicit
archive pathnames, etc. And most of these problems
never get fixed because MDC has too few resources to
perform maintenance on dormant software (software not
under active development).
If Multics is to meet its product objectives with high-quality
software, and to be able to maintain the ever growing set of
software with our limited resources, we've got to make it easier
to write user interfaces which perform according to
specification, are consistent, and reliable. The system
primitives that we have now are not adequate for this task. We
need a better way.
1.3 Is there a Solution?
The problems described above may seem to have little in common
with one another other than "unfriendliness". However, they are
all problems associated with creating or using user interfaces.
These problems exist because Multics lacks a centralized facility
for describing and implementing end-user interfaces.
In MTB-623, A Menu Interface for Multics, Noah Davids describes a
facility for organizing groups of Multics commands into menus.
This Executive Services (or Xservices) facility would provide an
alternative to the command line environment, in which the user is
presented with a menu of commands instead of having to type the
name of the desired command. It could provide environments
tailored to a particular type of user (secretary, manager,
engineer, mathematician, applications programmer, statistician,
etc) who only needs to use a few of the standard commands plus
several applications packages.
Something like Xservices would solve part of the end user
interface problem. However, once a user has selected a command
from the Xservices menu, we need user-friendly methods for the
command to obtain its input from the user. The "either menu or
prompting" facility that Xservices provides is not adequate for
many existing commands. Often neither prompting or a menu
interface is adequate to specify the needed information
_________________________________________________________________
(1) 25% is a conservative guess.
CAP: Overview MTB-646
(prompting item-by-item quickly becomes tedious, and menus aren't
flexible enough to provide variable inputs like pathnames).
Instead, we need a facility which combines the best features of
prompting and menus together into a Forms Interface. The
displayed form would have fields which the user could fill in
with prompt-type information, and mini-menus from which the user
could select options grouped together logically by function.
A forms interface facility for commands would obtain information
about fields and options to be displayed in the form from a
command Interface Description. This description would include
names of arguments accepted by the command, how each is to be
displayed in the form, how prompt fields are to be validated, how
arguments are to be converted for use by the program (eg,
applying star convention, equals convention, numeric conversion,
true/false switch conversion, etc), how results are to be
reconverted for printing/return, etc.
Multics needs a facility which can map the programmer's
description of a command or subsystem request into information
needed to display a forms interface, or into standard format
documentation for the interface. The same information could be
used by a special version of the listener/command_processor to
perform command line completion as part of standard command line
invocations of the command, and to prompt for required items
missing in the command line.
Coupled with the interface description facility would be an
argument processing facility to handle arguments in a standard
way, rather than having the hodge podge of argument handling we
have now. The central facility would define and implement "the
standard way" of handling arguments, and programmers wouldn't
have to worry about such issues. In the same vein, the central
facility could implement a generalized mechanism for user and
site-settable defaults for control arguments.
Multics needs a facility to make it easier to produce
high-quality user interfaces which work correctly and reliably,
in a user-friendly manner. In short, Multics needs a Command
Argument Processing facility (CAP), which is the subject of the
remainder of this MTB.
1.4 CAP is Only Part of the Solution
Clearly, the problems affecting Multics user friendliness cover a
broad area which includes handling of error messages and
conditions, user expertise levels, processing of arguments and
the user command interface, etc. The CAP proposal below does not
address all aspects of the general problem. Instead, it proposes
a solution for one aspect of the problem which we understand and
MTB-646 CAP: Overview
can solve. Other aspects of the general problem are not well
understood and will require more investigation before a solution
can be proposed.
This incremental attack on broad problem is a useful way of
tackling a problem which is too large to be understood as a
whole. The method involves solving parts of the problem which
are understood, then using information gained to try to better
understand the remaining parts of the problem. Our current
understanding of the overall problem suggests that all aspects of
the problem are interrelated and that solutions to the various
parts of the problem will have to be integrated into an overall
solution at some point. But trying to design an overall solution
now is not feasible, given our current limited understanding of
the problem.
CAP: Overview MTB-646
2 CAP TARGETS
Before proposing a solution to the problems above, we need a
firmer statement of what the CAP facility must be able to do, and
who its intended audience is. The requirements below are
probably not complete. I encourage you to suggest other
requirements, and to challenge requirements stated below which
you feel are inappropriate.
2.1 Audience
The features provided by the proposed CAP facility are targeted
towards a broad spectrum of users. From the user standpoint, CAP
should accommodate:
o end-users via the Xservices and forms interfaces,
o novice command line users via the command line version of
the forms interface,
o intermediate level users via forms and prompting, and
o expert command line users via command line completion.
Note that having various types of user interfaces to match user's
experience levels is often advocated in human factors
guidelines.(1) This allows users to begin using the system with
little instruction (via forms), and then to gradually learn about
faster, more direct usage methods as they gain experience and the
need arises (via command lines).
From a programming standpoint, the CAP facility itself is
directed toward both applications and system programmers who want
to provide user-friendly interfaces to their programs, interfaces
that are easier to program than by current methods, that are less
error prone, provide more standard interfaces, and that can
interface with the various user levels suggested above without
requiring additional programming effort.
2.2 Requirements for CAP
The following are a minimum set of requirements for an argument
processing facility:
_________________________________________________________________
(1) An excellent paper on this subject is: "Human Factors
Guidelines for Terminal Interface Design" by D. Verne
Morland, CACM Volume 26 Number 7, July 1983, p484.
MTB-646 CAP: Overview
o End-User interfaces provided by CAP must provide a friendly
interface to users at all experience levels. CAP interfaces
should support: the current command line interface (for use
in exec_com/absentee/abbrevs, and for intermediate and
expert users), but with prompting for omitted arguments; a
forms interface (for end users and novices); and a command
line completion capability (for experts).
o The CAP facility must be simple to program with, and much
less error prone than existing mechanisms. It must be easy
to describe an interface, and to understand and maintain the
description and its associated program.
o CAP should be useable in application programs written by our
customers, as well as in system programs. It should be
useable in programs not written in PL/I (eg, Fortran, Cobol,
exec_coms). It must be useable in commands, active
functions, subsystem requests and active requests, and I/O
modules.
o CAP interfaces should be upwards compatible with current
interfaces. We cannot afford to convert every user
interface at once. For conversion purposes, it should be
possible to provide features of CAP (eg, forms interface,
command line completion, argument validation) without
modifying the existing command. Such standalone support is
also needed to interface with third party application
programs whose code cannot be changed.
o It must be possible to implement the CAP facility in stages,
with some of the benefits available after a minimal
implementation, and other benefits achieved as additional
stages are completed. Implementation of CAP will be a large
effort, but we need some parts of the solution soon.
Several people have suggested that CAP provide a language
conversion interface so that command names and arguments could be
mapped into other languages (eg, French). While support at the
command line level is important, it is only one aspect of the
foreign language problem. Other aspects include foreign language
output and error messages, and foreign language documentation.
While CAP could help in providing foreign language command
interfaces, it is not clear whether solving just this part of the
overall problem would be a good idea. I'm sure users would be
confused by typing commands in French and getting output back in
English.
o Whatever CAP facility is chosen should provide for a future
capability to map command names, argument names and operands
into other languages.
CAP: Overview MTB-646
3 POSSIBLE DESIGN FOR CAP
Next, I'll describe a possible implementation for the CAP
facility. The purpose of this description is NOT to propose a
design for CAP, although many of the ideas below may be
incorporated into a final design. Instead, the description below
tries to introduce various aspects of command interface
enhancements to enable the reader to become familiar with the
topic, and to judge how feasible such enhancements might be, what
the benefits and drawbacks are, etc.
3.1 User Interfaces and Operating Environments
The targets for CAP mandate that the design for the CAP facility
include several different user interfaces: the normal command
line interface; a version of the command line interface with
optional command line completion(1) or prompting for missing
values; and a forms interface. Each of these interfaces is
described in more detail in section 3.3 below.
In addition, the design allows the facility to operate in several
different environments: at command level; within ssu_
subsystems; within the Xservices subsystem; within I/O modules
via support in iox_; within exec_coms, and as a subroutine called
by an application program.
The table below shows which user interfaces the design would
support in each environment. Each supported combination of user
interface and environment in marked by the number of the section
below which describes that combination.
_________________________________________________________________
(1) A fairly good description of a completion command processor
is given in MTB-586, Online Documentation for Multics,
written by Jim Siwila on June 29, 1982.
MTB-646 CAP: Overview
___________________________________________________
| COMMAND LINE INTERFACE | FORMS |
| | | | INTERFACE |
| no options | prompting | completion | |
======================================================================
|INTERACTIVE | | | | |
| command level | 3.3.1 | 3.3.2 | 3.3.3 | 3.3.4 |
| ssu_ | 3.3.5 | 3.3.5 | 3.3.5 | 3.3.6 |
| Xservices | | | | 3.3.7 |
|----------------- |------------|-----------|------------|-----------|
| KEYWORD SYNTAX | | | | |
| archive, etc | 3.3.8 | 3.3.8 | 3.3.8 | 3.3.8 |
| exec_com | 3.3.9 | 3.3.9 | 3.3.9 | 3.3.9 |
| io_call | 3.3.10 | 3.3.10 | 3.3.10 | 3.3.10 |
|----------------- |------------|-----------|------------|-----------|
| FROM SUBROUTINES | | | | |
| iox_, etc. | 3.3.11 | | | |
| other subrs | 3.3.12 | 3.3.12 | 3.3.12 | 3.3.12 |
|==================|============|===========|============|===========|
|ABSENTEE | | | | |
| command level | 3.3.13 | | | |
| ssu_ | 3.3.13 | | | |
|----------------- |------------|-----------|------------|-----------|
| KEYWORD SYNTAX | | | | |
| archive, etc | 3.3.13 | | | |
| exec_com | 3.3.13 | | | |
| io_call | 3.3.13 | | | |
|----------------- |------------|-----------|------------|-----------|
| FROM SUBROUTINES | | | | |
| iox_, etc. | 3.3.13 | | | |
| other subrs | 3.3.13 | | | |
|__________________|____________|___________|____________|___________|
3.2 Overview of the Design
A CAP facility is composed of two separate components: one
defines a language with which programmers can describe a program
interface; and a second which uses that description to provide a
variety of user interfaces to the program. The facility would
consist of the following modules:
CAP: Overview MTB-646
LANGUAGE COMPONENT:
CAP Language:
an interface description source language. This is the
language with which the programmer describes what arguments
are accepted by the command/af/request/etc, what conversions
are to be performed on the arguments, what the argument
names will be in the program, what order they are to be
passed to the command, required and default argument values,
etc.
cap: a translator for the Source Interface Description (SID)
language. The translator converts the source language
description of the program interface into binary data
tables. These tables form the Binary Interface Description
(BID) which drives the argument processing mechanism.
USER INTERFACE COMPONENT:
cap_:
a subroutine interface which uses the BID information to
process arguments given by a user in a command or request
line, or in a form. This would consist of several different
subroutine entrypoints to support the different user
interfaces (eg, command processor invocation, forms
interface, command line completion, etc).
command line completer:
a version of the video editor which performs command line
completion (on request) of tokens partially typed by the
user.
Implementation of the facility also requires changes to the
following programs:
command_processor_:
to determine if the command/af has a CAP interface, and if
so, to invoke cap_.
ssu_:
changes similar to command_processor_ causing cap_ to be
called for a request having a CAP interface.
video system:
In addition to changes needed for command line completion,
some changes may be needed to support the forms interface
for commands. For example, a way is needed for a user to
reedit an existing input line after CAP diagnoses it as
incorrect.
MTB-646 CAP: Overview
3.3 Operational Scenarios and Flow of Control
This section attempts to give the reader a better feel for the
issues involved in integrating new user interfaces into the
command environment. Section 3.1 introduced four possible user
interfaces for the CAP facility, and listed a variety of
environments in which these interfaces should work. This section
outlines how each user interface could work in the various
environments. Flow of control diagrams are included to clarify
who is calling whom.
Note that all of these ideas are sketchy attempts to insure that
each user interface could be implemented as part of the proposed
design. They do not represent an actual proposal to do it as
stated below, but instead are meant stimulate thinking about the
types of interactions that occur between the various parts of the
command environment. I invite your comments on problems with the
proposals below, and on better ways of implementing the user
interfaces.
Titles for the scenarios in section 3.3 are all of the form:
Interface Type : Operating Environment
For example, "Command Line- No options : Interactive- Command
Level". Refer to the table in section 3.1 for a quick reference
list of interfaces/environments which are discussed below.
3.3.1 COMMAND LINE- NO OPTIONS : INTERACTIVE- COMMAND LEVEL
This mode of operation represents the command/request line
interface we have today, modified to work with CAP interfaces.
The flow of control is shown below:
_____________ _____________ ________ ___________
| | | command | BID | | | |
| listener_ |-->| processor |-------->| cap_ |-->| command |
|___________| |___________| found |______| |_________|
| ___________
| | |
|------------------------->| command |
BID not found |_________|
The steps involved in calling a command or active function are as
follows:
CAP: Overview MTB-646
1) The user would type a command line with arguments.
2) The command processor would find the command name, look to
see if it has a CAP interface(1) and, if so, would invoke
cap_ with the command name typed by the user and the
argument list it would normally have passed to the command
itself.
3) cap_ would get the description of the command interface (the
BID), and parse the arguments given by the user according to
this description. Standard error diagnostics would be
issued for illegal arguments or syntax. In particular, cap_
would diagnose required arguments which are missing.
4) Once cap_ had parsed the arguments, it would construct a new
argument list containing the arguments in the order that
their corresponding parameters were defined in the BID. All
parameters described by the BID would be represented in the
new argument list. Parameters not specified by the user
would be assigned default argument values, as indicated by
the BID, or perhaps as indicated by a user- or site-settable
argument defaulting mechanism. Parameters which allow
varying numbers of arguments (such as multiple pathnames
given to a single command) would be passed as arrays, or
optionally passed one at a time to multiple invocations of
the command.
5) cap_ would convert argument values to the data type of their
corresponding parameter, as specified by the BID, with some
argument validation operations producing error diagnostics.
Possible conversions might include: expanding pathnames,
applying suffixes, applying star convention, applying equals
convention, numeric conversions, numeric range checking,
converting mode strings, converting switch control args to
bit string values, converting one of a list of possible
keywords to a case number, converting date_time_ strings,
access modes, etc. In addition, the programmer could
specify his own validation/conversion routines, perhaps
including use of active functions.
6) After cap_ has constructed the new argument list, it would
invoke the command. The command references its arguments
via named parameters in its procedure or entry statement.
This works since there are always a fixed number of
arguments in a fixed order. In essence, the interface to
the actual command procedure has become a subroutine
interface.
_________________________________________________________________
(1) How the command processor determines if the command has a CAP
interface is outlined in section 3.4.3 below.
MTB-646 CAP: Overview
7) The command can do further parameter checking, and either
diagnose errors itself (via com_err_) or return the error
information in a string provided by cap_ as part of the
calling sequence. The latter method is preferable, because
in a forms environment, it allows the user to correct the
errors by editing the form rather than having to retype the
information.
8) Assuming all parameters are correct, the command performs
whatever processing is requested, and returns to cap_ with a
0 error code (indicating successful operation). If this
were an active function invocation, the BID would designate
one of the parameters as the active function return value
and the program would assign its return value to this
parameter.
9) Upon return, cap_ would print any error diagnostics. For
active function invocations, it would convert any AF return
value from the data type associated with the BID-identified
procedure parameter back to a character string, and set the
AF return value. It would free any storage used for the
conversions (including the new arg_list storage), and return
to its caller.
3.3.2 COMMAND LINE- WITH PROMPTING : INTERACTIVE- COMMAND LEVEL
This is a modified version of the current command processor which
would prompt for required parameters when the user forgot to give
them. Prompting might be turned on by a value in the user's
default value segment, or by an installation parameter, etc.
Prompting would only occur for commands and active functions
typed at command level (ie, only when the listener called cu_$cp
to parse a command line). Commands invoked by some other program
calling cu_$cp should not involve prompting since the user has no
idea that another command is being used. Implementing this
restriction will require modifications to the cu_$cp interface.
Steps for processing a command line with prompting are identical
to those for the Command Line environment with no options (3.3.1
above) except that in step 3 above, the user would be prompted
for information missing from the command line, rather than having
missing required parameters be diagnosed as errors.
3.3.3 COMMAND LINE- WITH COMPLETION : INTERACTIVE- COMMAND LEVEL
This is a command line interface with argument completion added.
As the user was typing a command line, he could ask for help
about the command by typing the command line and an escape
sequence (eg, ESCx?). Similarly he could ask for information
CAP: Overview MTB-646
about a particular parameter. Or he could type part of an
argument value followed by an escape sequence (eg, ESCspace),
thereby asking that the remainder of the argument be supplied
automatically.
There are several ways in which a completion command processor
could be implemented. Perhaps the most straightforward would be
a version of the video system which supported the new escape
sequences.(1) Whenever one of the escape sequences was entered,
the editor routine bound to the escape sequence would pass the
entire command line typed so far, plus information on the cursor
position and function desired (eg, help or completion) to a cap_
entrypoint. This entrypoint would parse the command line
fragment using the BID, and based upon the cursor position, would
then provide help or a completion function on the specified
parameter. The command line (perhaps revised by the completion)
would be returned to the editor routine, which would make any
changes required to the actual command line seen on the screen
and return to the video editor.
completer
_____________ __________________ esc _________________ ____________
| | | iox_$get_line | seq | vid. ed. CAP | | cap_ |
| listener_ |-->| (video editor) |----->| completer req |-->| complete |
|___________| |________________| |_______________| |__________|
| _________________ ____________
| | | vid. ed. CAP | | cap_ |
once listener_ |---------------->| help req |-->| help rtn |
has read a help esc seq |_______________| |__________|
complete line
| _____________ ________ ___________
| | command | BID | | | |
|------>| processor |-------->| cap_ |-->| command |
|___________| found |______| |_________|
This process might be repeated several times on the same command
line if the user asked for several arguments to be completed, or
asked for help on several of the arguments, etc. Once the
command line was finally typed in (as indicating by the user
typing a newline character), it would be processed via CAP as
explained above in 3.3.1.
Clearly, there are several optimizations that might be performed
to avoid repeated reprocessing of the same command line.
However, since a command line completer could be implemented
_________________________________________________________________
(1) These could even be implemented as totally separate,
user-defined video editor requests.
MTB-646 CAP: Overview
exactly as described above, we need not concern ourselves with
possible performance optimizations here.
There are also some problems with the scheme proposed here. For
example, the video editor can be used for any type of input, not
just typing in command lines. So there would have to be some
method of distinguishing between input to the listener_ (command
line input) and other types of input.
It should also be clear that, once these problems are resolved,
both command line completion and prompting for missing arguments
could be performed together.
3.3.4 FORM : INTERACTIVE- COMMAND LEVEL
This mode of operation is a new type of command interface. It is
not a menu, but instead is a display of the arguments and control
arguments accepted by the command. One possible forms
implementation might begin by displaying the following form:
---- copy (version 1) ----
source_path: ___________________________________________________
target_path: ==
-acl: no
-chase: yes
-name: no
-long: yes
| RETURN | ESCx? | TAB | ESC-TAB | ESC-RETURN | ESCxq |
| end input | help | next | prev | invoke | quit |
| field | | field | field | command | |
The form consists of a title naming the command and its version,
followed by a list of arguments to be supplied, shown with
default control argument settings. At the bottom of the screen
are reminder lines indicating what keystrokes can be used to move
through the form.
When the form is first displayed, the cursor is positioned at the
first field. The user can type in or change the value of that
field, or use keystrokes to move to another field. The following
keystrokes might be defined:
CAP: Overview MTB-646
ESCx?
provide information about the field at which the cursor is
positioned. Also, ask the user if he wants additional help
about the command as a whole or about use of the forms
interface.
RETURN
ends an input field value, and moves the cursor to the next
field.
ESC-RETURN
completes input, and causes the command to be invoked with
the argument values currently displayed in the form.
TAB moves cursor to the next field. When positioned at the last
field, TAB moves the cursor back to the first field.
ESC-TAB
moves cursor back to previous field.
ESCxq
quits the forms interface without invoking the command.
other characters
When positioned at other than a type C argument, causes the
typed character to be entered as part of the field value.
Input ends for this field when RETURN is typed. The video
editor can be used to edit the value being typed.
There are (at least) 4 types of arguments which can be displayed
in the form:
A) required arguments for which there is no default. For
example, a pathname.
B) required arguments for which a default exists, and is
displayed. Arguments such as target_path in the form above
are in this category. Its default value is ==.
C) Required arguments which accept a small set of predefined
values as operands. The default value is displayed, and the
user cycles through other possible values by typing any
character (other than a control or escape sequence). An
example is "-long: yes" or "-sort: names".
One enhancement would be to add an escape sequence to
display a pop-up menu of the choices allowed (for
multi-valued arguments). This would give the user a chance
to position to a particular value and use ESCx? to get
information about that value.
MTB-646 CAP: Overview
When the cursor was positioned in this type of argument, the
reminder line might be of the form:
| n | p | m | ESCx? | TAB | ESC-TAB | ESC-RETURN | ESCxq |
| next | prev | value | help | next | prev | invoke | quit |
| value | value | menu | | field | field | command | |
and when the pop-up menu was on display, it might be:
| n | p | RETURN | ESCx? | TAB | ESC-TAB | ESC-RETURN | ESCxq |
| next | prev | select | help | next | prev | invoke | quit |
| value | value | value | | field | field | command | |
D) Optional arguments which the user can give to supply a
value. An example would be the -select argument of
display_list.
The interface described above is very similar to that used by
Stratus for their forms command interface. It is an example of
what might be done.
Remember that the purpose of analyzing argument processing with
various interfaces and environments is to determine what
functionality an argument processor must provide to operate
correctly with these interfaces/environments. The flow of
control is very similar to that for the normal command interface,
except that cap_ displays a form and the user provides command
arguments by filling in the form:
_____________ _____________ ________ ___________
| | | command | BID | | | |
| listener_ |-->| processor |-------->| cap_ |-->| command |
|___________| |___________| found |______| |_________|
/
_____________________/ ___________
/
___________ ______________ _________________
| display | | user fills | | build arglist |
| form |-->| in form |-->| from form |
|_________| |____________| |_______________|
The following steps might be used in processing a form to invoke
a command:
1) The forms interface might be invoked in any of several ways.
In the Stratus system, the user indicates that he wants a
forms invocation by typing the command name and then hitting
a special DISPLAY-FORM function key. We might use that
approach, but it would require that the command processor
CAP: Overview MTB-646
run in breakall mode, and function keys don't go well with
video editor escape sequences. However, a new escape
sequence could be added to the video editor to request that
a forms interface be used if any exists. The video editor
would have to pass this forms information along to the
command processor.
Alternately, if the user types "command_name -form", cap_
could use -form as a trigger for the forms interface. Or
there could be an option in the value segment which asks
that a form be displayed if the user types the name of a
command without any arguments.
As a fourth alternative, there could be a special cap_
entrypoint that could be called by a menu application such
as Xservices to trigger the forms interface.
2) Once the cap_ forms entry was called, it would display a
form using the information in the binary interface
description (BID). cap_ might not display the entire
description. Some arguments might be marked in the BID for
nondisplay (eg, debugging arguments). Or some might be
marked with a user experience level which is compared with
the user's actual experience level (a variable in his value
segment) to determine if the field should be displayed.
3) Once the form was filled out (ie, the use hit ESC-RETURN to
invoke the command), cap_ would extract information from the
form and would construct an argument list, as described in
3.3.1 above for the command line interface, steps 4 and 5.
4) cap_ would call the command as in section 3.3.1, step 6
above. The command would perform its function as in steps 7
and 8 above, and would return any error diagnostics to cap_
as in step 9.
5) If error diagnostics were returned by the command, cap_
would display them below the form, position to the argument
in error and allow the user to edit the argument. The user
could optionally quit rather than editing by use of an
escape sequence. If she chose to edit, she would then hit
the INVOKE escape sequence following editing to cause the
command to be reinvoked with the edited value.
Of course, both the sample form and the processing scenario above
are only possibilities. But several problems remain unanswered.
For example, at what point (and by what mechanism) does the form
get cleared from the screen so the command can display its
output? The whole issue of the forms interfaces must be
discussed in more detail in a separate MTB.
MTB-646 CAP: Overview
3.3.5 COMMAND LINE- WITH OPTIONS : INTERACTIVE- SSU_
This interface is the standard ssu_ request line interface,
modified to support command line completion and prompting for
missing arguments. Since ssu_ uses the command processor and a
version of the listener_ to process request lines, the
modifications suggested in 3.3.1, 3.3.2 and 3.3.3 above apply
equally well to ssu_.
3.3.6 FORM : INTERACTIVE- SSU_
This mode of operation would provide a new type of interface to
ssu_ subsystems. Each subsystem whose requests had CAP
interfaces would accept a standard -forms control argument
(similar to the standard -abbrev control arg). When -forms was
given, then ssu_ would present a menu of request names (similar
to the list printed by the ? request). When the user selected a
request, ssu_ would call cap_ to display the request's form using
information in the BID.
Once the form was display, processing would continue as for the
command level forms interface described in 3.3.4 above.
3.3.7 FORM : INTERACTIVE- XSERVICES
One interesting enhancement to Noah David's Xservices proposal is
to give the commands invoked from the Xservices main menu CAP
forms interfaces. In the same way that the CAP/ssu_ interface
provides a menu of requests and a forms interface to each
request, so a CAP/Xservices interface would provide a menu of
commands, and (for some of the commands) a forms interface to
each command.
In this case, Xservices would determine that the command selected
by menu option has a CAP interface, and call cap_ to display a
form for the command interface. Processing of the form could
occur as suggested in section 3.3.4 above. Flow of control is
shown below:
CAP: Overview MTB-646
_____________ _____________ ___________
| | menu option gives | | | |
| XServices |------------------->| cap_$form |-->| command |
|___________| command name |___________| |_________|
/
_________________/ ___________
/
___________ ______________ _________________
| display | | user fills | | build arglist |
| form |-->| in form |-->| from form |
|_________| |____________| |_______________|
3.3.8 COMMAND LINE OR FORM : KEYWORD SYNTAX- ARCHIVE, ETC
Rather than describing another combination of interface and
operating environment, this section describes how CAP would
handle another type of command syntax, the keyword-driven syntax
of the archive, tape_archive, manage_volume_pool, window_call,
mrds_call, dial_manager_call, memo and other similar commands.
All of these commands have a basic syntax of the form:
command_name function_keyword {arguments}
where the particular arguments and control arguments which can
follow the function_keyword depend upon the value of the keyword.
To provide a CAP interface, the BID would contain a table of
accepted function keywords, and for each function keyword it
would define an acceptable command syntax, arguments and control
arguments.
The BID information fits the command line interface described in
sections 3.3.1, 3.3.2 and 3.3.3 in an obvious way. Since the
keyword appears in the command line before other arguments and
control arguments, cap_ can validate the function keyword and
parse the remainder of the command line (or prompt for missing
values or perform command line completion) based upon the keyword
value.
For the forms interface described in section 3.3.4, the form
would initially display just the keyword argument (perhaps with a
default keyword and its operands). When the user specified (or
changed) the keyword, then the remainder of the form would be
filled in (or redisplayed) to reflect the syntax for the given
function. Once the form was filled in, processing would proceed
as in section 3.3.4 above.
MTB-646 CAP: Overview
3.3.9 COMMAND LINE OR FORM : KEYWORD SYNTAX- EXEC_COM
The exec_com is an important type of command interface, so
important that in MTB-612, Greg Baryza proposes to modify the
command processor to have exec_com files treated as commands.
For many applications, an exec_com can provide satisfactory
performance. However, the exec_com argument interface oftens
leaves much to be desired, since it is difficult to do
non-positional argument processing in an exec_com.
I propose to use the CAP command line and forms interfaces for
processing arguments to exec_com files. This can be done simply
because the exec_com command is quite similar in syntax to the
keyword-driven commands described in the previous section:
ec exec_com_file_path {ec_args}
or with Baryza's changes:
exec_com_file_path {ec_args}
The first form is quite similar to the keyword-driven syntax of
the archive command, except that instead of accepting a canned
list of keywords defined in the BID, the exec_com command uses a
searching mechanism (via exec_com search paths) to locate
exec_com files. The same search mechanism could be used to check
for a BID associated with the exec_com file, and to use
information in the BID to validate arguments to the exec_com,
prompt for missing arguments and perform command line completion,
and even to display a forms interface for the exec_com.
With a capability in cap_ to search for the exec_com file's BID,
parsing of a command line can proceed as in sections 3.3.1, 3.3.2
and 3.3.3 above. Processing of a form can proceed as in section
3.3.4. It is important to note that, whether command line or
forms interface is used, the end result is that the exec_com file
gets invoked with a fixed number of positional arguments which it
references by number. All of this could be done without changing
the exec_com command at all.
With only a small change to the exec_com command, the programming
interface for exec_coms could be improved even further. cap_
could call a new entrypoint in the exec_com command, passing both
the reordered argument list and an array of parameter names from
the BID. exec_com could preset the value for each named
parameter to be the corresponding argument in the arg list, thus
allowing the exec_com file to reference its parameters by name
(eg, &(path)) rather than by number. This would give the flow of
control shown below:
CAP: Overview MTB-646
exec_com
_____________ _____________ BID ________ ec file ________________
| | | command | found | | BID found | |
| listener_ |-->| processor |------->| cap_ |---------->| exec_com$cap |
|___________| |___________| |______| |______________|
3.3.10 COMMAND LINE OR FORM : KEYWORD SYNTAX- IO_CALL
The io_call command is an important command level interface to
the I/O system. If we are to provide CAP interfaces to I/O
modules, then the io_call command should support use of these
interfaces from command level.
Like the archive command, io_call has a keyword-driven syntax.
However, like the exec_com command, this keyword syntax cannot be
driven strictly from a list of defined keywords. The syntax also
depends upon information provided by each I/O module defining
attach, open_file, close_file, detach, modes, position, and
control options.
In order to provide CAP interfaces via the io_call command, I/O
modules will have to be converted to have CAP interfaces.
Section 3.3.11 discusses I/O module interfaces in more detail.
For now, let's assume there are BIDs describing the various
interfaces of an I/O module and see what changes would be needed
to support the io_call command. If the BID mechanism can support
the interdependencies of the io_call command, it can probably
support an arbitrarily complex set of such interdependencies.
To accommodate the interdependencies of io_call, we can
generalize the keyword syntax mechanism described in sections
3.3.8 and 3.3.9. The general syntax was:
<command_name> <function_keyword> {<args>}
A
|
SYNTAX FORK MECHANISM
where some forking mechanism is needed to determine what keywords
are allowed and the syntax of the remainder of the command line,
which depends upon the particular keyword chosen. Information
about this syntax is extracted from a BID related to the chosen
keyword.
For example, with the tape_archive command:
tape_archive keyword table_path {args}
A
|
MTB-646 CAP: Overview
list of keywords in BID
the keyword is any of the allowed archiving functions.
Presumably a list of allowed keywords would be defined in the BID
for the tape_archive command. Associated with each keyword would
be a syntax line:
tape_archive x table_path {pathnames} {-control_arg}
tape_archive a table_path pathnames {-control_args}
tape_archive t table_path {entrynames} {-control_args}
ta compact table_path
ta alter table_path warning_limit floatnum
ta alter table_path volume -number N {new_vol} {-alternate}
In fact, the alter keyword takes sub-keywords (eg, warning_limit
and volume) which further control the allowed syntax. This
points out the need for a multi-level forking mechanism that
allows the syntax of the command line to diverge at several
points, based upon use of several different keywords or names of
exec_com files, etc:
<command_name> <forkword> {<args>} {<forkword> {<args>}} ...
A A ...
|____________________|
|
MULTIPLE FORKING POINTS
This multi-level mechanism is clearly needed for the io_call
command, which supports multiple functions (attach, open,
position, get_line, put_chars, read, write, control, etc), and
also multiple I/O modules with varying attach/open/close/detach
descriptions and differing control requests.
For example, consider an attachment through mtape_:
io attach sw mtape_ m2134 -label ansi
| |
| |__ attach description based upon mtape_'s BID
|
|__ forkword from list in io_call's BID
CAP: Overview MTB-646
An open_file operation becomes more complex, because the name of
the I/O module is no longer contained in the command line.
io open_file sw sqo -extend -number 1 -name xyz_file
| | |
| | |__ allowed modes and remaining syntax from
| | I/O module's BID for the open_file handler
| | given in the IOCB.
| |
| |__ list of attached I/O switch names used to
| determine which switches can be given. Info
| in IOCB used to access I/O module's BID.
|
|__ forkword from list in io_call's BID
Thus with an adequate forking mechanism in the BID, it appears
that the io_call command could be supported by CAP without
modifications. Once the information is available to parse an
io_call command line, prompt for missing arguments, perform
completion or display an io_call form, actual processing of the
information can proceed as described in sections 3.3.1 through
3.3.4 above.
io_call
_____________ _____________ BID ________ ___________ ________
| | | command | found | | | | | |
| listener_ |-->| processor |------->| cap_ |-->| io_call |-->| iox_ |
|___________| |___________| |______| |_________| |______|
/
_____________________/ ____________
/
___________ ______________ _________________
| display | | user fills | | build arglist |
| form |-->| in form |-->| from form |
|_________| |____________| |_______________|
Form Displayed depends upon
Finding I/O Module BID
---------------------------
1) BID found: display full form with all options.
2) BID not found: display brief form with only
syntax of the given io_call operation.
3.3.11 COMMAND LINE : SUBROUTINES- IOX_
Picking up where we left off above, the iox_ subroutine checks to
see if the I/O Module has a BID, and if so, calls cap_$iox_ to
convert the argument list as described in section 3.3.1, steps 3
through 9.
MTB-646 CAP: Overview
________ ____________ ______________
| | BID | | | |
| iox_ |------->| cap_$iox |--->| I/O Module |
|______| found |__________| |____________|
| ______________
| | |
|--------------------------->| I/O Module |
BID not found |____________|
3.3.12 COMMAND LINE : OTHER SUBROUTINES
Just as the iox_ subroutine was able to call another subroutine
having a CAP interface, an arbitrary subroutine can do so as
well. An interfacing subroutine could call cap_ with the name of
the target subroutine and an argument list. If fact, the target
subroutine could be another entrypoint in the interfacing
routine. cap_ would proceed to convert the argument list and
call the target routine, as outlined in section 3.3.1, steps 3
through 9.
_____________ ________ ___________
| Interface | | | | Target |
| Routine |--->| cap_ |--->| Routine |
|___________| |______| |_________|
3.3.13 COMMAND LINE- NO OPTIONS : ABSENTEE ENVIRONMENT
CAP can work in an absentee environment just as it does in the
interactive environment. Of course, in an absentee job, there is
no user to prompt, or to use completion or fill in a form. So
only the basic CAP command line interface need be supported in
the absentee environment.
3.4 Common Aspects of the Flow of Control
It should be apparent from the user interface descriptions above
that having cap_ process arguments and then call the target
program provides an elegant mechanism for turning command
interfaces into easier-to-program subroutine interfaces. This
flow of data is the CAP-to-program flow.
Several other facilities similar to CAP have the command program
call the CAP-like facility, with the facility returning
information from the command line or form back to the program.
This is an awkward flow of control, especially when user
interfaces such as command completion and forms come into play.
CAP: Overview MTB-646
The flow of control issue is an important one. The
CAP-to-program flow is one of the most important characteristics
of CAP. It was for this reason that the flow of control
scenarios were described in so much detail in section 3.3.
Section 4 below will pursue this issue further by examining
several alternatives to CAP, comparing the CAP-to-program flow
with that of the alternatives.
3.5 Online Documentation from the BID Information
We might be able to replace info segments for commands and
subroutines having CAP interfaces by a help interface which uses
the information in the BID to document the command/subroutine.
The user interface would be through the help command:
1) The user types "help command_name" just as she does today.
2) The command processor calls cap_ to process the argument
list (since help has a CAP interface).
3) cap_ does processing similar to that described in 3.3.1
above. It finally calls the help command procedure.
4) help calls help_ with the command_name as the help topic to
be printed.
5) help_ looks for an actual info segment containing the topic,
doesn't find one, uses object search rules to see if the
topic represents a command name, and finds that the command
has a CAP interface. So help_ calls cap_ to get the binary
interface description information and formats it for
printing. The information would include most sections that
now exist in an info segment (eg, Syntax constructed from
the description, plus verbiage for Function, each item in
Arguments and Control Arguments, plus Access Required,
Notes, and perhaps even Examples).
However, there are several problems with this method of online
documentation. First is the problem of who controls the content
of the online documentation information: the documentation unit
or the programmers? Currently, the documentation unit has
complete responsibility for the content and formatting of info
segments, and no responsibility for the programs themselves.
However, if the online documentation information comes from the
BID, then the documentation unit would have to gain
responsibility over the online documentation portion of the
SID/BID, or else relinquish their online documentation
responsibilities to the programmer. Neither one of these
approaches seems correct.
MTB-646 CAP: Overview
Second, a method would have to be provided to dprint such online
documentation generated directly from the binary interface
descriptions. Currently, info segments are directly dprintable
from >doc>info, and many people take advantage of this fact by
dprinting info segments to act as their hardcopy documentation.
Because I haven't found an answer to either of these problems, I
suggest using an alternative approach: providing a command to
extract the basic syntax information from the BID in the form of
a template info segment (actually a template compin segment,
since both info segments and manual documentation is produced
from the same compin file, under the "single sourcing" policy for
documentation). The documentation unit could then fill in
information describing the function and arguments.
However, even this alternative has problems. It isn't feasible
for documentation people to fill in a new template every time a
small change is made to a command. If a new argument is added to
the command interface, it is much easier to edit the existing
compin segment that to fill in a new template compin segment.
But by doing so, we lose the direct link between the command
syntax defined in the BID and the documented syntax.
As a result, I'm not sure how to deal with the online
documentation issue. Clearly, we would be no worse off than we
are now if we continue creating documentation totally separate
from the coding effort. Also, we could easily provide a tool
like a super display_entry_point_dcl which display the full
syntax of a command, or the declaration and calling sequence of a
subroutine. Having this would make it easier for the
documentation group to check out the exact calling sequences when
it was updating the documentation.
Your ideas about how we might take better advantage of the syntax
information in the SID/BID in creating documentation would be
appreciated.
3.6 The CAP Translation Mechanism
Next, I will describe how a source interface description (SID)
for a command could be translated into the binary interface
description (BID). This description will not deal with the
details of a particular CAP description language, since the
details of the language are not important at this point in the
design process.
Before discussing the CAP command itself, let's address the goals
of the translation process, itself.
CAP: Overview MTB-646
3.6.1 GOALS FOR TRANSLATION
Given a SID and a command procedure source program written in
PL/I or Fortran, etc, we need to produce a BID translation of the
SID which can be referenced efficiently, and an object segment
compiled from the command procedure source. We basically have
two inputs and two outputs, as shown below:
x.pl1 x
-------- --------
| | | |
| | | |
-------- TRANSLATION --------
====================>
x.cap xcap_
-------- --------
| | | |
| SID | | BID |
-------- --------
3.6.1.1 BID Should Be an Object Segment
Because both the command object segment (x) and the BID are
needed at execution time, they should be closely linked in the
runtime environment. If they are stored in separate segments,
then some naming convention and/or searching convention must be
used (and enforced) to ensure that cooperating object segment and
BID are found during execution.
A simpler way of achieving this linking is to store the BID
inside of the command object segment (either by binding a
separate BID segment with the command, or by inserting the BID
information directly into the text section of the command object
segment). Either of these approaches would ensure that
equivalent versions of object and BID were used during execution.
Of course, storing the binary data in command object segment
means that the object segment will probably be somewhat larger
than it would otherwise be. However, viewed in terms of paging,
there will probably be fewer page faults if the BID is appended
to the text section of the object program, rather than being
stored in a separate data segment. Segmentation costs would be
less, as well.
The alternative approach of constructing and maintaining a data
base separate from the object segment to hold the BID adds
unneeded complexity to any CAP-like proposal. A search mechanism
different from object search rules would be needed to find
separately-stored BIDs, adding complexity to the runtime
environment. And if the BID database were something like a
MTB-646 CAP: Overview
vfile_ (to reduce segmentation overhead in storageing small BID
data segments), then we would need new tools to maintain the BID
data base, perform online installations into the database, etc.
In fact, we would undoubtedly need many separate data bases, in
order to isolate information for PSP programs from one another
for separate distribution to customers.
So one important goal is that the BID be an object segment,
stored with the command object segment, and findable via object
search rules.
3.6.1.2 Translation Mechanism Should be Simple to Use
Because one of our goals is to make it simpler to write commands
using the CAP interfaces, a second goal of the translation
mechanism is that it be easy to use. The developer shouldn't
have to go through 4 or 5 steps to obtain a working set of
modules from his source. From an ease of use standpoint, the
ideal translation mechanism would provide a single command that
compiled the CAP source and command procedure source, and
produced one or two object segments ready for binding and/or
unbound execution.
3.6.1.3 Programs Using CAP Should Be Easy to Understand
Besides making CAP simple to use, it is important that programs
implemented using CAP are easy to understand and to maintain (far
easier than could be achieved with our existing command argument
mechanisms). Essentially, the CAP language is a high-level
language for describing the user interface to a program. To
understand what input a CAP command expects and how it operates,
the reader must have both the CAP source language description of
the interface and the program source. Perhaps the easiest way to
make both available is to place both in the program source and in
the compilation listing.
3.6.1.4 The Translation Mechanism Should Be Simple to Code
When it doesn't conflict with the other goals above, we should
choose a design for the translation mechanism which is as simple
(quick) to implement as possible.
CAP: Overview MTB-646
3.6.2 POSSIBLE TRANSLATION MECHANISMS
3.6.2.1 Design 1: Separate Source and Object
Perhaps the simplest mechanism is to store the SID in a segment
separate from the command procedure, and have the cap translator
generate a CAP object segment which is bindable with the command
procedure object segment. The diagram below illustrates this for
a PL/I command procedure called x.
FULL SERVICE CAP INTERFACE
SEPARATE SOURCE & OBJECT, BINDABLE OBJECT
bound_x_
bound_x_.s.archive bound_x_.archive x
--------------- ------------------- ---------------
| | | | | |
| x.pl1 | | x | | |
| --------- | | --------- | | |
| | | | pl1 | |x: | | | x: entry |
| | |-------------->| entry | | | |
| --------- | | --------- | bind | |
| | | |------->| |
| x.cap | | xcap_ | | |
| --------- | | ------------- | | |
| | | | cap | |x_cap_info:| | | x_cap_info: |
| | |-------------->| entry | | | entry |
| | SID | | | | BID | | | ------- |
| --------- | | ------------- | | | BID | |
| | | | | ------- |
--------------- ------------------- ---------------
While the method diagrammed above is simple, the separation of
the description of the command procedure makes the code for the
total command (SID plus command procedure) harder to understand.
The program reader must access two separate segments to
understand how the command operates, or must read two separate
compilation listings, or two pages on microfiche, etc. Since our
goal is to make programs using CAP easier to write and
understand, this separation of SID from program is undesirable.
3.6.2.2 Design 2: Integrated Source and Object
A more integrated translation mechanism might make it easier to
understand and maintain a command interface coded using CAP.
Understanding and maintenance would be made easier by including
the SID with the PL/I, Fortran, exec_com, etc source for the
MTB-646 CAP: Overview
command, rather than in a separate file. The interface
description would be tied to the program as a whole and would be
visible in compilation listings of the program. This integration
of source could be achieved by placing the interface description
in the program source as a comment. The reduction_compiler uses
such a mechanism to tie the reductions to the source program, and
the mechanism has proved quite effective.
Similarly, the BID could be stored with the command procedure,
either by binding it into the same bound segment as shown in the
diagram above, or by actually placing the BID into the text
section of the command procedure object segment.
The diagram below shows what steps could be performed by the cap
command to translate the integrated PL/I source and SID for a
command procedure into a single, executable object segment.
CAP: Overview MTB-646
FULL SERVICE CAP INTERFACE
INTEGRATED SOURCE AND OBJECT
(ALL of the following steps are done by the cap command)
x.pl1.cap x.pl1 x x.list
----------- ----------- ----------- -----------
| | | | | | | |
|/* | |/* | cap | t e x t | |/* |
| ------- | copy | ------- |invokes |-- --- --| | ------- |
| | SID | | source | | SID | | pl1 | d e f s | | | SID | |
| ------- |-------->| ------- |------->|-- --- --| & | ------- |
| | */| to pdir | */| | l i n k | | */|
| | | | | |-- --- --| | |
| | | | | | s y m b | | |
-----|----- ----------- ----------- -----------
| | |
| copy SID to pdir merge BID with | | update listing
| and expand object segment | | source map; put
| CAP includes | | CAP includes
| | | in SID listing
V x V V
------- cap ------- ----------- ----------- x.list
| SID |------------->| BID | | | | |
| + | translates ------- | t e x t | |/* |
|incls| | ------- | | ------- |
------- | | BID | | | | SID | |
| ------- | | | + | |
definition for |-- --- --| | |incls| |
x_cap_info ep ---->| defs + | | ------- |
inserted in defs |-- --- --| | */|
| l i n k | | |
source map updated |-- --- --| | |
to refer to ---->| symb + | | |
x.pl1.cap & CAP ----------- -----------
include files
The scheme above has the advantages of maintaining the one-to-one
correspondence between source segments and resulting object
segments; of providing a single source module which includes both
the CAP SID and the command procedure program; of providing a
single object segment which has a accurate source map referencing
all files used in forming the object segment (including CAP
include files); of producing a listing which shows the SID with
include files expanded, plus the normal program source. The
compilation process is a simpler, one-step operation. And
because the BID is integrated with the object segment, no
additional searching is needed to find the BID once the command
procedure is found. The procedure even works for unbound
commands.
MTB-646 CAP: Overview
However, I'm sure some of the difficulties of the scheme above
are obvious, as well. The cap command would have to know how to
interface with a variety of compilers (eg, pl1, fortran, cobol,
etc). It would have to know how to add the BID and update the
source map and compiler information to an object segment, and how
to insert information about CAP include files into the listing.
Making even the smallest change to the SID would require
recompiling the PL/I or Fortran procedure as well as the SID
itself. All of these factors mean that a cap command supporting
a combined source and object translation would be much harder to
build and debug than would a command for the separate source and
object alternative.
3.6.2.3 Other Designs
Of course, other translation mechanisms are possible. A
compromise approach might integrate the source but not the object
(one source segment compiled by two separate commands, cap and
pl1, to produce two separate object segments which are bound
together). While this approach is simpler than the fully
integrated design, it is harder to use (three commands are
involved (cap, pl1 and bind) instead of one or two). Also, SID
include files wouldn't be expanded in the pl1 program compilation
listing.
It is unclear at this point how much we should pay in
implementation costs to achieve the benefits of fully-integrated
source and object. This is an issue that will be discussed in
the technical review.
3.6.3 HOW TRANSLATION WORKS FOR PROGRAMS
The basic steps in the translation process for a command
procedure are described in more detail below. The mechanism
described here is the integrated design diagrammed in section
3.6.2.2 above.
1) The cap command is invoked on a cap source program having a
suffix of lang.cap, where lang is the source language in
which the command procedure is written (eg, copy.pl1.cap for
the copy command). A sample command line for the the copy
command might be:
cap copy.pl1 -ot -map -table
CAP: Overview MTB-646
2) cap looks in copy.pl1.cap for a comment beginning "/*cap "
and ending with "end_cap*/". This special comment contains
the source language interface description to be translated
by cap into a binary interface description. cap translates
this interface description, placing it in temporary storage
in the process directory.
3) cap then copies copy.pl1.cap into a temp segment in the
process directory called copy.pl1, and invokes the PL/I
compiler to compile this segment. The object segment is
placed in the working directory. This step is similar to
what create_data_segment does in compiling a data segment.
4) Once the pl1 command returns, cap checks the compilation
severity. If errors occurred during the PL/I compilation,
cap stops.
5) If pl1 compiled the program successfully, cap copies the SID
from copy.pl1.cap into a temp segment in the process
directory, expanding any include files referenced by the
SID. It compiles the expanded SID into a BID placed in
another temp segment.
6) cap then checks the entrypoint parameter descriptors for the
copy entrypoint of the PL/I object segment against the BID
to insure that the entrypoint parameters are declared
compatibly with binary argument descriptions. The cap
translation will fail if incompatible entrypoint parameters
are found.
7) cap then appends the BID to the end of the object segment
text section, and adds a new definition of this text
entrypoint to the definitions section. The entrypoint for
the copy command might be called copy.cap_data. It updates
the source map for the object segment to include the real
pathname for the primary source module, adding any CAP
include files referenced by the SID.
8) Finally, it modifies the listing produced by the PL/I
compiler to include the complete set of source file
pathnames (adding any SID include files), and inserts copies
of the SID include files into the SID part of the listing.
Note that having the cap command add information to the text
section of the command object segment requires that object
segment sections following the text section be relocated. It may
be possible to incorporate code from the binder to perform this
relocation, or to use the proposed Object Utilities (ou_) to do
this relocation.
MTB-646 CAP: Overview
On the other hand, if it is acceptable to use an intermediate
approach of integrated source but separate object, such
relocation could be handled purely by the binder. In addition,
if cap simply created an ALM or CDS source for the BID and then
compiled it, then cap would not have to know how to manipulate
object segments at all. Such manipulation would instead be done
by the alm or create_data_segment compilers, and by the binder.
3.6.4 HOW TRANSLATION WORKS FOR EXEC_COMS
The basic steps of the translation process for an exec_com
segment would differ from those for programs in that the exec_com
segment is interpreted rather than being compiled. Therefore,
the BID must be stored separately from the exec_com segment
itself. For an exec_com segment:
1) The cap command is invoked on an exec_com source program
having a suffix of ec.cap. A sample command line might be:
cap data_file.ec
2) cap looks in data_file.ec.cap for a block of comments
beginning "&-cap" and ending with &-end_cap. cap translates
this interface description, placing it in a permanent
segment in the same directory as data_file.ec.cap. The
segment is called data_file.cap_data. Knowing that the
interface is for an exec_com, cap insures that all arguments
in the BID have a character string representation suitable
for use inside of an exec_com.
3) cap adds the name data_file.ec to data_file.ec.cap, if it is
not already there. In fact, it adds names with an ec suffix
for each exec_com entrypoint described by the BID. It also
adds these names with a cap_data suffix to the
data_file.cap_data segment.
3.6.5 DETECTING A CAP INTERFACE
When the command processor or other program wants to determine
whether a program has a CAP interface, it can call
get_entry_arg_descs_$info using a pointer to the program
entrypoint to find out how many parameters the entrypoint has.
Most existing commands are declared without parameters, but a CAP
interface would have many parameters, one for each argument given
in the BID. If parameters were present, the command processor
could call hcs_$make_ptr to see if
command_name$command_name.cap_data existed. If so, it is a CAP
interface.
CAP: Overview MTB-646
However, if CAP interface detection were integrated into the
command processor, then there would have to be a more efficient
method of detecting a CAP interface. One simple solution would
be to add a CAP bit to the entry sequence flags stored just
before the entrypoint. The cap translator could set the flag as
part of compiling the SID, and a cap_ subroutine could check the
flag setting when given an entry variable identifying the
entrypoint in question.
For subsystem requests, the subsystem request processor would
perform checks similar to those just described for the command
processor. The same technique could be used by iox_ when
interfacing with I/O modules.
For exec_com segments, cap_ could look for a segment called
&ec_dir>&ec_name.cap_data. If one is found, the exec_com has a
CAP interface.
3.7 Support for Existing Programs
Up to now, the discussion in this MTB has centered on how CAP
would be used in a totally new program or exec_com, or in a
program/exec_com that had been modified to support a CAP
interface. However, one of the requirements is to provide CAP
interfaces for existing commands or exec_coms without having to
modify them. CAP must provide such interfaces because MDC cannot
afford to modify all (or even many) of the existing commands, and
yet would like to provide CAP interfaces for most of the commands
in the MPM Commands manual. CAP should even be able to interface
with third party applications programs which cannot be modified
(because Honeywell doesn't own the source, etc).
The purpose of providing CAP interfaces for existing programs is
to allow the features of CAP (command line prompting and
completion, and forms) to be used for these existing commands,
and to provide standard command line syntax checking for the
commands.
The flow of control when invoking an existing program which has a
CAP interface would be the same as that described for new
programs in sections 3.3.1 to 3.3.4, except that instead of
changing the data type of arguments in section 3.3.1, steps 4 and
5, cap_ would rebuild the argument list as a standard command/af
argument list (char(*) arguments with a char(*) varying AF return
value). All arguments in the rebuilt list would appear in a
fixed order (as specified in the BID). cap_ would place default
argument values into the rebuilt list for control arguments not
specified by the user. This would allow defaults to be changed
in the SID without having to modify the existing program.
MTB-646 CAP: Overview
In order to adapt the CAP design to support existing programs,
two problems must be solved:
o If the integrated source and object method of
translation is adopted for CAP, then an alternate
method would have to be defined to support existing
programs. This is because the integrated method
involves compiling a command source program which
contains a SID, and inserting the resultant BID into
the command object program. However, such
compilation/insertion would not be permissable when
interfacing with existing programs which could not be
modified.
o A method would be needed to detect whether an existing
program has a CAP interface. Counting the entry
parameter descriptors of the existing program wouldn't
work, since the entrypoint in the existing command
would still be declared options(variable) with no
defined arguments.
3.7.1 HOW TRANSLATION WORKS FOR EXISTING PROGRAMS
CAP translation for existing programs could be almost identical
to the scheme for separate source and object translation
described in section 3.6.2.1. The main difference would be that
a special keyword would appear in the SID to indicate to cap_
that the target program should be passed a standard command/af
argument list. A SID which uses this keyword is called an
Existing Program SID (EPSID), and translation of an EPSID
produces an EPBID. The translation is diagrammed below.
CAP: Overview MTB-646
EXISTING PROGRAM SUPPORT
SEPARATE SOURCE & OBJECT, BINDABLE OBJECT
bound_x_
bound_x_.s.archive bound_x_.archive x
--------------- ------------------- ---------------
| | | | | |
| x.pl1 | | x | | |
| --------- | | --------- | | |
| | | | pl1 | |x: | | | x: entry |
| | |-------------->| entry | | | |
| --------- | | --------- | bind | |
| | | |------->| |
| x.cap | | xcap_ | | |
| --------- | | ------------- | | |
| | | | cap | |x_cap_info:| | | x_cap_info: |
| | |-------------->| entry | | | entry |
| | EPSID | | | | EPBID | | | -------- |
| --------- | | ------------- | | | EPBID| |
| | | | | -------- |
--------------- ------------------- ---------------
3.7.2 DETECTING A CAP INTERFACE FOR EXISTING PROGRAMS
The simplest solution for detecting that an existing program has
a CAP entrypoint is to set the CAP entry sequence flag (esf) in
entrypoints of the existing program object segment. The CAP esf
approach was described in section 3.6.5 above.
To implement this approach, the object program would have to be
available to whatever tool is used to set the CAP esf. Since the
binder has access to both the CAP EPBID and to the object
program, it seems reasonable to invent a new bindfile control
which tells the binder to turn on the CAP esf for a given set of
entrypoints. Alternately, the binder could look for BID and
EPBID segments, and use information in the BID to determine which
set of entrypoints should have their CAP esf turned on.
As a debugging aid, we might also provide a tool which would turn
on or off the CAP esf for an existing, unbound program.
3.8 A Sample CAP Program
To further appraise this proposal, it would be useful to look at
a program which uses a CAP interface. What follows is the
skeleton of the copy command, showing the sections of the program
relating to CAP. The sample of CAP language shown below is not
necessarily the language which would be used for CAP, but will
give you a feeling for how such language would be used and the
MTB-646 CAP: Overview
kinds of user interface issues which must be dealt with in a CAP
language.(1)
_________________________________________________________________
(1) Acknowledgment: the sample language shown below is derived
from a language proposed for Ford's Command Line Interface
Compiler (CLIC), another CAP-like system written by Jay
McFayden et. al. at Ford.
CAP: Overview MTB-646
/* ***********************************************************
* *
* Copyright (c) 1972 by Massachusetts Institute of *
* Technology and Honeywell Information Systems, Inc. *
* *
*********************************************************** */
/*cap
copy: command synonym (cp) version(1)
cap_version(1) language(pl1)
arguments (source_path target_path -all -acl -chase
-names -long)
help ("causes copies of specified segments and
multisegment files to be created in the specified
directories with the specified names. Access control
lists (ACLs) and multiple names are optionally
copied.");
source_path: group_arg (paths,1)
pathname count (1...*)
apply_star_convention (files, -chase)
help ("pathname of a segment or multisegment file to be
copied. The star convention is allowed. The default
action of this command when path1 specifies a link is
given below in the "Notes" section.");
target_path: group_arg (paths,2)
pathname count (0...*)
apply_equal_convention
default (==)
help ("pathname of a copy to be created from
source_path. If the last target_path argument is not
given, the copy is placed in the working directory
with the entryname of source_path. The equal
convention is allowed.");
-all: group_switch_arg
true_names (-all, -a)
true_help ("copies multiple names and ACLs.")
set_true (-acl, -names)
form (no);
-acl: switch_arg
true_names (-acl)
true_help ("copies the ACL.")
false_names (-no_acl)
false_help ("does not copy the ACL.")
default (-no_acl);
MTB-646 CAP: Overview
-names: switch_arg
true_names (-name, -nm, (-names))
true_help ("copies all names.")
false_names (-no_name, -nnm, (-no_names))
false_help ("does not copy names.")
default (-no_names);
-chase: switch_arg
true_names (-chase)
true_help ("copies the targets of links that match
source_path. See "Notes" for the default action.")
false_names (-no_chase)
false_help ("does not copy targets of links that match
source_path. See "Notes" for the default action.")
default_depends_on (source_path);
-brief: switch_arg
true_names (-brief, -bf)
true_help ("suppresses warning messages.")
false_names (-long, -lg)
false_help ("prints warning messages when necessary.")
default (-long);
"Access required": help ("Read access is required for
source_path. Status permission is required for the
directory containing source_path if the -name, -acl or
-all control argument is specified. Append permission
is required for the directory containing target_path.
Modify permission is required for the directory
containing target_path if the -name, -acl, or -all
control argument is specified.");
Notes: help ("The control arguments can appear once anywhere
in the copy command line after the command name and
apply to the entire copy command line.
The default for chasing links depends on source_path. If
source_path is not a starname, links are chased by default.
If source_path is a starname, links are not chased.");
end_cap*/
CAP: Overview MTB-646
copy:
cp: procedure (cap_info_ptr, source_path, target_path, acl_sw,
chase_sw, names_sw, brief_sw);
/* This is the standard service system command to copy a segment or
multi-segment file. This procedure also includes the move
command, which consists of a copy (with names and ACLs) followed
by a delete. Both commands take multiple arguments and the star
convention. Under control of optional arguments it will also
copy extra names and/or the ACL of the segment. */
dcl source_path (*) char(*);
dcl target_path (*) char(*);
dcl (acl_sw, chase_sw, names_sw, long_sw) bit(1);
.
.
.
do Ipath = lbound(source_path,1) to hbound(source_path,1);
call expand_pathname_ (source_path(Ipath), source_dir,
source_ent, code); /* abs path, no need to */
/* check code. */
call expand_pathname_ (target_path(Ipath), target_dir,
target_ent, code);
call copy_ (source_dir, source_ent, target_dir, "copy",
copy_options, err_sw, code);
if code = 0 then do;
if names_sw then do;
call copy_names_ (source_dir, source_ent, target_dir,
target_ent, "copy", err_sw, code);
if code ^= 0 then ...
end;
if acl_sw then do;
call copy_acl_ (source_dir, source_ent, target_dir,
target_ent, err_sw, code);
if code ^= 0 then ...
end;
end;
else ...
end;
%include cap_info;
end copy;
MTB-646 CAP: Overview
The cap_info_ptr argument shown in copy's parameter list points
to the structure shown below:
dcl 1 cap_info aligned based(cap_info_ptr),
2 cap_version char(8),
2 prog_version char(8),
2 prog_name char(32) varying,
2 invoke_type fixed bin,
2 code fixed bin(35),
2 message char(1000) varying,
2 sci_ptr ptr,
2 info_ptr ptr,
cap_info_ptr ptr,
cap_version_1 char(8) int static options(constant)
init("capv1"),
(COMMAND init(1), /* invoke_type values */
ACTIVE_FUNCTION init(2),
REQUEST init(3),
ACTIVE_REQUEST init(4)) fixed bin int static
options(constant);
We should perhaps consider a more flexible error reporting
mechanism than that shown above (for example, one similar to
ssu_$print_message). Also, I haven't yet figured out how error
reporting within the form would be integrated with ssu_ error
reporting (eg, ssu_$abort_line).
For languages other than PL/I, the information in the structure
above would have to be passed in a different way. For an
exec_com, it could be passed by having exec_com_ set named
variables containing the information in the structure (with the
exception of sci_ptr and info_ptr). For a FORTRAN program, the
pertinent variables could be passed as separate arguments to the
FORTRAN program.
CAP: Overview MTB-646
4 OTHER POSSIBLE INTERFACES
Several other mechanisms exist which provide facilities similar
to those described above. These mechanisms are at varying stages
of design and implementation. I've investigated three such
facilities and have tried to incorporate their good ideas into
the proposal above while avoiding some of their pitfalls. In the
discussions below, I will introduce these three facilities
briefly, and describe why they don't meet the requirements for a
CAP-like system, as described in section 2 above.
4.1 The Stratus Interface
The Stratus Interface is a forms or command line interface
developed by Stratus, Inc for use on their computer. Full
information on this system is available in the manuals which
describe this system. If anyone wants to review the Status
design, John Gintell has a set of manuals in Cambridge, and I
have pertinent excerpts from the manuals in Phoenix.
4.1.1 EXAMPLE
In the Stratus design, the command calls an s$parse subroutine
with pairs of arguments: a character string describing the
attributes of an argument; and a variable in which the parsed
argument value is returned.
A sample routine which illustrates the Stratus method is the
display_report command. If this command were documented in a
Multics info segment, the output of help -brief would be:
display_report report_name {-control_args}
Control arguments:
-long (default)
-no_long
-sort SORT_KEY
List of Sort Keys:
ascii (default)
alphabetical
numerical
MTB-646 CAP: Overview
The actual procedure might be structured as follows on the
Stratus system:
display_report: procedure;
dcl code bin(15),
report_name char(32) var,
long_switch bin(15),
sort_code char(16) var,
s$parse_command entry (char(*) var, bin(15),
char(*) var, char(*) var,
char(*) var, bin(15),
char(*) var, char(*) var,
char(*) var);
call s$parse_command ("display_report", code,
"report:name,required", report_name,
"switch(-long),=0", long_switch,
"option(-sort),string,length(16),
allow(ascii,alphabetical,numerical),=ascii",
sort_code,
"end");
if code ^= 0 then return;
else do;
... body of pgm which uses report_name, long_switch,
and sort_code vars
end;
end display_report;
In this example, each line following the first in the
s$parse_command call defines the specifications for an argument
(called an Argument Description Group (ADG)), until the "end"
line is reached, signalling the last specification.
Each ADG has the form:
descriptor, data_variable, {given_switch,} {default_calculator,}
where each of the above is a separate argument in the calling
sequence of s$parse_command.
The descriptor in the first ADG (the quoted string argument)
defines a "positional command argument", one of three kinds of
ADG's. "report" is a label, which is separated from other parts
of the group by a colon. The argument_type is "name". This type
controls the type of validation performed on the argument. Other
possible types include: date_time, number, pathname, starname,
string, user_name and unclaimed (a catchall type). The type is
CAP: Overview MTB-646
followed by a qualifier "required" which says that the user must
supply this argument.
The descriptor is followed by the data_variable, report_name.
This is a variable declared in the command which the parse sets
according to the arguments given by the user. In this case, if
the user typed:
display_report quarterly_stats
then report_name would have the value "quarterly_stats".
The second ADG defines a "switch command argument", the second of
the 3 kinds. The name of the switch is -long. When typed as a
command line (what STRATUS calls Linear Form), -long and -no_long
are used to set the switch. When used via CRT Form, the switch
argument is displayed as a field in the form:
-------------------- display_report --------------------
report:
-long: no
-sort: ascii
Editing controls are used to position to the -long field, and
then the user hits the CYCLE key to cycle through the possible
values (in this case "yes" or "no"). The =0 part of the
descriptor gives the default value. In this case, 0 represents
no. The default value is displayed on the CRT Form.
The third kind of ADG is the option. In the example above, -sort
is an option that requires a string operand of max length 16
chars. Allowed values for the operand are "ascii",
"alphabetical", or "numerical", with "ascii" being the default.
In the CRT Form, the user positioned at this field can cycle
through the allowed values by hitting the CYCLE key. The
sort_code variable would be assigned a value of "ascii", based
upon the CRT Form shown above. In Linear Form, if the user did
not give the -sort optional arg, then the parser would assign
"ascii" to sort_code.
When the user decides the arguments are set correctly, he hits
the ENTER key. At that point, arguments are checked for
consistency and arg values are assigned to the programs
variables.
4.1.2 CRITIQUE
The Stratus system provides a nice user interface. Because it is
a dedicated mini-computer system using Stratus-supplied
terminals, it can take full advantage of all terminal features,
MTB-646 CAP: Overview
including specially-named function keys, inverse video
highlighting of fill-in-the-blanks fields, etc. However, it has
several drawbacks.
The Stratus method requires that the command be invoked prior to
displaying the form. The user types the name of the command and
then hits a DISPLAY-FORM key on the terminal. This sets a static
bit which controls the operation of s$parse when it is called by
the command.
Also, the Stratus technique is rather awkward for the programmer,
because the full interface description is encoded as arguments in
the call to s$parse. Among other things, this means that the
programmer is constantly dealing with lengthy argument strings
and that it is impossible to include online documentation along
with the interface description.
Finally, Stratus uses a program-to-parser flow of control. This
flow is somewhat awkward. In a forms interface, the user types
the name of the command followed by the FORM key; the listener
sets a static flag indicating that a form is to be generated, and
invokes the command; the command calls s$parse to display a form;
the user fills in the form, and types the ENTER key; then,
s$parse returns the user-provided information to the command.
However, if the command detects an error in one of the argument
values, it must diagnose the error and then call s$parse again to
redisplay the form.
Support for command line completion processing would be awkward
with a program-to-parser flow for similar reasons. What you
would like with a completer is to have the completion mechanism
built into one set of modules (section 3.3.3 above proposes to
put the completion mechanism into video editor requests).
However, with the Stratus mechanism, the listener would have to
read the command name portion of the command line, invoke the
command, then the command would call s$parse to do completion on
the remainder of the command line. Putting more than one command
on a command line (via semi-colon separation) would be extremely
difficult since no one program is responsible for processing the
entire command line.
4.2 The process_arguments_ Interface
Lindsey Spratt proposed another type of interface in MTB-629.
His interface, called process_arguments_, has actually been
implemented sufficiently well to be used for parsing mtape_
attach, open, close and detach descriptions. The MTB provides
detailed information, so I'll describe his system here only
briefly.
CAP: Overview MTB-646
4.2.1 EXAMPLE
In Lindsey's system, an interface is described by a set of
control information expressed via bind_file-like keywords. A
sample control file showing part of mtape_'s attach description
is shown below:
Program_name: mtape_.attach;
Default_linear_form:
"-density 1600 -device 1 -default_volume_type ansi",
" -track 9 -wait_time 10 -error -label -no_display",
" -no_ring -no_system -no_wait";
Initial_implied_option: volume;
Option: comment;
Option_name: -comment, -com;
First_argument: comment;
Argument: comment;
Presence: required;
Validate:
"[and [ngreater [length &r1] 0] [nless [length &r1] 65]]";
Option: default_volume_type;
Option_name: -default_volume_type, -dvt;
First_argument: default_volume_type;
Argument: default_volume_type;
Presence: required;
Validate:
"[and [ngreater [length &r1] 0] [nless [length &r1] 22]]";
.
.
Option: density;
Option_name: -density, -den;
First_argument: density;
Argument: density;
Presence: required;
Validate: "[or [nequal (200 556 800 1600 6250) &r1]]";
Option: display;
Option_name: -display, -ds;
Antonym: -no_display, -nds;
Argument: flag;
Default_value: "true";
Antonym_value: "false";
Option: error;
Option_name: -error, -err;
Antonym: -no_error, -nerr;
Argument: flag;
Default_value: "true";
Antonym_value: "false";
MTB-646 CAP: Overview
.
.
End;
This source is converted to a binary description (a
print_vector_array) by the cvapd command, with the binary
description stored in a vector database.
As with Stratus, the command must be invoked prior to argument
processing. It passes its name to
process_arguments_$argument_list, along with a pointer to its
argument list, and other arguments. The process_arguments_
subroutine finds the binary interface description, uses it to
parse the argument list, and places the parsed arguments in
character string form in a resultant print_vector_array which is
returned to the command. The command can then scan through the
print_vector_array itself looking for arguments, or can call
process_arguments_$get_option_value to obtain a particular
argument.
4.2.2 CRITIQUE
The process_arguments_ approach is currently in the middle of its
implementation stage, and the design has evolved as it has come
into use in mtape_. I think the design includes some very good
ideas. These include the ability to define a hierarchy of binary
command interface descriptions, so that the site or individual
users could tailer command interfaces (eg, changing defaults)
without modifying the command procedure itself.
But overall, it does not meet several of the requirements set
forth in section 2 above.
1) Use of print_vector_arrays to hold parsed argument values
adds complexity to PL/I programs, rather than simplifying
them. The program wants to deal with the arguments as PL/I
variables. But to get a variable, it must either call a
special vector array lookup routine to assign the value of
the -brief argument to a variable; or it must walk through
the complex vector array data structure itself.
A more natural, user-friendly technique is to have the
arguments directly addressable by name as PL/I variables.
It seems like needless overhead for process_arguments_ to
construct an elaborate print_vector_array which is not
directly usable by the command, when the command really
needs PL/I variables set to the argument values. The CAP
design accomplishes this by passing the parsed argument
CAP: Overview MTB-646
values in an argument list which the command can directly
reference via parameters.
2) use of the print_vector_array implementation makes it
difficult for non-PL/I programs (eg, Fortran, Cobol, Pascal,
exec_com) to interface with process_arguments_. The
print_vector_array mechanism relies heavily on data
structures chained together using pointers. However, none
of the above languages support pointers in the PL/I sense,
and most don't support structures.
One possible way to cope with print_vector_arrays would be
to create a set of service routines (similar to ft_menu_) to
deal with print vectors from other languages. However, this
involves extra code, extra programming interfaces, and
unnecesary programming complexity.
3) this design also suffers from the flow of control problems
caused by having the command call process_arguments_. These
flow of control problems are outlined above in section
4.1.2.
4) the current implementation requires that the source language
interface description reside in a separate segment from the
PL/I source of the command. This separation makes it harder
to understand and maintain the command, and adds additional
segments to the system libraries when the command gets
installed. Section 3.6 above discussed these problems, and
stresses the importance of having the interface description
reside directly in the source segment for the command.
5) using print_vector_arrays to hold the binary interface
description and storing it in a vector database prevents the
interface description from being stored inside the command
object segment. Section 3.6 points out the maintenance
headaches this can cause.
6) use of a print_vector_array to hold the resultant processed
arguments greatly limits the processing services which
process_arguments_ can provide to the command. Print
vectors are limited to character string values, so no data
type conversions can be performed by process_arguments_.
All in all, it would appear that the vector array implementation
chosen for process_arguments_ is a serious drawback.
MTB-646 CAP: Overview
4.3 The Ford Clic Interface
Several programmers at Ford are working on a Command Line
Interface Compiler (CLIC). Programming is nearing completion. I
quote from the Clic Language Specification(1) overview:
The command line interface compiler is intended to produce a
tabular description of the command, an include file of a pl1
structure containing the complete set of possible command
arguments, and at least a skeletal runoff/compose segment to
be used in producing a help file for the command. Any of a
number of special user interfaces obtains, edits and
validates argument values, filling in the argument
structure, and then calls the appropriate processing
subroutine(s) or system commands.
The processing program receives a pointer to a filled-in
structure containing all of the argument values, with the
argument values [referenced] by name, rather than by several
pointer references. The structure is described by the
include file produced by the clic compile process, and then
compiled into the program.
Copies of the Clic Specification can be made available to those
who would like to review the full spec. Contact Gary Dixon.
4.3.1 EXAMPLE
Most of the work on the Clic system relates to defining the
source language for the interface description. The Clic language
specification for the copy command is shown below:
_________________________________________________________________
(1) The Command Line Interface Compiler Language Specification,
June 4, 1983, written by the Warranty Programming group of
the Engineering Information Systems Department, Ford Motor
Company. Designers are Jay McFayden, Mike Dean and Steve
DeDoes.
CAP: Overview MTB-646
copy: command synonym (cp)
help ("causes copies of specified segments and
multisegment files to be created in the
specified directories with the specified names.
Access control lists (ACLs) and multiple names
are optionally copied.")
args (path)
switch_args (all, acl, brief, chase, name);
path: argument domain (char(168) edit(expand_pathname))
dim(1:)
help ("from and to paths of segments to be copied from
and to.");
all: switch_arg
true_names (all)
incon (acl, no_acl, name, no_name)
help ("copies multiple names and ACLs.");
acl: switch_arg
true_names (acl)
false_names (no_acl)
default (no_acl)
incon (all)
help ("copies the ACL.");
chase: switch_arg
true_names (chase)
false_names (no_chase)
help ("copies the targets of links that match path.");
brief: switch_arg
true_names (brief, bf)
false_names (long, lg)
default (long)
help ("suppresses warning messages.");
name: switch_arg
true_names (name, nm)
false_names (no_name, nmn)
default (no_name)
incon (all)
help ("copies multiple names.");
Data type information (eg, "domain(char(168))" in the path
argument) is included in the description because the Clic
compiler translates the description above into a PL/I include
file to be used by the command, plus a binary interface
description of unspecified format. As with the Stratus and
process_arguments_ systems, the command would call a subroutine
to parse the arguments. With Clic, the argument values are
MTB-646 CAP: Overview
stored in the PL/I structure which the command passes to this
subroutine along with its argument list.
4.3.2 CRITIQUE
The Clic interface description language is a flexible,
easy-to-read language which should make interface descriptions
easy to devise, understand and maintain. The language is less
cumbersome that that used by Stratus, making it easier to use.
It is less keyword-driven than the process_arguments_ language,
making it easier to read and understand. And it seems to offer
adequate flexibility for describing command/request syntax.
On the other hand, the Clic system shares several of the problems
described for the other systems.
1) Use of a PL/I structure to hold parsed argument values makes
the Clic interface difficult to use from non-PL/I languages.
The job of the Clic translator is also made harder because
it has to know how to parse data type descriptions (eg,
"domain (char(168))") and build a PL/I structure. The CAP
facility avoids this complexity by having the PL/I compiler
translate parameter declarations into entry parameter
descriptors.
2) Clic also suffers from the control flow problems caused by
having the command call the argument parsing routine.
3) Clic does not allow the Clic source language to be stored as
part of the command source program. As pointed out in
section 3.6, this can make the command source harder to
understand and maintain.
4) The current Clic documentation does not make it clear
whether the Clic object segment is really a standard-format,
bindable object segment. If it isn't, this is another
disadvantage as pointed out in section 3.6.
CAP: Overview MTB-646
5 QUESTIONS FOR THE TECHNICAL REVIEW
The MR11/MR12 Technical Review Board should address the following
issues:
1) Is there a problem with the current Multics command/request
interfaces? If so, does Section 1 properly describe the
problem?
2) Does Section 2 define the proper audience to which
improvements in the Multics command interface should be
directed?
3) Does Section 2 define the proper set of requirements for an
improved command interface?
4) Does the design outlined in Section 3 meet the needs of the
audience, and fulfill the requirements in Section 2?
5) Is there a viable solution to the unresolved design issues?
These are:
o Does the proposed CAP design support the needed
interfaces and operating environments?
o How should documentation be handled for CAP interfaces
(Section 3.5).
o How should the mechanism for translating the SID into a
BID work (Section 3.6). Should SID be separate from
program source? Should BID be: stored in text section
of command object; be a separate, bindable object
segment; be stored in a database?
6) Can MDC afford the cost of retrofitting CAP interfaces onto
existing commands?
7) The development plan calls for CAP to be in operation for
MR12, at the earliest. Will CAP be ready soon enough to
meet marketing needs?
MTB-646 CAP: Overview
6 OTHER QUESTIONS
The questions in Section 5 address the aspects of the CAP design
which are needed to meet the major requirements of Section 2.
There are also a set of things it would be nice for CAP to do at
some point after its first release. These include:
A) The ability to map command names, argument values and
operands into a foreign language.
B) The ability to distinguish between novice and expert users,
and to present novice users with simplified command
interfaces (reduced numbers of control arguments, etc).
C) The ability to interface with a new error reporting
mechanism, should one be developed in the future.
These questions are discussed briefly below.
6.1 Foreign Language Support
As indicated in section 2.2, providing complete support for
foreign language interfaces to commands involves doing more than
changing command names, control arguments and their operands,
etc. It also involves mapping command output and error messages
into the foreign language. These are areas outside of the CAP
design.
However, CAP should be able to do the mapping of command names,
control arguments and operands. It would do this using a special
BID which maps the various command and argument names from the
foreign language into the local language. The special BID is
called a Foreign Language BID (FLBID). The diagram below shows
how the FLBID might be used:
CAP: Overview MTB-646
FOREIGN LANGUAGE TRANSLATION
S E G M E N T S I N
|
>french_sss | >sss
--------------------|------------------------
|
bound_fscom2_
copy
------------------
| copy: |
| entry |
| |
| copy_cap_info: |
copie.cap copie references | entry |
--------- cap --------- by pathname | ------- |
| FLSID |-------->| FLBID |--------------------->| BID | |
--------- --------- | ------- |
------------------
bound_pl1_
pl1
------------------
| pl1: |
| entry |
| |
| pl1_cap_info: |
pl1.cap pl1 references | entry |
--------- cap --------- by pathname | ------- |
| FLSID |-------->| FLBID |--------------------->| BID | |
--------- --------- | ------- |
------------------
Notes:
1) Object search rules would be used to select the French
version rather than the English. Thus >french_sss would
appear before >sss in the object search rules.
2) There would be two pl1.cap segments, one containing SID
(English version) and one containing the FLSID (French
version).
3) The FLBID is an object segment created by the cap
translator. This object segment has an the main entrypoint
for the command (eg, copie) which simply calls cap_ with its
argument list, and cap_ does the mapping between French (as
given in the FLBID) and English (as given in the BID).
MTB-646 CAP: Overview
4) There would be two object segments with the name pl1 (the
FLBID in >french_sss>pl1, and >sss>bound_pl1_).
5) The FLBID would reference the BID by an absolute pathname
given in the FLSID and stored by the cap translator in the
FLBID. This pathname provides the mapping between FLBID and
BID. Object search rules cannot be used for this mapping
since there are two object segments in the search rules with
the reference name pl1 (the FLBID in >french_sss>pl1, and
>sss>bound_pl1_).
6.2 Novice vs. Expert Users
In making systems easier to use, one important feature is to have
the system tailor the user interface to the user's level of
expertize. Having both a command line interface and a forms
interface provides a certain amount of tailorability. The form
provides a prompting-type interface to novice users, while
command lines provide an efficient to use interface for more
expert users.
However, for a command with many control arguments (eg,
enter_output_request or list), a novice user might be intimidated
more when presented with a many-optioned form than he would when
asked to issue the command in a command line.
Clearly, a mechanism for limiting the number of optional
arguments which are presented in a form is desirable for novice
users. The detailed mechanism for providing user expertize
levels is a subject for future study. However, a minimum
requirement for any such mechanism is that the options to be
displayed for any given expertize level be identified in the BID.
Thus, the BID should provide the capability to designate
expertize levels for arguments and control arguments.
6.3 Interacting with New Error Reporting Mechanism
There are many problems with the current Multics mechanisms for
reporting errors to the user. A discussion of these problems is
beyond the scope of this MTB. However, it is clear than any plan
to improve Multics error reporting mechanisms is likely to have
an impact on CAP. For example, to provide multi-lingual error
messages, it may be desirable to store error message text in the
BID, so that this information could be replaced in a Foreign
Language BID (FLBID). The design for CAP should provide for such
future enhancements to the error reporting mechanism, by
structuring the BID in a way which makes it easily extended for
hold new kinds of information.
CAP: Overview MTB-646
7 FUTURE DEVELOPMENT PLANS
The following steps would be necessary to pursue the design and
implementation of the CAP facility after the MR11/MR12 Technical
Review:
1) Review current commands and I/O modules in MPM Commands and
MPM Subroutines to categorize command syntax types, argument
types, and control argument types. (2 person weeks)
2) Write a CAP Language MTB describing results of the above
study. The MTB would define which syntaxes CAP would
support. These supported syntaxes would probably become
defacto standards. The MTB would define features of the SID
needed to support forms and command completion interfaces,
and would then propose a CAP language to be used in SIDs.
(4-6 person weeks)
3) Hold a design review on the CAP Language MTB. (.5 person
weeks)
4) Write a CAP Implementation MTB describing a detailed design
for implementing the command line interface (with completion
and prompting) for commands, subsystem requests, exec_coms,
I/O modules, and existing programs. The MTB might also
propose a implementation for a user-settable defaults
mechanism (eg, mtape_set_defaults). (4 person weeks)
5) Hold a design review on the CAP Implementation MTB. (.5
person weeks)
6) Implement the CAP command line interface, including
prompting, completion, builtin help facility, and
user-settable defaults. (about 30 person weeks)
7) Modify a significant number of existing commands, and some
new commands to use CAP. (5-10 person weeks, depending upon
how many commands were involved).
8) Review literature on forms interfaces. (2 person weeks)
9) Build a prototype forms interface. (4 person weeks)
10) Write a CAP Forms MTB which proposes an implementation for
the forms interface, based upon results of the literature
review and prototype studies. (4 person weeks)
11) Hold a design review on the CAP Forms MTB. (.5 person
weeks)
12) Implement the CAP forms interface. (about 15 person weeks)