MULTICS TECHNICAL BULLETIN MTB741-07
To: MTB Distribution
From: Michael Flegel
Date: April 15, 1987
Subject: MOWSE - Design Commands and Subroutines
-----------------------------------
This document provides an overview of the MOWSE environment and
the user interface. There are four MTBs that describe the design
and implementation of MOWSE and some applications that use MOWSE
facilities. The four MTBs are:
MTB-740 MOWSE Overview
MTB-741 MOWSE Design, Commands and Subroutines
MTB-742 MOWSE Background File Transfer (BFT) Facility
MTB-744 MOWSE Terminal Emulator
(rev-05): February 26, 1987. Re-implementation of mowse_io_ to
use the immediate call event channel facilities.
(rev-06): March 24, 1987. Description of mowse_utils_ and its
entry points.
(rev-07): April 14,1987. Removal of mowse_utils_; change |
mowse_io_ to receive data from tty_ rather than hcs_ |
entry points to support DSA interfaces indirectly. |
-----------------------------------
Comments on this MTB should be sent to the authors -
via Multics mail to:
Flegel@System-M
via forum on System-M to:
>udd>m>jms>mtgs>workstation_working_group (wwg)
via telephone to:
ACTC (403) 284-6400
_________________________________________________________________
Multics project internal documentation; no to be reproduced or
distributed ouside the Multics project.
MOWSE Design MTB741-07
TABLE OF CONTENTS
Section Page Subject
======= ==== =======
1 1 Overview
2 8 Establishing MOWSE
2.1 10 . . The PC Side
2.1.1 10 . . . . What the PC Looks Like With MOWSE
2.1.2 11 . . . . PC MOWSE Initialization
2.1.3 12 . . . . MOWSE Message Support
2.2 14 . . The Multics Side
2.2.1 14 . . . . What Multics Looks Like with MOWSE
2.2.2 15 . . . . Multics MOWSE Initialization
2.3 16 . . Foreground and Background Communication
2.3.1 17 . . . . Foreground Messages
2.3.2 18 . . . . Background (MOWSE) Messages
2.3.3 19 . . . . Multitasking
2.3.3.1 19 . . . . . . The Need for Multitasking
2.3.3.2 19 . . . . . . Simulating Multitasking on Multics
2.4 21 . . The Capability Address Table -- CAT
3 28 Communication Support
3.1 28 . . PC Data Handling
3.2 31 . . Multics Data Handling
3.3 37 . . The Protocol
3.3.1 37 . . . . Properties of the Protocol
3.4 43 . . The I/O Module
3.4.1 43 . . . . About mowse_io_
3.4.2 53 . . . . Reconnecting mowse_io_
4 55 Application Interface
4.1 55 . . MOWSE Considerations
4.1.1 56 . . . . Considerations for Long Messages
4.2 58 . . Subroutine Interfaces
4.3 131 . . Dedicated Minor Capability Numbers
4.4 136 . . Video Manager
5 145 MOWSE Major Capabilities
6 149 MOWSE Commands
6.1 149 . . PC Commands
6.2 152 . . Multics Commands
7 155 Installing MOWSE on the PC
8 157 Glossary
9 161 Appendix
9.1 161 . . Error Codes
MOWSE Design MTB741-07
1. Overview
Multics Online Work Station Environment (MOWSE) provides the
means for cooperating processes on Multics and a Personal
Computer to communicate with each other and to exchange requests
for information or processing. MOWSE is designed in such a way
that, given the limitations of the operating systems under which
it operates, these processes may be active in the background
while other foreground activities, not necessarily related to
MOWSE, take place.
MOWSE does not assume that one of the processes is dominant over
the other, or that certain functionality is only available on one
of the machines. Every attempt has been made during the design
to ensure that the same functionality, in terms of MOWSE
requests, exists on both machines. Naturally, the manner in
which this functionality is delivered to, or requested by, a
process depends on the operating system that governs the process.
MOWSE OPERATION
The primary functionality provided by MOWSE is the ability of
MOWSE to support background applications in addition to, and at
the same time as, foreground applications.
A foreground application is a program that has control over and
the use of a display screen and terminal keyboard. Under
Multics, all programs that make use of the user_i/o switch are by
definition foreground programs. Another characteristic of
foreground applications is that these applications are permitted
to use the processor by default, except when it is required by
the operating system (subject to possible multi-programming
considerations). Foreground applications may therefore be
permitted to loop while waiting for an event to occur.
A background application, on the other hand, must not use the
keyboard or display screen. It only is permitted to use the
processor under strictly defined circumstances (such as the
receipt of message) and then only for brief periods of time.
A MOWSE background application is not the same as a stand-alone
program operating in a multi-tasking environment in that every
program running in a multi-tasking environment has an independent
existence known to the operating system, while a MOWSE background
program is not visible to the operating system at all. A MOWSE
background application should be viewed as a subroutine that is
called by MOWSE whenever a message is received that is to be
MTB741-07 MOWSE Design
analyzed by the subroutine. As such, there can only be one
"subroutine" active at any time. Furthermore, that subroutine
must not stay active for too long, since other subroutines cannot
be called (activated) until the active subroutine returns control
to MOWSE. Of course while the background is active, the
foreground application cannot be active.
In order to distinguish between the usually understood meanings
of "applications" and "subroutines", MOWSE background
applications are referred to as "major capabilities". A major
capability differs from other application programs in that:
1) it makes its existence known to MOWSE as a major capability,
and
2) it is prepared to accept and process MOWSE messages.
A major capability can therefore be defined as an application
program that has the above characteristics. It is generally a
program that can provide processing or I/O facilities when it
receives a specifically formatted message requesting it to do so.
The result of the processing is returned to the requestor via a
formatted message.
A major capability makes itself known to MOWSE by means of a
"create_instance" subroutine call to MOWSE. In this call, the
major capability gives MOWSE a name by which the major capability
will be known to other MOWSE applications, and the name or
address of a program that is to be called whenever a message for
this major capability is received. MOWSE will return to the
calling application (now a MOWSE major capability) a major
capability number that uniquely identifies it within the MOWSE
environment. This number is used, as an address, by all major
capabilities that wish to send messages to the major capability.
The name of the major capability, its program address, and other
information is maintained by MOWSE in a Capability Access Table
(CAT).
A major capability is usually designed to perform many different
functions in a particular area. Every function that a major
capability supports is assigned a unique number, called a "minor
capability number". There are some functions (such as error
handling) that all major capabilities must be prepared to support
and these are assigned fixed minor capability numbers. Functions
that are unique to the major capability can be given any unused
minor capability numbers at the discretion of the designer of the
major capability. The numbers must, of course, be unique to the
major capability but can be the same as those used for some other
major capability.
MOWSE IMPLEMENTATION
The functionality of MOWSE is divided into four major areas:
MOWSE Design MTB741-07
1) Communications Support (PAD)
The primary function of the software in this area is to
perform the assembly and disassembly of packets that are
received or transmitted over the communications
facilities that link the two computer systems. The PAD
will also ensure that the packets are transferred error
free and will support the transparent exchange of data
streams. The PAD is activated by interrupts from the
communications hardware on the IBM PC and by timer
interrupts on Multics.
Two logical channels are provided by the PAD over the
single communications link. One channel is dedicated to
the exchange of data between the foreground programs on
either computer system, while the other channel is used
for communications between all of the background major
capabilities.
2) Scheduler
The scheduler examines all messages received from the PAD
and takes appropriate action depending on whether the
message is received over the foreground or background
channels. If a message is received over the foreground
channel, it is placed in a buffer until it is requested
by the foreground program. If the message is received
over the background channel, then the scheduler will
examine the major capability number contained in the
message. If the major capability number is that of the
MOWSE major capability, then the message is passed
directly to the MOWSE major capability software. If the
major capability number identifies a major capability in
the Capability Access Table (CAT), then the message
processing program for that major capability will be
called and passed the message. The scheduler is
activated on the PC by means of a timer interrupt and on
Multics by means of an event signalled by the packet
receiver whenever a complete message is available for the
PAD to examine.
3) Application Interface
The application interface consists of a subroutine
library that is used by both foreground and background
applications to communicate with MOWSE.
MTB741-07 MOWSE Design
On Multics, a foreground program will access this library
by means of calls through the user_i/o switch, while
background applications will access the library directly.
The Multics application interface can generate user
defined and internal messages that will be sent to other
major capabilities known to MOWSE. It can also modify
portions of MOWSE's internal tables. Since these tables
are in the user's address space on Multics, they are
subject to corruption by inappropriate actions by user
programs.
On the PC, both foreground and background applications
will access the library directly. The PC applications
interface is divided into two parts. One part, which
runs in the user's address space, is used for formatting
a MOWSE software interrupt message and then causing a
MOWSE software interrupt. The second part of the PC
application interface runs in MOWSE's address space and
is activated when a software interrupt occurs. This
second part can generate user defined and internal
messages that will be sent to other major capabilities
known to MOWSE. This part can also modify certain MOWSE
internal tables which are protected from user damage by
the fact of being located outside of user addressable
memory (if the user program is well behaved).
The PC subroutine library entry points make use of the
DOS interrupt facility to generate calls into MOWSE in
order to access MOWSE's data. The interrupt used is
specified in when MOWSE is started up on the PC. These
functions are handled in much the same manner that DOS
uses to handle its own interrupts, and in fact can be
thought of as interrupts into MOWSE. The methodology is
quite simple. Whenever an application wishes to access
one of the WS functions, it sets the AH register to the
appropriate function number (identical to the manner in
which an application invokes a DOS function). This can
be done trivially in 'C' (Lattice) by the type REGS and a
simple assignment instruction before the interrupt call.
Parameters are passed to the MOWSE function by placing
the parameters into a defined 'C' structure which the
specific MOWSE function knows about. The address of this
structure is placed into the SI register and the
structure's length is placed into the CX register.
Again, setting up the registers can be done through the
'C' type REGS. Each MOWSE function will return an error
code in the AX register, and if data is to be returned,
it will be placed into the structure which was supplied
to the function.
For example, the invocation will look as follows:
MOWSE Design MTB741-07
parameters.p1 = p1;
parameters.p2 = p2
...
input_registers.SI = &(parameters);
input_registers.CX = length(parameters);
input_registers.AH = (byte) ws_function
int86 (software_interrupt, &input_registers,
&output_registers)
return_code = output_registers.AX
The manner in which the software interrupt handler works
is:
switch (AH)
{ case 0: MOWSE_function_0();
case 1: MOWSE_function_1();
. .
. .
. .
default: Return_Error();
}
4) MOWSE Major Capability
The major portion of the MOWSE functionality is
implemented as a background major capability. As such,
it is only activated when it receives a message addressed
to it, and it supports a variety of minor capabilities
that control and support the operation of MOWSE itself as
well as other background activities. Because it is a
background major capability, it cannot loop or go blocked
at any time, it cannot consume large portions of CPU
cycles, and it cannot write messages to the display
screen or read data from the keyboard.
The MOWSE major capability is activated when it receives
messages from the MOWSE major capability on the other
system, or from the application interfaces on either
system. Similarly, it can generate messages to major
capabilities on either system or to its counterpart on
the remote system.
MTB741-07 MOWSE Design
The MOWSE Scenario Diagram:
Figure 1 illustrates how MOWSE is supported on Multics and the
PC. On the Multics system, MOWSE is implemented as an i/o module |
that is inserted between the user_i/o switch and they tty_ I/O |
module. Additional entry points are supplied that allow programs |
running on Multics to send special messages in a pre-defined
format over the communications link. In order to support the
concept of background processing, the mowse_io_ module is
activated using an immedate call event channel upon which is
generated an event whenever an EOP character (End Of Packet) is
detected. This is accomplished by setting the wakeup table to
this special character.
On the PC, MOWSE is implemented as an extension to MS-DOS that is
activated whenever an interrupt is received from the either the
communications channel or the timer. When a communications
interrupt occurs, a PAD (packet assembly/disassembly) module
reads the data from the link and assembles a complete message
from Multics. This message is placed in a holding buffer on the
PC. In order to support the concept of background processing,
the module that examines the holding buffer is activated by a
timer interrupt. This module will, when it is safe to do so,
pass the message to the application on the PC to which it is
addressed. This application does not necessarily have to be the
application that was active when the timer interrupt occurred.
The main difference between a non-MOWSE and a MOWSE environment
is that the MOWSE environment implements two logical channels
over the single physical communications link between the PC and
Multics. One of the channels, referred to as the foreground
channel, carries all of the data traffic that passes through the
user_i/o switch on Multics or originates from the PC keyboard.
The other channel, referred to as the background channel, carries
data traffic that originates from calls by background
applications to the Multics Work Station (WS) subroutine library.
MOWSE Design MTB741-07
----------------
| MOWSE |
MULTICS SIDE |---> | CAPABILITY |----|
| ---------------- |
--------------- | ---------------- |
| Foreground | | | Background | |
| Application | |---> | Application |----|
-----^--------- | ---------------- |
| | |
_____V_______ _____________ ________V____
|user_ | | | |MOWSE |
|I/O | <------------ | SCHEDULER | <------- |subroutine |
|switch | | | |library |
------------- ------------- -------------
| foreground FG and BG ^ background |
V messages out messages in | messages out V
-----------------------------------------------------------------
| COMMUNICATION MODULE |
-----------------------^-----------------------------------------
|
---V---- -------
| tty_ | <--packet--> |RS232|
-------- -^-----
PC SIDE |
-------------------------------------------V---------------------
| COMMUNICATION MODULE (PAD) |
-----------------------------------------------------------------
^ | FG/BG in ^
| V |
------------- ------------- -------------
| MOWSE | | | |MOWSE |
| subroutine|<-------------| SCHEDULER | <------- |subroutine |
| library | | | |library |
------------- ------------- -------------
^ | ^
| | |
--V------------ | --------------- |
| Foreground | | | Background | |
| Application | |---->| Application |----|
--------------- | --------------- |
| --------------- |
NOTE: ARROWS INDICATE | | MOWSE | |
DATA FLOW, |---->| CAPABILITY |----|
NOT CONTROL FLOW ---------------
Figure 1: The MOWSE Scenario
MTB741-07 MOWSE Design
2. Establishing MOWSE
This chapter gives an overview of how a user invokes the MOWSE
environment, followed by details of the actions that the MOWSE
program performs to set up the environment on the PC and on
Multics.
Invoking MOWSE:
The MOWSE environment must be established from the PC side first,
and then from the Multics side. The steps involved are
summarized as follows:
USER ACTION SYSTEM RESPONSE
1. Boot the PC using 1. The PC is now receptive to
MS-DOS v. 2.0 commands.
(or greater)
2. Type in the "MOWSE" 2. The PC now has MOWSE installed
command on the PC communication port.
3. Type in "WSTERM" command 3. The PC is now using the WSTERM
terminal emulator.
4. Log in to Multics 4. Multics is now ready to receive
commands.
5. Type in the 5. MOWSE is now completely
"attach_mowse" established.
command on Multics.
In more detail, the process is as follows:
When establishing the MOWSE environment on the PC there are
actually two stages of progression that must be made. The first
is the establishment of communication with Multics. This is done
by executing the MOWSE command on the PC (see section 7.1).
This will install the resident portion of MOWSE to function on
the communication port of the PC. Once the user has established
the MOWSE environment on the PC, (s)he may connect to Multics,
with the PC providing the functionality of a terminal through the
use of a terminal emulator designed to be used with MOWSE (ie.
WSTERM). To enter the full MOWSE environment, the user must
issue the attach_mowse command on Multics (see section 7.2).
(S)He may now run applications on Multics or the PC that use the
WS subroutine library, in addition to standard terminal I/O.
MOWSE Design MTB741-07
The scenario can be thought of as analogous to the procedure
required to initiate a telephone conversation:
- the person picks up the telephone
(PC starts MOWSE)
- the person dials a telephone number
(PC dials up to the remote system)
- the phone begins to ring
(user logs into remote system)
- the callee answers the phone
(remote system starts up MOWSE and sends special characters)
- the people talk
(remote system and PC talk through MOWSE messages)
- the people say good-bye
(remote system, then PC exit from MOWSE)
Exiting from MOWSE:
To completely exit the MOWSE environment, the user must first
exit the Multics MOWSE environment, and then the PC MOWSE
terminal environment. To exit the MOWSE environment, the user:
1. Quits MOWSE on Multics.
(detach_mowse)
2. Quits MOWSE terminal environment on the PC.
(exitmows)
MTB741-07 MOWSE Design
2.1. The PC Side
2.1.1. What the PC Looks Like With MOWSE
When MOWSE starts, a new module called MOWSE, is appended to
MS-DOS so as to permanently occupy the lowest available memory on
the PC. Several hardware and software interrupts are trapped by
the MOWSE module which provide the sole means for activating the
module. There are three main interrupts which activate MOWSE;
they are: one of the communications port hardware interrupts,
which governs the communications link to Multics; a user defined
software interrupt, which provides the means for PC resident
foreground and background applications to make requests of MOWSE;
and the SCHEDULER INTERRUPTS (consisting of a timer interrupt,
the console I/O interrupt, and the BIOS diskette service
interrupt) which handles the processing of MOWSE messages.
The following is a schematic of how MOWSE looks on the PC:
===========
message |Application|
characters ===========
<---------> RS232 <---->| PAD |
-----------
timer ----->| | message -------------
console I/O ----->| Scheduler |------------>| Application |
BIOS diskette ----->| | --------------
----------- |
| Library | software interrupt |
| Support | <-------------------
===========
| MS-DOS |
===========
MOWSE Design MTB741-07
2.1.2. PC MOWSE Initialization
The initialization of MOWSE is concerned with the following five
items:
1) Setting up the RS232 communications port
2) Setting up the interrupt vectors
3) Initializing the interrupt controller
4) Terminal emulation
5) Terminating and staying resident
In setting up the communications port MOWSE will initialize the
port to the default values described in section 7.1 or the
specified values through the "mowse" command.
The initialization of the MOWSE interrupt vectors will also be
set up so that the MOWSE interrupt handlers will respond to the
appropriate interrupts. Because DOS's 5 user interrupts are
greatly competed for by many applications, the user may specify
which user interrupt MOWSE will use for the PC software library
(see section 7.1).
There is an added facility which will allow MOWSE to examine a
start_up file which may contain the necessary communications port
initialization and interrupt vector placement. In addition, the
user will be able to start up applications through this start_up
file. These applications will be started as soon as the remote
system has entered into the MOWSE environment.
Once the interrupt vectors have been initialized, MOWSE will
enable the interrupt controller. From this point on, MOWSE is
ready on the PC side. At this point, MOWSE will "terminate and
stay resident" (thus making MOWSE a resident portion of DOS) and
go on implicitly communicating on the communciations port it has
been initiated on.
MTB741-07 MOWSE Design
2.1.3. MOWSE Message Support
The primary concern of MOWSE is to handle the transfer of
messages between loaded applications. In order to perform this
fundamental function through the MOWSE interrupt handler, MOWSE
makes use of three types of interrupts to analyze the contents of
the message queue:
- Timer Interrupt
- User I/O Request Flag
- BIOS Diskette Service Interrupt
The analysis of the message queues is done by interrupting into
MOWSE instead of automatically processing each complete message
when it arrives because MS-DOS is NOT re-entrant. Thus special
care must be taken before invoking MOWSE applications; MOWSE
applications may request MS-DOS functions, and if MOWSE calls the
application when it has interrupted MS-DOS, a call into MS-DOS
from the application will be catastrophic not only to MOWSE but
to the entire PC.
The mechanism used to perform the analysis of the queue is based
upon that used by the MS-DOS print spooler. This method involves
the use of the interrupts and an internal DOS flag which
indicates when and where DOS is active.
During MOWSE initialization, the following BIOS interrupt vectors
are set to point to the MOWSE functions:
- Interrupt 1Ch - DOS timer interrupt
- Interrupt 28h - Internal DOS interrupt flag that is
signalled when DOS is waiting for console
I/O.
- Interrupt 13h - BIOS diskette services interrupt
In addition, the address of the "in-DOS" flag is retrieved at
initialization (via DOS interrupt 34h) and saved for testing when
in the MOWSE Interrupt. The 13h interrupt is used by MOWSE
simply to set a flag when the BIOS diskette servers are active so
as to ensure that no MOWSE capability will be invoked while the
diskette servers are active.
The following is a brief description of what is done to solve the
above problems due to the non-re-entrancy of MS-DOS:
MOWSE Design MTB741-07
- If the in-MOWSE flag is set
- jump to the next user of the interrupt
- If the in-DOS flag is set
- jump to the next user of the interrupt
- If the in-SOFT flag is set
- jump to the next user of the interrupt
- Set the in-MOWSE flag
- Enable interrupts (so as to allow communications to
continue)
- Call the MOWSE SCHEDULER
- Disable the interrupts (to allow us full control over the
in-MOWSE flag)
- Reset the in-MOWSE flag
- Jump to the next user of the interrupt.
Once the MOWSE interrupt handler finds that it is capable of
calling a MOWSE application without any problem, the message
scheduler takes the appropriate action on the message determined
by the "header" of the message - "major capability" number,
"minor capability" number, and "data". These capabilities
determine where the data is to go, and what is to be done with
it.
A predefined major capability is set aside for MOWSE which allows
the MOWSE environment to coordinate the PC MOWSE and the remote
MOWSE. The remaining capabilities can be used by applications in
order to allow the application to talk between its components on
each of the systems.
These remaining capabilities are handled as Remote Procedure
Calls which transfer data and control to the application for
processing. Because DOS errors are capable of occurring inside
of the MOWSE application, MOWSE must trap DOS errors before it
makes the call into the application. This is to guarantee that
MOWSE will always regain control after the application has
completed servicing of its message (in order that MOWSE can reset
the "in-MOWSE" flag so that other messages may be serviced).
MTB741-07 MOWSE Design
2.2. The Multics Side
2.2.1. What Multics Looks Like with MOWSE
When MOWSE starts, a new I/O module, called "mowse_io_", is |
inserted beneath the user_i/o switch (by default) and the "tty_" |
I/O module: |
-<user_i/o>- syn_ -<mowse_i/o>- mowse_io_ -<mowse_tty>- tty_ |
The "mowse_io_" I/O module sends and receives packets encoded |
according to the MOWSE I/O protocol through "tty_" via the |
"mowse_tty". It sends and receives user data via the "user_i/o" |
and "mowse_i/o" switches. The transformation of user data into
packets and packets into user data is accomplished in "mowse_io_"
by calls to a set of subroutines which are the PL/1 equivalent of
the C routines on the PC which implement the MOWSE I/O protocol.
MOWSE Design MTB741-07
2.2.2. Multics MOWSE Initialization
Once MOWSE has been installed on the PC, it is ready to provide a
connection to a terminal emulator which is designed to be used
with MOWSE. Using this emulator (WSTERM), the user can then
connect to Multics and initiate MOWSE on Multics through the
command "attach_mowse" (see section 7.2). After successfully
entering MOWSE, Multics sends a RESET command to the PC MOWSE to
indicate that it has been established. This allows Multics and
the PC to communicate with each other through MOWSE messages and
its protocol (see section 4.1).
MTB741-07 MOWSE Design
2.3. Foreground and Background Communication
Messages pass between Multics and the PC through one of the two
logical channels supported by MOWSE: foreground and background.
All messages which originate or terminate at the user_i/o switch
on Multics use the foreground MOWSE channel. Messages which
originate or terminate at applications having nothing to do with
user I/O generally use the MOWSE background channel, with two
exceptions:
All background error messages are routed by MOWSE from a
background application to the foreground channel because
their ultimate destination is for user I/O (the terminal
emulator on the PC which is a foreground application).
Messages originating from the video module tc_io_ are routed
over the foreground channel as well (even though they
originate by calls through the MOWSE subroutine library)
since their ultimate destination is also for user I/O (the
terminal emulator).
All MOWSE internal messages are routed through the background
channel.
The following schematic is an example of the distinctions between
the foreground and background channels:
---------- ----------
| screen |<----| terminal | foreground channel -------
---------- | emulator |-------------+---------->| forum |
| keyboard |---->| |<----/|-----|---/|-----| |
---------- ---------- | | | -------
| | |
| | | --------
| | +-------| tc_io_ |
| | --------
background | +---+ query
or error |<-+ | | response
messages | | | |
----- | | | | -----
| bft |------+--|--|/--|------->| bft |
| |<--------+------|/-------| |
----- background channel -----
MOWSE Design MTB741-07
2.3.1. Foreground Messages
A foreground message is equivalent to the terminal data in the
standard environment. It is data that has been requested via
iox_ entrypoints on the I/O switch. Such data is of no
consequence to MOWSE; on input, it is merely passed on to the
requesting procedure; on output it is identified as a
foreground message and transmitted to the remote system. On
input, if there are no requests for terminal data, the data is
buffered until such a request is made.
How User Data is Sent to the PC:
When a Multics program wishes to send data to the PC screen,
it simply writes the data to one of the standard switches
"user_output", "error_output" or "user_i/o" with a call to
"iox_$put_chars". This presents the data to be sent to the
"put_chars" entry point of "mowse_io_". This entry point
calls a MOWSE routine that breaks the data into packet-sized
pieces. Each piece is prefixed by the appropriate capability
numbers to indicate screen output, and then passed to the PAD
for transmission to the PC.
How User Data is Obtained from the PC:
When a packet is received from the PC by the "mowse_io_" I/O
module, the data in it is extracted and dispatched according
to the specified capability numbers. If these indicate that
it is keyboard input, it is stored in a 4096 character
circular buffer maintained by "mowse_io_" for holding keyboard
input until it is requested by Multics.
The data in the circular buffer maintained by "mowse_io_" for
keyboard input is extracted in response to an "iox_$get_chars"
or an "iox_$get_line" on the "user_input", "user_i/o", or
"mowse_i/o" switches. The request may be for less data than
is in the buffer, in which case the excess data remains in the
buffer to be extracted by a subsequent call for it. If there
is insufficient data in the buffer to satisfy an input request
(i.e. there is no data for a 'get_chars' call, or no LF for a
'get_line' call), the process will be blocked pending new
input from the PC.
The circular buffer is limited to 4096 character. If the need
arises that greater than 4096 characters are to be
maintiained, mowse_io_ will leave the overflowing data in PAD
until enough space becomes available. This will eventually
cause the foreground subchannel to fill up which in turn will
exert "back pressure" on the channel until data is retrieved
from the buffer.
MTB741-07 MOWSE Design
2.3.2. Background MOWSE Messages
Messages that are passed over the background channel always
contain a major capability number. The scheduler uses this
number to determine which background capability is to receive the
message. One background capability is always present when MOWSE
is running: the MOWSE capability. This capability receives and
processes internal MOWSE messages that are used to implement and
control MOWSE operations.
Unlike foreground messages which are placed into a buffer
awaiting future retrieval by a foreground application, MOWSE
messages are interpreted and controlled by MOWSE. Receipt of a
MOWSE message requires subsequent action which depends upon the
type of message transmitted/received. Also, on input, unlike
foreground messages, MOWSE messages may occur at any time and are
not dependent on any requests for them. They are asynchronous.
This feature allows for future applications such as background
file transfer, which may periodically interrupt the foreground
task. Thus, the I/O module periodically wakes up to check for
the presence of a MOWSE message. Given this, a MOWSE message can
initiate a task that interrupts any currently active foreground
task. Upon completion, control is returned to the original task.
MOWSE Design MTB741-07
2.3.3. Multitasking
2.3.3.1. The Need for Multitasking
The natural way to implement the MOWSE I/O protocol is as a set
of cooperating tasks. Some of the tasks needed are:
(i) A packet assembler which assembles characters received
from the communications link (i.e. the FNP on Multics
and the modem port on the PC) into packets which are then
placed in a received packet queue.
(ii) A packet receiver which processes the packets in the
received packet queue. Among other things, this
processing involves exerting flow control and extracting
data. Data that is extracted is placed in a received
data queue.
(iii) A dispatcher which examines the received data queue and
forwards the data (according to the capability numbers)
to whoever is responsible for that data.
Unfortunately, neither Multics nor the PC support multitasking.
Thus we must write more complicated code that simulates a
multitasking ability. Note that no amount of "clever coding" can
remove the necessity of some kind of multitasking ability because
MOWSE requires the ability to interrupt the current foreground
process of the user (such as editing a file) to perform a remote
procedure call for a background process (such as moving files
between Multics and the PC).
2.3.3.2. Simulating Multitasking on Multics
The highest priority task is that of assembling incoming
characters into packets and storing them in the received packet
queue. This task, however, can be done by the system by
collecting the data sent from the PC into chunks (packets) and
signalling an event to the packet receiver along an immediate
call event channel (when the system detects an EOP character
indicating that a complete packet has arrived).
MTB741-07 MOWSE Design
The task of next highest priority is that of processing received
packets because it is during this processing that we first have
the opportunity to respond to messages from the PC (since this is
where we determine what those messages are). One of the most
important aspects of this processing is extracting the user data
and then storing it in the received data queue.
The task of dispatching the data in the received data queue is of
next highest importance. This, in turn, may lead to one more
task of slightly lower priority. This lowest order task would be
the response to a message which would be the invocation and
execution of background applications.
In order to get this scheme for multitasking to work, there are a
couple of other things we need to do. The first is that we must
insure that we do not allow an interrupt to occur while we are |
transmitting packets to the PC through tty_. Otherwise, the |
scheduler might start up a task that writes to the PC, in which |
case we would end up sending to the PC one packet imbedded in the |
middle of what ought to be the previous packet. This problem is |
easily avoided by masking real-time timer interrupts before |
writing to tty_ and then reinstating those interrupts when the |
writing is finished. |
|
The other is that anywhere we have to block because the PC has |
exerted back pressure (through flow control), we must block in |
such a way that when input next arrives from the PC (which we |
hope will remove the back pressure), we will immediately start up |
the packet receiver task. The packet receiver will then signal |
an event along an event channel upon which a "process" is waiting |
for the flow control to open up. |
|
For further description, please refer to Section 3.2, "Multics |
Data Handling". |
MOWSE Design MTB741-07
2.4. The Capability Address Table -- CAT
The Capability Access Tables (CATs) are tables which provide
information specific to each MOWSE application (major
capability). Such information will be used by MOWSE in
identifying a capability, determining the current status of a
capability (executing, sleeping, suspended, etc.), determining
what physical address in memory to invoke the capability, and
determining the locations of internal message buffers (so MOWSE
can handle the transfer of argument data between applications).
Two CATs will be maintained by the MOWSE on each system: one is
the "local_cat" and the other is the "remote_cat". This allows
MOWSE to know about capabilities that are available on other
systems.
MTB741-07 MOWSE Design
LOCAL CAT
The local CAT is used by MOWSE to keep track of information about
all of the applications which are loaded on the local system.
MULTICS:
02 local_cat dimension (33:64) unal,
03 flags,
04 reset bit (1) unal,
04 suspended bit (1) unal,
04 status bit (1) unal,
04 mbz1 bit (33) unal,
03 sleep_time fixed bin,
03 mcb_ptr ptr,
PC:
typedef struct local_cat_struct {
struct local_cat_struct *next_cat;
char flags;
char pad;
long sleep_time;
SREGS sregs;
REGS regs;
short bpreg;
short spreg;
int (*ws_entry)();
short waitreg;
mcb *mcb_ptr;
} local_cat;
local_cat l_CAT [NUMBER_OF_CAT_ENTRIES];
The Multics CAT is reserved space by MOWSE on the MULTICS side.
When MOWSE is initially invoked, the table is created in MOWSE's
static memory. Also, the PC CAT is reserved space by MOWSE on
the PC side. When MOWSE initially invoked, the table is created
in MOWSE's static memory. The index into each of the tables will
be represented by the major_capability_number.
Fields:
flags.reset: (MULTICS); bit 0 of flags (PC)
Determines if the capability is presently being reset; if
it is, this flag is set.
flags.suspend: (MULTICS), bit 1 of flags (PC)
Determines if the capability is presently suspended; if it
is, this flag is set.
flags.status
Determines if the capability is awaiting status
information and becomes cleared when the status
information has arrived.
MOWSE Design MTB741-07
next_cat: (PC)
Used to link CAT entries that require special proccessing;
i.e. sleeping, waiting for window to open.
sleep_time: (MULTICS,PC)
Determines if the capability is presently sleeping; if it
is, then this time will be greater than the MOWSE clock
time.
sregs: (PC)
Information about the segment registers are contained in
the local CAT on the PC side. This provides the necessary
information for accessing data (mcb) which is outside of
MOWSE space on the PC and is not required on the Multics
side.
regs: (PC)
Information about the processor registers are contained in
the local CAT on the PC side. This provides the necessary
information for reinvocations of the capability and is not
required on the Multics side.
bpreg, spreg: (PC)
Provide storage area for registers that are not contained
in the REGS structure.
ws_entry: (PC)
Contains the entry point in the user's address space of
the routine to be called whenever a message arrives.
waitreg: (PC)
Contains the value of the PC's IP (instruction pointer)
register if the application is suspended by MOWSE (i.e.
because of a window full condition).
mcb_ptr: (MULTICS, PC)
The MOWSE Control Block pointer references information
which is maintained on the application inside of the
application's data space. Such information consists of
buffer pointers, data block pointers, etc.; see the MOWSE
Control Block section ahead.
MTB741-07 MOWSE Design
REMOTE CAT
The remote CAT is used to maintain knowledge of the existence of
capabilities which are loaded on the remote system.
MULTICS:
02 remote_cat dimension (33:64) unal,
03 major_capability fixed bin,
03 capability_name char (32),
03 flags,
04 reset bit (1) unal,
04 suspended bit (1) unal,
04 sleep_time bit (1) unal,
04 mbz2 bit (33) unal,
PC:
typedef struct remote_cat_struct {
int major_capability;
char capability_name [CAPABILITY_NAME_LENGTH];
char flags;
} remote_cat;
remote_cat r_CAT [NUMBER_OF_CAT_ENTRIES];
The Multics CAT is reserved space by MOWSE on the MULTICS side.
When MOWSE is initially invoked, the table is created in MOWSE's
static memory. Also, the PC CAT is reserved space by MOWSE on
the PC side. When MOWSE initially invoked, the table is created
in MOWSE's static memory. The index into each of the tables will
be represented by the major_capability_number.
Fields:
major_capability: (MULTICS, PC)
Keeps track of the system id in the high 8 bits while the
lower 8 bits contains the major_capability_number of a
remote capability. The lower 8 bits will also form the
index into this table.
capability_name: (MULTICS, PC)
The name (character representation) of the remote
capability.
flags.reset: (MULTICS); bit 0 of flags (PC)
Indicates if the remote capability is presently being
reset; if it is, this flag is set.
flags.suspend: (MULTICS), bit 1 of flags (PC)
Indicates if the remote capability is presently been
suspended; if it is, this flag is set.
flags.sleep_time (Multics); bit 2 of flags (PC)
Indicates whether the remote capability is sleeping; if
so, the flag is set.
MOWSE Design MTB741-07
MOWSE Control Block (MCB)
As mentioned above, the data for each entry of the local CAT will
be accessible through the mcb_ptr (MOWSE_Control_Block_Pointer).
However, this structure will NOT reside in memory reserved for
MOWSE, but rather in space allocated out of the application's
data area when a call to ws_$create_instance ("cretinst") is
requested by the application. Flags, though, are kept in MOWSE
table space since this permits direct access to them and reduces
their susceptibility to corruption.
MULTICS:
dcl 01 mcb based,
02 version char (8),
02 capability_name char (32),
02 major_capability fixed bin (17),
02 inbuff_length fixed bin (17),
02 inbuff_position_index fixed bin (17),
02 inbuff_data_length fixed bin (17),
02 outbuff_length fixed bin (17),
02 mbz1 bit (36) unal,
02 entry_var entry options (variable),
02 data_block_ptr ptr,
02 inbuff ptr,
02 outbuff_list_start ptr,
02 outbuff_list_end ptr,
02 iocb_ptr ptr,
02 mowse_info_ptr ptr;
dcl 01 output_buffer based,
02 destination_system char,
02 destination_major char,
02 destination_minor char,
02 buffer_position fixed bin,
02 buffer_length fixed bin,
02 next_buffer ptr,
02 data ptr;
PC:
typedef struct mcb_struct {
char major_capability;
char system_id;
char mcb_flag;
char capability_name[CAPABILITY_NAME_LENGTH];
int (*entry_point_offset)();
int (*application_entry)();
char *data_block_ptr;
struct allocstr *inalloc;
int inbuff_length;
struct linklst *inbuff;
MTB741-07 MOWSE Design
struct allocstr *outalloc;
int outbuff_length;
struct linklst *outbuff;
double low_memory;
double high_memory;
} mcb;
Fields:
major_capability: (MULTICS, PC)
Keeps track of the system id in the high 8 bits while the
lower 8 bits contains the major_capability_number of a
remote capability. The lower 8 bits will also form the
index into the CAT.
capability_name: (MULTICS, PC)
The name (character representation) of the capability.
entry_point_offset: (PC)
The address of the pre-entry support routine which MOWSE
provides to handle certain internal MOWSE functions
specific to the application before that application is
invoked with a message.
entry_var: (MULTICS); application_entry (PC)
The memory location to call in order to invoke the
application associated with this capability. On the
MULTICS side, this field contains the entry point variable
retrieved from a call to hcs_$make_entry, with the entry
name provided in the call to ws_$create_instance. On the
PC side, this field contains the physical address (a
segment and an offset) to the routine that is to be
called.
data_block_ptr: (MULTICS, PC)
A pointer to data in the application program which is
guaranteed to be preserved when the same application
program is invoked.
flags: (PC)
Suspended, resume: flags which must be referenced by the
subroutine library to avoid address ability problems.
inalloc: (PC)
A pointer to the linked list structure used for allocating
buffers for packet assembly.
inbuff: (PC)
A pointer to the first buffer on a chain of linked
buffers.
inbuff: (MULTICS)
A pointer to an input buffer in the application's data
space into which argument data is to be passed to this
capability.
inbuff_length: (MULTICS, PC)
The length of the input message buffer.
inbuff_position_index: (MULTICS)
Keeps track of where the end of the data is currently in
the input buffer; MOWSE uses this value to determine where
to add data when concatenating protocol packets to form
MOWSE Design MTB741-07
complete messages.
inbuff_data_length: (MULTICS)
Keeps track of the amount of data currently residing in
the input buffer.
outalloc: (PC)
A pointer to the linked list structure used for allocating
buffers for packet disassembly.
outbuff: (PC)
A pointer to the first buffer on a chain of linked
buffers.
outbuff: (MULTICS)
A pointer to an output buffer in the application program's
data space from which argument data is to be retrieved
when sending messages to other applications.
outbuff_length: (MULTICS, PC)
The length of the output message buffer.
utbuff_position_index: (MULTICS)
Keeps track of where the end of the data is currently in
the output buffer; MOWSE uses this value to determine
where to get the next protocol packet when the message is
longer than one packet.
outbuff_data_length: (MULTICS)
Keeps track of the amount of data residing in the output
buffer.
mowse_iocb_ptr: (Multics)
A pointer to the I/O control block to which mowse_io_ is
attached.
low_memory: (PC)
The lowest address in memory occupied by the application.
high_memory: (PC)
The highest address in memory occupied by the application.
MTB741-07 MOWSE Design
3. Communication Support
MOWSE is an I/O module and accessory routines that inserts itself
between the terminal data switch, usually user_i/o, and the
associated I/O module, usually tty_, i.e. these need not
necessarily be the switch and I/O module, they are used for
simplicity only. In essence, it is similar to the audit_ I/O
module (ata). As such, all data entering/exiting Multics via the
communications port first passes through the MOWSE I/O module.
It contains the standard iox_ entrypoints attach, get_chars,
get_line, put_chars, modes, position, control, close and detach.
The Multics MOWSE communicates with the PC MOWSE. It is divided
into three logical layers.
1. the byte transport protocol
This layer provides packetization, error-detection, and
full-duplex communications.
2. the message transport protocol
This layer makes the size of a message independent of
packet size.
3. message handler
This layer is responsible for the different message
types within the MOWSE environment.
The byte transfer protocol deals with the physical transmission
of packets over the communications line. It along with the PC
byte protocol forms a logical layer between the systems. The
byte transport protocol communicates with the message transport
protocol when sending or receiving packets. The message
transport protocol along with the PC message transport protocol
forms a second logical layer between systems. The message
transport protocol is responsible for sending and receiving a
complete message. The message handler is responsible for
interpreting the type of message to be sent or received and the
subsequent action. For a description of the types of messages
within the MOWSE environment and the subsequent action, see
section 3.3.
3.1. PC Data Handling
Essentially, the communication port (specified at initialization
of MOWSE on the PC) interrupt handler is concerned with ALL
incoming and outgoing data and can be subdivided into four types
of communication port interrupts:
MOWSE Design MTB741-07
(i) Transmitting Data
(ii) Receiving Data
(iii) Change in Modem Status
(iv) Received Character Error or Received Break Detection
1. Transmitting Data:
The Transmitting Data interrupt type is responsible for
transmitting data (characters) from a "transmit buffer" - a 4096
character circular buffer - and is triggered whenever the PC's
transmit holding register is empty. Thus all outgoing data is to
be placed into the transmit buffer and is transmitted in turn.
The contents of the transmit buffer are arbitrary, that is,
whatever is in the buffer is indiscriminately transmitted. The
contents are the responsibility of the protocol mechanisms of
MOWSE.
The following is a more complete description of the manner in
which the transmit data interrupt operates.
- get the next character out of the transmit buffer
- place the character into the RS232 port (this has the
effect of also sending the character down the line)
- increment the pointer to the next character
2. Receiving Data:
Receiving data is responsible for getting data off of the
communications line and determining what is to be done with the
data. There are essentially two streams under which the arriving
data is classified:
(i) Raw Data Stream
(ii) Packet Data Stream
While in Raw Mode, the PC MOWSE is waiting for special characters
from the remote system (i.e. Multics) to indicate that the
remote system has established its own MOWSE environment. Until
those special characters are detected, the arriving data is
placed into a "terminal buffer" - a 4096 character circular
buffer. The terminal buffer contains all data which is destined
to be displayed on the PC's CRT and is the responsibility of an
application (usually a terminal emulator) to empty the contents
of this terminal buffer through the MOWSE library function "get
terminal data". This facility allows the user to connect to the
remote system (Multics) and set up the MOWSE environment on that
system.
MTB741-07 MOWSE Design
Once the remote system has entered into the MOWSE environment, it
sends out the special characters which the PC MOWSE is looking
for. Once these characters are detected, PC MOWSE will
automatically switch from the Raw Data Stream to the Packet Data
Stream. It is only the Packet Data Stream which is analyzed by
the Communications Protocol and will be discussed further later.
The following is a more complete description of the manner in
which the receive data interrupt operates.
HARDWARE_INTERRUPT_HANDLER:
- get the character from the RS232 port
- insert character into circular receive buffer
TIMER_INTERRUPT:
- receive a character from the circular receive buffer
- if the packet mode is on (received special characters)
- call PROTOCOL handler
- otherwise
- place the character into the terminal buffer
3. Change in Modem Status
The change in modem status type of interrupt is used to detect
changes in the modem control.
4. Received Character Error or Received Break Detection
The received character error or break detection type of interrupt
is used to detect breaks in the communication line. Character
errors are discarded as they are handled by the communications
line by an automatic retry.
MOWSE Design MTB741-07
3.2. Multics Data Handling
Whereas the PC handles incoming and outgoing data itself directly
through the RS232 port, Multics must take a somewhat different
approach to receiving and transmitting data. The following
description shows how the Multics MOWSE (mowse_io_) handles the
exchange of data with the PC MOWSE.
As discussed earlier, the data communications between Multics and
PC MOWSEs can be divided into 3 layers. Each layer will be
discussed individually below.
The following diagram gives a synopsis of how the data handling
will work on Multics:
MTB741-07 MOWSE Design
PC CONNECTION
| |
V |
tty_ |
*
A (eop wakeup)
*
(alarm reset) V (bg remote)
**************** PACKET RECEIVER **************
* * * * | * *
B C D * | * (data E
* * * * | * ready) *
V V V * | * V
TIMEOUT HANDLERS * | * PACKET DISPATCHER
| (3) * | * ^ |
| ^ ^ ^ * | * * |
| * * * (open send q)* | * E |
| B C D ************** | * * |
| ***** * +-----------+ G * |
| * * | * * |
|(alarm* * | V (bg local) * |
| set)* * | +--- I/O INTERFACE *************** |
| * * | | * ^ ^ |
| * * | | * * | |
| * * | | *******G +-----------------+ |
| * F | | (data ready?) | | |
| * * | | | | V
V * V V | +- FOREGROUND BACKGROUND
PACKET TRANSMITTER <+
* ^ |
* * |
********F |
(send q open?) |
+-------> Data Output
|
V
PC Connection
Key:
*X*> Channels, X = description index
---> Subroutine calls
Channel Descriptions:
A - Immediate call ..... data input
B - Alarm call ......... 7 second timer
C - Alarm call ......... 15 second timer
D - Alarm call ......... 30 second timer
E - Wait call .......... BG message available
F - Wait call .......... Send queue full blocking mechanism
G - Wait call .......... Foreground input blocking mechanism
MOWSE Design MTB741-07
3.1.2.1 The Byte Transport Layer
This layer is responsible for handling all character data. It is
not necessary at this point to determine whether or not the
characters to be received or transmitted are valid. But rather
to ensure that they are transmitted.
The receipt and transmission of characters is handled in the
Multics system, and mowse_io_ only sees the results of its
requests. However, mowse_io_ is capable of controlling how the
receipt and transmission of characters interfaces between itself
and the internal mechanisms of the system.
Transmission is simple: mowse_io_ merely makes a request to the
system to send characters out to the terminal. Receipt of
characters is only slightly more complicated. MOWSE is entirely
driven by data, and not only from an interactive perspective.
That is, even though the user (who provides the interactive
aspect) may be doing certain things, there is still the other
"non-visible" part which the user does not see. Because of this,
it is necessary for MOWSE to be able to receive data WHENEVER
there is data available, regardless of whether or not the process
is blocked.
In order to accomplish this feat of processing input whenever
input is available, mowse_io_ sets up an asynchronous call event
channel which is attached to the terminal (PC). This allows the
mowse_io_ handler for the input data to be invoked immediately
when there is data. But this mechanism can be improved upon
further by setting the wakeup table on the channel such that an
event will be signalled only when an EOP character (End Of
Packet) is received. The mowse_io_ handler need only awaken when
a complete protocol packet has arrived from the PC MOWSE, which
brings us to the next section of our discussion.
3.1.2.2 The Packet Transport Layer
This layer is responsible for handling data in the form of
complete packets. Its responsibilities lie in approving and
queueing input packets, and queueing and retransmitting output
packets.
3.1.2.2.1 Packet Receiver
MTB741-07 MOWSE Design
The input end of the packet transport layer lies the handles the
receipt of packets from the PC. As discussed in the previous
section, the internal mechanisms of the system handle character
data and generate events to the packet receiver whenever an EOP
character is detected. The packet receiver is responsible for
processing all of these packets: protocol control handling
(which involves resetting the timer mechanism for packet
transmission timeouts) data packet queueing for future extraction
by the background sub-channel handler (packet dispatcher), and
foreground sub-channel data handling.
In addition, it is responsible for detecting and generating
events to handlers which are awaiting certain events. Such
events include signalling to a blocked call on the get_chars
operation that foreground data has arrived, signalling to a
blocked call in the packet dispatcher (awaiting an opening of the
output packet queue) that the queue has opened up, and signalling
to the packet dispatcher that there is a message in the
background message queue.
3.1.2.2.2 Packet Transmitter
The output end of the packet transport layer handles the
transmission of packets to the PC. It's responsibilities lie in
assembling supervisor, control, and data packets, and queueing
data packets for transmission to the PC.
The transmitter is invoked through normal subroutine calls from
the packet receiver (for transmission of supervisory and control
packets), the timeout handlers (for resending data packet
requests), and the I/O interface (for the transmission of data
packets from the interactive or the background application
portion of the system). In addition, the transmitter must have
the capability of blocking itself whenever it is requested to
transmit a data packet and finds the send packet queue full for
that sub-channel. In order to do this, it makes use of a wait
event channel; the channel is sent an event (wakeup) whenever the
packet receiver detects that a sub-channel packet transmission
queue has opened up (due to an acknowledgement packet). When the
transmitter takes control after the wakeup, it continues
transmitting packets as if nothing had suspended it.
3.1.2.2.3 Timeout Handlers
The timeout handlers are responsible for guaranteeing that
transmitted packets do not sit around too long unacknowledged by
the remote. This is necessary to prevent the possibility of data
which has been transmitted being lost before it reaches the
remote.
MOWSE Design MTB741-07
In order to accomplish this, timeout handlers are set up, one for
each possible timeout period: receive timer (7 seconds), send
timer (15 seconds), and the packets which require confirmation
(30 seconds). When a timeout occurs, the handler for that
timeout performs the necessary functions (such as packet
resending) by calling the packet transmitter with the appropriate
data.
These timeout handlers do not control themselves. That is, it is
up to the packet receiver to reset the alarm mechanisms on the
appropriate handler when a requirement has been satisfied within
the allotted time. It is up to the packet transmitter to set the
alarms when it is required to begin timing for the necessary
response.
3.1.2.3 The Message Transport Layer
This layer is responsible for handling the interface between the
communications layers (byte transport and packet transport) and
the background applications and the foreground I/O. Its
responsibilities lie in forming complete messages out of packets,
handling local message transport, and foreground I/O.
3.1.2.3.1 Packet Dispatcher
The dispatcher's duties lie in the area of dispatching all
completed messages, both local and remote, to the appropriate
background applications. This can be considered to be a
"process" of its own. The only entry into the dispatcher is
through events on an event wait channel which are signalled from
either of two sources. First is the packet receiver, which
generates a wakeup on the channel when it receives a completed
packet along the background sub-channel, thus signalling to the
dispatcher that there is a data packet to assemble into a
message; second is the I/O interface (see below), which generates
a wakeup on the channel when it is requested to send a local
message to another background application.
3.1.2.3.2 I/O Module Interface
The I/O module interface provides the means for foreground
(system) and background applications to make requests of MOWSE.
The foreground is the usual set of iox_ entrypoints which are
attached to the user_i/o switch by default; the background is an
order to the iox_$control entrypoint which makes requests to
either "send_local_message" or "send_message".
MTB741-07 MOWSE Design
Since, to the foreground, the iox_$get_chars and iox_$get_line
operations must block if their conditions cannot be met (ie.
insufficient data), the module will block on an event channel
awaiting a wakeup from the packet receiver (to indicate that
there is now data to be examined and possibly returned from the
operation). In the background, when a local message is requested
to be sent, the message is placed into a queue and an event
signals to the packet dispatcher that there is a message waiting
to be processed.
MOWSE Design MTB741-07
3.3. The Protocol
This section describes how MOWSE on Multics communicates with
MOWSE on a PC. This mechanism is referred to as MOWSE I/O.
There are two parts to MOWSE I/O: the physical link and the
logical link. The physical link is simply how the PC is
physically connected to Multics. The logical link is how it
appears to MOWSE that the PC is connected to Multics.
The physical connection of the PC into Multics is that of a
terminal. It might be via direct connection to the FNP, via
dial-up through the phone system or via a network such as TYMNET.
The physical connection out of the PC is through a serial port on
the PC. The serial port is controlled by the MOWSE I/O software
on the PC.
The logical connection between Multics and a PC is substantially
different from what might be expected from the physical
connection. For example, although there is only one physical
connection, there are two independent logical connections -- one
for foreground task communications and the other for background
task communications. Moreover, each of these logical channels
appears to be more robust than the underlying physical connection
in the sense that they are virtually error free (i.e. garbage
and transmissions errors on the physical connection are detected
and corrected) and provide an 8-bit wide data path (whereas, the
physical connection may only provide a 7-bit wide data path).
It is, of course, software that accounts for the difference
between the logical and physical connections. That software is
the topic of this chapter.
3.3.1. Properties of the Protocol
MOWSE requires that the logical connection between Multics and
the PC has certain properties that are not inherent in ordinary
terminal connection to Multics. These properties are:
(i) Transparency. There needs to be a way to send all 256
8-bit codes in any order, even if the underlying medium
does not support it (e.g. as would be the case if
connected through TYMNET, which only passes 7-bit codes).
(ii) Accuracy. There needs to be an error detection and
correction mechanism so that all data (and only that
data) is received intact.
MTB741-07 MOWSE Design
(iii) Flow control. There needs to be protection against
data being transmitted faster than the receiver can deal
with it.
(iv) Duality. There needs to be two logically independent
channels to provide independent communication for
foreground and background tasks.
These properties are achieved by imposing an appropriate I/O
protocol on the physical connection, which is a simplified form
of the HDLC (High-level Data Link Control) protocol used in Level
2 of X.25. The protocol used for MOWSE I/O is packet oriented.
There are three kinds of packets used by the Protocol.
(i) Information packets, which transport the user's data.
(ii) Control packets, which transport packet control
information (e.g. retransmission requests), and
(iii) Supervisory packets, which transport link control
information (e.g. reset the link).
Information Packets
An information packet is a group of characters consisting of 5
parts:
__________________________________________________
| |
| SOP | CTL | DATA | LEN | CRC | EOP |
|__________________________________________________|
Where:
SOP is the Start-Of-Packet character. It is a single 8-bit
character which "announces" the start of a packet.
CTL is a single 8-bit character which contains all control
information for the packet.
DATA is a series of 8-bit characters representing the user's
data.
LEN is a 6-bit count of the number of characters in the entire
packet including all control characters.
CRC is the 6-bit Cyclic-Redundancy-Check based on a polynomial
of order 6 for the entire packet.
MOWSE Design MTB741-07
EOP is the End-Of-Packet character. It is a single 8-bit
character which marks the end of the packet.
Information packets are the only type of packet that have a data
field. They are also the only type of packet that is subject to
flow control (i.e the protocol is willing to accept control and
supervisory packets at any time, but information packets are only
accepted when it is convenient to do so).
Information packets are sequenced. The first information packet
has a sequence number of zero, the next has a sequence number of
one, and so on up to 3. The fourth packet again has a sequence
number of 0. In other words, the sequence numbers are cyclic
with a cycle length of four. This means that they can be encoded
in only two bits. The sequence number is part of the control
field.
The sequence numbers are used to provide two features, flow
control and missing packet detection. Flow control is
implemented by enforcing a rule that allows only a certain subset
of the available range of sequence numbers to be in use (i.e
unacknowledged) at any given time. The number of sequence
numbers that is allowable is referred to as the window size,
while the range of sequence numbers is referred to as the window.
Every time an acknowledgement is received for a packet with a
given sequence number, that sequence number is removed from the
window and a new sequence number is added to the window. The new
sequence number is one higher (in a cyclic sense) than the
highest sequence number currently in the window.
Missing packet detection is implemented by the requirement that
all information packets be sequenced, and that they be
transmitted and received in the correct order.
Control Packets
Control and supervisory packets have the same format as data
packets, except that there is no data field:
________________________________________
| |
| SOP | CTL | LEN | CRC | EOP |
|________________________________________|
MTB741-07 MOWSE Design
There are ten types of control packets, ACK, NAK, FOREGROUND
BREAK, DISCONNECT, RESET, FAST DISCONNECT, FOREGROUND BREAK
CONFIRMATION, DISCONNECT CONFIRMATION, and RESET CONFIRMATION.
ACK packets are used by the receiver of information packets to
tell the sender of the packets the sequence number of the next
packet that it expects to receive. By doing so it allows the
receiver to advance the flow control window by one.
NAK packets also contain the sequence number of the next packet
that the receiver expects to see, but the transmitter is
obligated to transmit the packet containing the sequence number
immediately. The receiver will discard all packets it receives
until the requested sequence number is seen.
FOREGROUND BREAK packets are used to signal to a Multics
foreground task (such as a PL/1 compile) a "quit" condition. The
PC sends the BREAK request to Multics where mowse_io_ determines
how the break is to be handled and sends back a BREAK
CONFIRMATION to the PC. There are two methods in which the BREAK
must be handled depending on the current state of operations in
MOWSE. The first case is when mowse_io_ receives the BREAK while
it is NOT processing any background messages (ie. a background
task is not active); under these circumstances, mowse_io_ can
immediately signal the "quit". The second case occurs when the
BREAK is received while a background task is active; in this
situation it is not possible to generate a "quit" as this will
interrupt the background job thus freezing all background
operations on Multics (background applications may NOT be
interrupted by other background applications as it may occur that
the interrupting application is the same as the interrupted, this
may NOT be allowed to occur). So mowse_io_ postpones the quit
until it determines that there is no background processing.
RESET packets are used to indicate that the sender has been
requested to clear the channel of all information packets that
are currently known to it. A RESET CONFIRMATION packet is used
by the receiver of the RESET packet to indicate that it has also
cleared the channel of all information packets that it has. A
typical reset sequence is as follows:
(i) A user requests that a reset sequence be initiated on the
local computer.
MOWSE Design MTB741-07
(ii) The local computer sends a RESET packet to the remote
computer. At the same time the local computer will
discard all information packets that it has received or
is waiting to transmit. The local computer will continue
to discard all information packets that it receives until
a RESET CONFIRMATION packet is received. When the RESET
CONFIRMATION is received, it then transmits a RESET
CONFIRMATION to the remote. In this way, both the remote
and the local computers get an acknowledgement to a reset
request.
(iii) When it receives a RESET packet, the remote computer
will discard all of its information packets and transmit
a RESET CONFIRMATION packet back to the local computer.
(iv) At this point both computers can begin to transmit
information packets again.
DISCONNECT packets are used to terminate the MOWSE environment,
ie. remove the packet communications between the computers. The
protocol of disconnection is identical to that of the RESET
protocol.
FAST DISCONNECT provides a minimal method of disconnection of the
MOWSE environment in that no confirmation FAST DISCONNECT packets
is required. When a system requests a fast disconnect from the
other system, then the initiating system is guarunteed to be out
of the MOWSE environment. This is to provide a means for the
Multics system to issue immediate disconnects to the PC system in
the event of a new_proc or logout or other fatal process
occurrences.
Packet Formats
The CTL field in every packet is used to identify the logical
channel, the packet type, and to contain the sequence numbers.
The information contained in the Ctl field has been designed to
require bit sequences that will always fall into the range of bit
sequences used by the printable ASCII character set and therefore
fall into the range of 32 (Dec.) to 126 (Dec.).
The definitions are:
Decimal Description
Range
MTB741-07 MOWSE Design
32 RESET
33 RESET CONFIRMATION
34 DISCONNECT
35 DISCONNECT CONFIRMATION
36 BREAK
37 BREAK CONFIRMATION
38-69 DATA (includes send and receive
sequence numbers)
70-77 ACK (includes receive sequence
number)
78-85 NAK (includes receive sequence
number)
86 FAST DISCONNECT
After a packet has been created and formatted by MOWSE, it is
scanned to determine if the data portion contains any character
which either cannot be sent across the communications link (e.g.
8-bit data cannot be sent across TYMNET), or is one of the
protocol control characters (such as SOP or EOP). Each such
character is replaced by a two character escape sequence
consisting of an ASCII control character followed by a printable
ASCII character.
The set of characters which must be replaced by escape sequences
can be specified by the user. Thus, if the user indicates that
the communications link will support all 256 8-bit characters,
only the protocol control characters will be replaced by escape
sequences.
The replacement of the data characters via two character escape
sequences has no effect upon the checksum of the packet: The
checksum is calculated using the original data characters rather
than those actually sent in the data field of the packet. This
allows the receiver of the packet to revert escape sequences as
soon as they are encountered.
MOWSE Design MTB741-07
3.4. The I/O Module
3.4.1. About mowse_io_
The I/O module is responsible for controlling communications
within MOWSE through data packetization as discussed in section
4.1, and dispatching received data to its appropriate handler.
An "appropriate handler" is either a user_input queue which
collects foreground data to be retrieved through calls to
iox_$get_chars and iox_$get_line, or background applications
which process background data packets.
ATTACH DESCRIPTION:
mowse_io_ {switch_name} |
ARGUMENTS:
switch_name |
Is the name of the io switch under which mowse_io_ will be |
attached. If none is given, then mowse_io_ will attempt to |
attach itself next to tty_. |
OPENING:
The opening modes supported are stream_input_output.
EDITING:
Editing is not the responsibility of mowse_io_, it merely passes
on editing requests to the PC terminal manager. For further
information, refer to WSTERM.info.
BUFFERING:
This I/O module is responsible for the manipulation of two
logical subchannels of data communications: foreground and
background. Both of these subchannels will block awaiting the
capability of transmitting characters. Input of characters is
performed once every second on a timer where the input is sorted
out and placed into the appropriate channel buffer.
Retrieval and transmission of characters along the foreground
subchannel will block to the calling routine awaiting the
availability of characters or the capability of transmission of
characters.
ENTRY POINTS:
MTB741-07 MOWSE Design
The following is a list of all entry points in mowse_io_
available through calls to iox_ entrypoints.
attach detach_iocb modes
close get_chars open
control get_line put_chars
GET CHARS OPERATION:
The get_chars operation reads as many characters as are
available, up to but not exceeding the number requested by the
caller. No error code is returned if the number read is less
than the number requested, at least one character is always
returned. The characters read may comprise only a partial input
line, or several input lines; no assumptions can be made in this
regard.
GET LINE OPERATION:
The get_line operation is supported. No error code is returned
if the read operation occurs with the input buffer length at
zero. For further explanation, see the iox_$get_line entry.
PUT CHARS OPERATION:
The put_chars operation is supported (see the iox_$put_chars
entry).
CONTROL OPERATION
Control orders accessible through calls to iox_$control provide
the necessary additional functionality to the I/O module. These
control orders allow the caller to access functionality specific
to the I/O module. With mowse_io_ it has been necessary to
provide control orders which are "visible" to the user as well as
specialized orders which are to remain undocumented to the user.
Following is a list of the control orders which are supported by
mowse_io_ and require specific handling by mowse_io_:
LIST OF VISIBLE ORDERS:
For complete description of those orders not described, please
refer to the appropriate Multics documnetation.
MOWSE Design MTB741-07
abort read_status
debug_off resetread
debug_on resetwrite
get_editing_chars set_default_modes
get_input_conversion set_editing_chars
line_length set_input_conversion
printer_off set_term_type
printer_on trace_off
quit_disable trace_on
quit_enable write_status
debug_on
debug_off
These orders allow all communications packets being sent and
received both locally and remotely (PC) by Multics to be
recorded into a specified Multics segment. The info_ptr
points to the structure below (defined in
mowse_io_control_info.incl.pl1) or can be null in which case
the segment name "debug.mowse_io_" is default.
dcl 01 mowse_io_debug_info based (mowse_io_debug_info_ptr),
02 version char (8),
02 segment_name char (32) var;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
segment_name
Is the name of the segment in the current working
directory to which the packets will be recorded.
get_input_conversion
set_input_conversion
Input translation by MOWSE is performed by WSTERM and will
accept only one escape character, all other changes will be
recorded and installed into tty_ when mowse_i/o is detached
(see tty_).
printer_off
printer_on
These orders allow the printer facility to be turned on and
off in order to specify read unechoed terminal characters.
When these orders are specified, a control message is
formulated to the PC MOWSE of the type PON/POFF. Please refer
to MTB744 for further detail.
MTB741-07 MOWSE Design
trace_on
trace_off
These orders allow all messages being sent and received by an
application to be recorded in a specified Multics segment.
The info_ptr points to the structure below (defined in
mowse_io_control_info.incl.pl1), or can be null in which case
the default segment name will be "trace.mowse_io_".
dcl 01 mowse_io_debug_info based (mowse_io_debug_info_ptr),
02 version char (8),
02 segment_name char (32) var;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
segment_name
Is the name of the segment in the current working
directory to which the messages will be recorded.
LIST OF NON-VISIBLE CONTROL ORDERS:
These control orders are required by ws_ and other procedures
which require access to functionality specific to the support of
MOWSE as a whole:
flush_subchannel reconnection get_terminal_emulator_state
send_local_message get_mowse_info send_message put_to_sleep
store_mowse_info
flush_subchannel
Return to the caller when the specified subchannel has been
emptied by mowse_io_. The info_ptr points to the following
structure (defined in mowse_io_control_info.incl.pl1).
dcl 01 mowse_io_flush_subchannel
based (mowse_io_flush_subchannel_info_ptr),
02 version char (8),
02 subchannel fixed bin;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
MOWSE Design MTB741-07
subchannel
Is the subchannel to be flushed. It must be either FG
(foreground) or BG (background) (defined in
mowse_messages.incl.pl1).
get_terminal_emulator_state
Provides information as to whether or not the MOWSE terminal
emulator WSTERM is currently operating under MOWSE. The
info_ptr points to the following structure (defined in
mowse_io_control_info.incl.pl1):
dcl 01 mowse_io_terminal_state
based (mowse_io_terminal_state_ptr),
02 version char (8),
02 state bit (1) unal,
02 mbz bit (35) unal;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
state
Is the state of WSTERM "1"b if attached, "0"b otherwise.
mbz
Must be zero.
get_mowse_info
Provides a means of accessing the MOWSE data structures
mowse_info_ declared in mowse_info.incl.pl1 (which contains
all data necessary to MOWSE such as the CAT) and mowse_mcb
(which is the MOWSE Control Block for mowse_io_). The
info_ptr points to the following structure (defined in
mowse_io_control_info.incl.pl1):
dcl 01 mowse_io_info based (mowse_io_info_ptr),
02 version char (8),
02 mcb_ptr ptr,
02 info_ptr ptr;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
mcb_ptr
Is the pointer to the the mowse_io_ MOWSE Control Block.
MTB741-07 MOWSE Design
info_ptr
Is the pointer to the mowse_info_ structure which contains
information pertinent to MOWSE.
put_to_sleep
Provides a mechanism by which a background application can be
notified in a specified number of seconds through a background
message (see ws_$sleep). The info_ptr points to the following
structure (defined in mowse_io_control_info.incl.pl1):
dcl 01 mowse_io_sleep_info based (mowse_io_sleep_info_ptr),
02 version char (8),
02 major_index fixed bin,
02 sleep_seconds fixed bin;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
major_index
Is the index number into the local CAT of the application
which is requesting to be put to sleep.
sleep_seconds
Is the number of seconds the applications is to be
put_to_sleep.
reconnection
Is the control order which is to be received by mowse_io_ when
a reconnection to a disconnected process has been requested.
It is mandatory that this control order be issued to mowse_io_
at reconnection, otherwise MOWSE will not operate correctly.
Reconnection will be implemented in a later version of MOWSE.
send_local_message
send_message
These orders provide a means of sending messages to both the
remote system (PC) and the local system. The info_ptr points
to the following structure (defined in
mowse_io_control_info.incl.pl1):
dcl 01 mowse_io_message based (mowse_io_message_ptr),
02 version char (8),
02 channel fixed bin,
02 io_message_ptr ptr,
02 io_message_len fixed bin (21);
where:
MOWSE Design MTB741-07
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
channel
Is the channel on which the message is to be transmitted
and can have one of the values FG (foreground) or BG
(background) (defined in mowse_messages.incl.pl1).
io_message_ptr
Is a pointer to the character string containing the
message to be sent.
io_message_len
Is the length of the message to be sent, referenced by
io_message_ptr.
set_video_mode
Provides a means of notifying mowse_io_ that the video system
is enabled/disabled. This order will generate a modes message
to be sent to the remote with the appropriate flag set to the
mode specified.
dcl 01 mowse_io_set_video_mode_info based (mowse_io_store_info_ptr),
02 version char (8),
02 mode bit (1) unal,
02 mbz bit (35) unal;
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
mode
Is the current state of the video system: True if
attached, False if not.
mbz
Must be zero.
store_mowse_info
Provides a means of saving reference to the mowse_info_
structure in the attach data to mowse_io_ for future retrieval
through the order "get_mowse_info". The info_ptr points to
the following structure (defined in
mowse_io_control_info.incl.pl1):
dcl 01 mowse_io_store_info based (mowse_io_store_info_ptr),
02 version char (8),
02 info_ptr ptr;
MTB741-07 MOWSE Design
where:
version
Is the version number of the structure. It must be
mowse_io_info_version_1.
info_ptr
Is the pointer to the mowse_info structure.
LIST OF NON-SUPPORTED CONTROL ORDERS:
Because of the special need for mowse_io_ to control the
communications aspect of the Multics process, the following
control orders must be rejected by mowse_io_ as they will affect
the functionality of mowse_io_ (these non-suppoerted orders are
listed in mowse_io_bad_control.incl.pl1):
get_chars_timeout set_delay
get_line_timeout set_framing_chars
interrupt set_input_translation
listen set_line_type
position set_output_translation
put_chars_timeout set_wakeup_table
start_xmit_hd send_initial_string
stop_xmit_hd set_event_channel
input_flow_control_info wru
output_flow_control_chars modes
MODES OPERATION:
The modes operation is supported when the I/O switch is open.
The recognized modes are below. The modes string is parsed via
the mode_string_ entries to parse the modes string. MOWSE
requires full control over the communication modes in order to
communicate effectively with the PC. Thus MOWSE will reset the
modes to the manner in which mowse_io_ requires them.
crecho, ^crecho
echoes a carriage return when a line feed is typed.
lfecho, ^lfecho
echoes and inserts a line feed in the user's input stream when
a carriage return is typed.
llN, ^ll
specifies the length in character positions of a terminal
line.
plN, ^pl
specifies the length in lines of a page.
MOWSE Design MTB741-07
When a modes order is requested, in addition to "changing" the
above modes, mowse_io_ will also issue a message along the
foreground subchannel which is destined for the terminal manager
in order that it may make the necessary changes. It is up to the
terminal manager to interpret and provide the necessary changes
to the terminal environment. See WSTERM.info.
CONTROL OPERATIONS FROM COMMAND LEVEL
The following is a list of control operations which are
accessible from command level through io_call as follows:
io_call control switch_name order_arg
ARGUMENTS:
switch_name
The name of the I/O switch.
order_arg
Any control order described above (and in tty_) which can
accept null info pointer as well as read_status, write_status,
terminal_info, and the following as shown:
store_id
where id is the answerback string.
set_term_type type {-control_args}
where type is the new terminal type and -control_args can
be of any -initial_string (-istr), -modes, and
-ignore_line_type. These control_args are accepted by
io_call, but are ignored by mowse_io_.
line_length N
where N is the new line length.
The following control orders can be used as active functions:
[io_call control switch_name read_status]
returns true if input available; false otherwise.
[io_call control switch_name write_status]
returns true if output is pending; false otherwise.
[io_call control switch_name terminal_info terminal_type]
returns the current terminal type.
[io_call control switch_name terminal_info baud]
returns the baud rate
[io_call control switch_name terminal_info id]
returns the terminal identifier (answerback).
MTB741-07 MOWSE Design
[io_call control switch_name terminal_info line_type]
returns the current line type.
MOWSE Design MTB741-07
3.4.2. Reconnecting mowse_io_
In the event that Multics has become disconnected from the PC for
any reason - whether that be through the communication line
dropping, the PC crashing, or some error on Multics which causes
a process to become disconnected - there must be some facility by
which mowse_io_ may re-establish the connection after this
disconnection. There are essentially three approaches to the
solution:
1) Completely ignore it and force the user to "new_proc" when
reconnecting to Multics. This is not acceptable as it is
imposing unnecessary restrictions on the user.
2) Support only reconnection from a PC which is currently
running under the PC MOWSE. This is the minimum solution as
it allows the needed reconnection, but it will not function in
the event of a reconnection from a non-MOWSE "terminal" and
subsequently cause the Multics process to "hang".
3) Full support for reconnection from both a MOWSE and a
non-MOWSE terminal. This is the preferred solution, but also
the most complicated.
PC MOWSE
The solution which has been agreed upon is number two as it
provides the minimum support necessary for reconnection. There
are two manners in which a disconnection can occur: one is that
the communications line between the PC and Multics has dropped;
second is that the PC has crashed.
In the first case, MOWSE can detect the line drop when the DSR
signal drops, thus the PC MOWSE can exit gracefully, suitably
notifying all currently loaded applications through a
"terminate_capability" minor message. In the second case, the
line is still connected yet PC MOWSE has discontinued
communications due to the crash. In either case, PC MOWSE must
be restarted in order to talk on the communications line, thus
reconfiguring the port (RS232) and dropping the DSR causing
Multics to disconnect (if it wasn't already).
Multics MOWSE (mowse_io_)
When the reconnection is established to Multics through PC MOWSE,
mowse_io_ will begin the reconnection sequence with the PC on the
"reconnection" control order which has been issued to user_i/o.
If mowse_io_ is not attached to user_i/o, then all I/O modules
between user_i/o and mowse_io_ must forward the reconnection
order in order for mowse_io_.
MTB741-07 MOWSE Design
In the case of the video system running, the reconnection control
order is sent to window_io_. window_io_ forwards this control
request to the user_terminal_ switch attached through tc_io_ to
the mowse_terminal_ switch. tc_io_ must then take steps after it
forwards the reconnection order to ws_tty_ to mowse_io_. tc_io_
must then send whatever control orders needed through ws_tty_ to
get WSTERM on the PC back into the state which the video system
expects of it.
When reconnection has been completed, mowse_io_ will send
"terminate_capability" minor capability messages to each of the
Multics loaded applications and then clean out the CAT. This is
necessary as the PC and Multics version of the CAT are no longer
compatible as the PC MOWSE had to be reinitialized. When this
has completed, MOWSE will be reset.
Note: The implementation of reconnection is being postponed to a
later version of MOWSE.
MOWSE Design MTB741-07
4. Application Interface
4.1. MOWSE Considerations
The implementation of background processing under operating
systems that do not directly support multitasking within a
process creates the potential for problems in the interface
between the background tasks and the operating system. The
occurrence of problems can be reduced, but not eliminated, by
requiring the writers of MOWSE applications to follow certain
rules when designing and implementing these applications.
The primary consideration on both Multics and the PC is the fact
that background processes are essentially being run as
subroutines that are invoked as the result of hardware interrupt.
Because this is the case, MOWSE applications must be designed in
such a way as to minimize the processing required during each
invocation. In particular, MOWSE applications must not loop
while waiting for service or responses from the corresponding
application running on the other processor. In order to
facilitate the correct behavior of MOWSE applications, the
following rules should be followed:
1) Every request received by a MOWSE application (in the form
of a minor capability call) must be responded to by another
minor capability message that is sent back to the
originating application. While there is work to be done by
the cooperating applications, no application should receive
a minor capability message without responding to it by
sending another minor capability message.
2) MOWSE applications should not access the user i/o facilities
on either computer at any time after the "terminate and stay
resident" call is made.
3) On the PC, the amount of memory taken by MOWSE applications
should be minimized. Since MOWSE applications will stay
active for the entire life of the PC session, even when not
active, memory should be husbanded carefully. As a general
rule, MOWSE applications should be designed to perform
specific capabilities that have a wide usage. Other
applications can be written to make use of these
capabilities for more specific, and shorter lasting,
purposes. As an example, bft is a MOWSE application that is
MTB741-07 MOWSE Design
designed to transfer a single file between computers and is
quite small in size. For the more specific application of
backing up all of the files on a PC according to some
criteria, a more complex, and much larger application called
PCFB can be run that makes use of the simple capabilities of
bft.
4) In order to avoid memory fragmentation on the PC, MOWSE
applications should be initiated and loaded on the PC as
soon as possible. Ideally, this should occur before the
terminal support application, or any other foreground
application, is started. This can be accomplished by
starting the applications as soon as MOWSE returns to
command level on the PC, or by having MOWSE initiate the
applications when it starts up.
5) Background applications must not be permitted to generate
events from which bpth the application and MOWSE cannot
recover. Therefore, MOWSE must trap all signals generated
be background applications. When MOWSE does so, it sends an
informative message through the background message facility
(put_background_message), in addition it immediately
terminates all reference to the application from MOWSE
(destroying the application).
4.1.1. Considerations for Long Messages
Invisible to the applications (capabilities), long messages can
be sent between applications. Long messages are messages longer
than a single MOWSE protocol packet. The handling of long
messages is not part of MOWSE, because MOWSE would have to
maintain message buffers for each capability, and these buffers
would have to be of indefinite length. Instead, we have each
individual capability in effect handle its own long messages, but
in a way that the application writers need not know about it nor
code specially for it, except to supply long enough buffers,
indicated in the calls to create_instance.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
MOWSE Design MTB741-07
{data} {packet}
library fun. ------> SEND_MESSAGE ========> EXTERNAL_MOWSE
/ ||
|| {send_me_more} ||
============================/
Every library function that sends messages to the remote system
uses the splitter to send them. If the splitter detects that the
message is longer than the size of a single MOWSE protocol
packet, it sends successive portions of that message. This is
done in coordination with a pre-processor routine built in to the
remote capability who receives the message.
Each portion of the long message sent by the splitter contains a
MORE-LATER indicator. The pre-processor detects this indicator
and, instead of passing the message portion along to its
capability's process-event entry point, it appends the portion to
the capability's input message buffer. It then requests the
splitter for more, by sending a "send-me-more" message back.
This process continues until the final portion, for which the
splitter does not insert the MORE-LATER indicator, and thus the
pre-processor knows this is the final portion, appends it the
input buffer, and (only now) passes control to its capability's
process_event entry point, presenting it with the full
re-assembled message.
If the re-assembled incoming message portions exceed the size of
the input message buffer, the pre-processor gives control to its
process_event entry point, presenting it with a truncated message
and a minor capability that has been changed from the original
minor of the message, to the pre-assigned minor for
"MESSAGE_TOO_LONG". The capability must contain this minor
capability written to handle this condition. The truncated
message also contains in its first byte the original minor, so
the error handling can resume at the originally specified minor,
if desired.
The above explanation leaves out one complication: the splitting
action is actually shared by 2 routines: the SPLITTER as shown
above, and the pre-processor entry point of the SENDING
capability. Only the first portion of a long message is sent by
the SPLITTER proper; the remaining portions must be sent by the
pre-processor entry point of the sending capability, because that
is its only entry point that can get control when the
"send-me-more" response message is received. Thus a
process_event entry point actually does both the splitting of
outgoing long messages and the re-assembly of incoming long
messages.
MTB741-07 MOWSE Design
4.2. Subroutine Interfaces
The entire purpose of MOWSE is to provide an application writer
with a means of using the facilities on each of the systems which
are executing within MOWSE. Additional functionality is
available to Multics and PC subroutines and commands. Namely,
applications running on Multics within MOWSE can call PC-resident
procedures if so desired. Conversely, applications within MOWSE
on the PC can call Multics-resident procedures. For example,
applications written on the PC to run under MOWSE can now use
Multics commands and active functions, Multics applications and
almost any of the facilities available to the Multics user from
the PC.
There are essentially three levels of implementation which are
required by MOWSE to make this possible. The application sees
two of these layers: the library entry points - routines which
the application calls to perform some MOWSE functions; and the
"minor capability" numbers - functions which the application
provides in addition to certain functions required of the
application by MOWSE. The remaining layer provides the means of
communication between the components of MOWSE on each system.
The interfaces between the application and MOWSE are made simpler
to the programmer of the application through the Work Station
Subroutine Library. The WS Subroutine Library provides the
application writer with a means of: registering into the WS
environment, obtaining information from MOWSE, and making
requests of other applications which are registered with MOWSE.
MOWSE Design MTB741-07
WORK STATION SUBROUTINE LIBRARY COMMANDS
The following is a list of all the Work Station library
subroutines and entrypoints:
MULTICS PC FUNCTION
ws_$connect_request conrqst - request a connection to
an application
ws_$connect_response conresp - reply to a request for
connection
ws_$create_instance cretinst - register with MOWSE
ws_$destroy_instance destinst - check out of MOWSE
ws_$disconnect_request disrqst - terminate conversation
to an application
ws_$disconnect_response disresp - reply to the disconnect
request
ws_$execute_capability execap - execute a loaded
capability
ws_$execute_command execom - execute a system command
ws_$find_capability_name findname - find capability name of
an application given its
name
ws_$find_capability_number findnumb - find capability number
of an application given
its number
NA getbgmes - get a special message
to display
ws_$get_status getstat - request status infor-
mation from a capability
iox_$get_chars ** gettdata - get data from foreground
iox_$get_line ** channel
ws_$put_background_message putbgmes - store a special message
for display
ws_$put_status putstat - send status information
to requesting capability
iox_$put_chars ** puttdata - send data through
foreground channel
ws_$reset_capability resetcap - tell a capability to
reset itself
ws_$resume_capability resume - allow a suspended cap-
abiliity to send and
receive messages
ws_$send_query_reply sendqrep - send user's response
to a query message
ws_$sleep wssleep - tell MOWSE to refuse mes-
sages to the capability
for a time
NA stayres - terminate and stay
MTB741-07 MOWSE Design
resident
ws_$suspend_capability suspend - ask an application
to suspend operation
temporarily
ws_$terminate_capability termcap - tell a capability to
terminate itself
** These are standard Multics library entry points.
The next section deals with each set of entry points in turn. In
addition, an introductory section is provided for each set of
entry points which discusses the flow of information and control
in response to each of the library entry points. In some of the
descriptions below, reference is made to two types of messages,
foreground and background. For a complete description of these
channels, see section 3.3.
It is important to remember the following conventions that are
used by the flow diagrams:
"app" - Represents the application procedure.
"library_entry"- Represents the WS subroutine library entry
which is to be satisfied. This constitutes the
first layer of MOWSE.
"-->" - Represents a local interface between modules.
"==>" - Represents a remote interface between modules.
"XXXXXX" - Represents a MOWSE internal function, not to be
seen by the application. This constitutes the
second layer of MOWSE.
"app(XXXXXX)" - Represents a predefined minor capability to be
supported by the application. This constitutes
the third and final layer of MOWSE.
"{...}" - Represents data which is being passed.
MOWSE Design MTB741-07
Connect Request: ws_$connect_request, conrqst
Connect Response: ws_$connect_response, conresp
ws_$connect_request attempts to establish a "connection"
between the calling application and the application specified
in the argument list. It is then up to the requested
application to accept or reject the request by performing the
necessary MOWSE calls to set up for connection (creating
another mcb by calling ws_$create_instance).
ws_$connect_response is to be called when the requested
application has performed the necessary function to establish
itself for the new connection. It is used to notify the
requesting application by providing a ACCEPT and a pointer to
the mcb which identifies the instance for the connection, or a
REJECT status and a null new mcb pointer.
The following is a description of the method which MOWSE uses
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{system,cap_name,args} {cap_name,args}
app------> connect_request=======> app(REQUEST_CONNECT)
||
|| {cap_name,args}
||
VV {response} {response}
app(RESPONSE_CONNECT) <===== connect_response <---- app
When an application requests a connection, a message is sent
to the requested application for the connection. The
requested application is notified via the predefined minor
capability REQUEST_CONNECT. If the capability is not yet
registered with MOWSE, it is called and allowed to do so. The
connect request message is then passed on the the capability.
It is then up to the application to perform the necessary
actions which will create an instance to which the requesting
application may communicate whether it be a new instance or an
existing one. The application which was requested then
returns the response via a call to ws_$connect_response which
sends a RESPONSE_CONNECT to the application which made the
connect request. This message indicates the accept or reject
of the connect and the capability number of the instance which
is connected (if one exists).
MTB741-07 MOWSE Design
Multics Entry: ws_$connect_request
Function:
Request a connection to an application which has been loaded
by sending a "REQUEST_CONNECT" minor capability to the
requested application.
Syntax:
dcl ws_$connect_request entry
(char (*),
char (*),
fixed bin,
ptr,
fixed bin (35));
call ws_$connect_request
(capability_name,
args,
system,
mcb_ptr,
code);
Arguments:
capability_name: (Input)
The name of the major capability of the application to
which the connect is requested.
args (Input)
Any command line arguments which may be necessary if the
capability is to be started before the connection is made.
system (Input)
The system of the capability being connected to.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$connect_request ("bft", "load", REMOTE, mcb_ptr,
code);
MOWSE Design MTB741-07
PC Entry: conrqst - connect_request
Function: Request a connection to an application which has been
loaded by sending a "WSRQSTCN" minor capability to the requested
application.
Syntax:
int conrqst(cap_name,args,system,mcb_ptr);
char *cap_name;
char *args;
int system;
mcb *mcb_ptr;
Arguments:
cap_name (Input)
The name of the capability to be connected.
args (Input)
Any command line arguments which may be necessary if the
capability is to be started before the connection is made.
system (Input)
The system of the capability being connected to.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to cretinst.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = conrqst ("bft", "load", WSREMOTE, mcb_ptr);
MTB741-07 MOWSE Design
Multics Entry: ws_$connect_response
Function:
Reply to an application's request for a connection. This
allows the application of the ws_$connect_request call to to
be notified either of this applications accepting the connect
request by supplying the new major capability_number or to
reject the request by supplying an error code. The
application which made the request for connection will receive
the RESPONSE_CONNECT which will indicate the success or fail
of the request.
Syntax:
dcl ws_$connect_response entry
(fixed bin(17),
fixed bin(17),
ptr,
fixed bin(35));
call ws_$connect_response
(status,
major_capability,
mcb_ptr,
code);
Arguments:
status: (Input)
The acceptance/rejectance of the connect request.
Values: ACCEPT
REJECT
major_capability: (Input)
The major capability number of the application to which
the response is destined.
mcb_ptr: (Input)
A pointer to the mcb which is associated with the
connection. The mcb can be either the original mcb
obtained by the application, or the address of a new mcb
obtained by the application specifically for this
connection.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$connect_response (ACCEPT, request_capability,
mcb_ptr, code);
call ws_$connect_response (REJECT, request_capability,
mcb_ptr, code);
MOWSE Design MTB741-07
PC Entry: conresp - connect_response
Function:
Reply to an application's request for a connection. This
allows the application of the conrqst call to to be notified
either of this applications accepting the connect request by
supplying the new major capability_number or to reject the
request by supplying an error code. The application which
made the request for connection will receive WSRESPCN which
will indicate the success or fail of the request.
Syntax:
int conresp (status,cap_num,mcb_ptr);
int status,
cap_num;
mcb_ptr,
Arguments:
status: (Input)
The acceptance/rejectance of the connect request.
Values: WSACCEPT
WSREJECT
cap_num: (Input)
The major capability number of the application to which
the response is destined.
mcb_ptr: (Input)
A pointer to the mcb which is associated with the
connection. The mcb can be either the original mcb
obtained by the application, or the address of a new mcb
obtained by the application specifically for this
connection.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = conresp (WSACCEPT, request_capability, mcb_ptr,
new_mcb_ptr, code);
ecode = conresp (WSREJECT, request_capability, mcb_ptr,
NULL, code);
MTB741-07 MOWSE Design
Create Instance: ws_$create_instance, cretinst
A capability calls create_instance to make itself known to both
MOWSEs, thereby providing its capabilities to MOWSE thus allowing
it to receive messages from other capabilities in MOWSE.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{name + entry + {major_cap
inlen + outlen_dataptr} + name }
app ----------------> create_instance =====>ADD_TO_REMOTE_CAT
<-----------------------+
{mcb_ptr}
The application calls create_instance, supplying the name by
which it wants to be known to the MOWSEs, the entry point where
it is to be invoked on the receipt of its messages, and the size
of its 2 private message buffers (one for incoming and one for
outgoing messages), and a pointer that MOWSE will maintain and
provide to the application.
Create_instance first calls the local add_to_cat routine, which
attempts to add the supplied information into the next available
slot in the local CAT of the local MOWSE (the local MOWSE has a
local CAT and a remote CAT). If this fails, an error is returned
immediately to the application, without any attempt to add to the
remote system's copy of the CAT.
If the above is successful, create_instance sends a message to
the remote MOWSE, requesting it to add this capability to its
remote CAT. This message contains just the supplied internal
name, and the local capability number used. It does not contain
the entry point or buffer information, because the remote system
does not need to know them.
The remote MOWSE's add_to_cat does not send any response message
back as it is assumed that a successful add_to_cat on the local
system will result in a successful add_to_cat on the remote
system. The calling application need not return to MOWSE
immediately after the create_instance call (many library
functions DO require that the caller immediately return to MOWSE
to await a response message that re-invokes the caller, but the
create_instance function has no such requirement).
MOWSE Design MTB741-07
After the remote message is sent, create_instance returns a
pointer to the MOWSE Control Block (mcb) to the caller. This mcb
is to be used by the caller when requesting most of the MOWSE
subroutine entry points. If the local add_to_cat failed, an
error code is returned to the caller instead.
MTB741-07 MOWSE Design
Multics Entry: ws_$create_instance
Function:
Register the calling routine with MOWSE by assigning it a
major capability number and adding it to MOWSE's capability
table. The calling routine must supply the name by which it
is to be known to MOWSE, and the entry point describing where
it is to be invoked by an execute capability.
Syntax:
dcl ws_$create_instance entry
(char(*),
char(*),
fixed bin(17),
fixed bin(17),
ptr,
ptr,
fixed bin(35))
call ws_$create_instance
(capability_name,
entry_name,
inbuff_length,
outbuff_length,
data_block_ptr,
mcb_ptr,
code)
Arguments:
capability_name: (Input)
The name by which the calling capability will be known to
MOWSE.
entry_name: (Input)
The entry point (by name) which will be invoked when MOWSE
has a message destined for the application.
inbuff_length: (Input)
The length (in characters) of the message buffer which
receives argument data from incoming messages. The buffer
will be allocated with the size specified or
MINIMUM_BUFFER_SIZE, whichever is larger.
outbuff_length: (Input)
The length (in characters) of the message buffer which
will be used for outgoing messages. The buffer will be
allocated with the size specified or MINIMUM_BUFFER_SIZE,
whichever is larger.
data_block_ptr: (Input)
Pointer to the application's local data which is to be
preserved across calls to the capability through MOWSE.
This provides an alternate method to static variables of
preserving data across the starts and stops of the
application's life in MOWSE thus providing reentrancy.
mcb_ptr: (Output)
MOWSE Design MTB741-07
Pointer to the application's MOWSE Control Block which
will be used by MOWSE to maintain information on the
application.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$create_instance ("bft", "bft_$process_event",
256, 256, data_ptr, mcb_ptr, code);
Notes:
All applications which expect to receive messages must have
registered with MOWSE (through create_instance) in order to
receive messages. A message is provided to the application
when a the destination of the message specifies the major
capability number of the application. The application will
then be invoked at the entry name provided with the message
(argument data), its length, and a pointer to the applications
data_block as follows:
dcl application_$entry_point entry
(fixed bin,
fixed bin,
ptr,
fixed bin,
ptr,
ptr);
application_$entry_point (minor_capability, major_sender,
arg_ptr, arg_length, mcb_ptr, data_block_ptr);
The buffers inbuff and outbuff allow MOWSE to send and receive
messages longer than one communications packet (defined by
PACKET_SIZE) in a manner transparent to the capability.
MTB741-07 MOWSE Design
PC Entry: cretinst - create_instance
Function:
Register the calling routine with MOWSE by assigning it a
major capability number and adding it to MOWSE's capability
table. The calling routine must supply the name by which it
is to be known to MOWSE, and the entry point describing where
it is to be invoked by an execute capability.
Syntax:
int cretinst (cap_name, entry, inbuff_len, outbuff_len,
data_ptr, mcb_ptr);
char cap_name[WSCAPLEN];
int (*entry)();
int inbuff_len;
int outbuff_len;
char *data_ptr;
mcb **mcb_ptr;
Arguments:
cap_name: (Input)
A null terminated string of characters specifying the name
by which the calling capability will be known to MOWSE.
entry: (Input)
A pointer to the function which will be invoked when MOWSE
has a message destined for the application.
inbuff_len: (Input)
The length (in characters) of the message buffer which
receives argument data from incoming messages. The buffer
will be allocated with the size specified or WSMINBUF,
whichever is larger.
outbuff_len: (Input)
The length (in characters) of the message buffer which
will be used for outgoing messages. The buffer will be
allocated with the size specified or WSMINBUF, whichever
is larger.
data_ptr: (Input)
Pointer to the application's local data which is to be
preserved across calls to the capability through MOWSE.
This provides an alternate method to static variables of
preserving data across the starts and stops of the
application's life in MOWSE thus providing reentrancy.
mcb_ptr: (Output)
The address of the pointer to the application's MOWSE
Control Block which will be used by MOWSE to maintain
information on the application.
Returns:
0 - no error
Or an error code defined in the appendix.
MOWSE Design MTB741-07
Example:
ecode = cretinst ("bft", bft_process, 256, 256, data_ptr,
&mcb_ptr);
Notes:
All applications which expect to receive messages must have
registered with MOWSE (through cretinst) in order to receive
messages. A message is provided to the application when a the
destination of the message specifies the major capability
number of the application. The application will then be
invoked at the entry name provided with the message (argument
data), its length, and a pointer to the applications
data_block as follows:
application_$entry_point (minor_cap, major_sender, arg_ptr,
arg_length, data_block_ptr, mcb_ptr);
char minor_cap;
int major_sender;
char *arg_ptr;
int arg_length;
char *data_block_ptr
The buffers inbuff and outbuff allow MOWSE to send and receive
messages longer than one communications packet (defined by
WSPAKSIZ) in a manner transparent to the capability.
MTB741-07 MOWSE Design
Destroy Instance: ws_$destroy_instance, destinst
A capability calls destroy_instance to cause both the local and
remote MOWSEs to remove reference to the calling capability,
thereby making that capability unknown to MOWSE. This removes
the application from the CAT thus preventing messages from being
sent to this deleted capability.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{mcb} {major_cap}
app ------> DESTROY_INSTANCE =========> WS_DELETE_FROM_CAT
<-------------+
The application calls destroy_instance supplying the pointer to
its mcb. Delete_instance then removes reference in the CAT to
the application, in effect erasing the information stored about
it in the CAT.
Destroy_instance will then send a message to the remote MOWSE
requesting that this capability also be removed there. This
message contains the major capability number of the destroyed
instance.
The MOWSE on the remote system frees the CAT slot there but does
not send any response message back to the local system as it is
assumed that a successful delete_from_cat on the local system
means that the remote delete_from_cat will also be successful.
Therefore the calling application need not return to MOWSE
immediately after the destroy_instance call.
MOWSE Design MTB741-07
Multics Entry: ws_$destroy_instance
Function:
Removes the reference to the application from MOWSE's
capability table and deallocates the inbuff and outbuff
message buffer space.
Syntax:
dcl ws_$destroy_instance entry
(ptr,
fixed bin(35));
call ws_$destroy_instance
(mcb_ptr
code);
Arguments:
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$destroy_instance (mcb_ptr, code);
Notes:
MTB741-07 MOWSE Design
PC Entry: destinst - destroy_instance
Function:
Removes the reference to the application from MOWSE's
capability table and deallocates the inbuff and outbuff
message buffer space.
Syntax:
int destinst (mcb_ptr);
mcb **mcb_ptr;
Arguments:
mcb_ptr: (Input)
The address of the pointer to the application's MOWSE
Control Block assigned by a call to "cretinst".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = destinst (&mcb_ptr);
Notes:
If this is the final instance and it is being destroyed, then
all memory occupied by the application is released including
memory occupied by its code.
MOWSE Design MTB741-07
Disconnect Request: ws_$disconnect_request, disrqst
Disconnect Response: ws_$disconnect_response, disresp
ws_$disconnect_request provides an application with a simple
means of discontinuing a connection (conversation) to another
application.
Once the requested application has performed the necessary
functions for a disconnect (a call to ws_$destroy_instance
etc.), it calls ws_$disconnect_response which provides the
application with a simple means of responding to the
disconnect request.
The following is a description of the method which MOWSE uses
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{cap_num}
app -----> disconnect_request =======> app(REQUEST_DISCONNECT)
{response} {response}
app(RESPONSE_DISCONNECT) <====== disconnect_response <---- app
When an application requests a disconnection, a message is
sent to the requested application for the disconnection. The
requested application is notified via the predefined minor
capability REQUEST_DISCONNECT. It is then up to the
application to perform the necessary actions which will
"break" the connection to which the requesting application was
communicating. The application which was requested then
returns the response via a call to ws_$disconnect_response
which sends a RESPONSE_DISCONNECT to the application which
made the disconnect request. This message indicates the
accept or reject of the disconnect.
MTB741-07 MOWSE Design
Multics Entry: ws_$disconnect_request
Function:
Request that conversation to the specified application be
terminated by sending a REQUEST_DISCONNECT to the specified
capability.
Syntax:
dcl ws_$disconnect_request entry
(fixed bin(17),
ptr,
fixed bin(35));
call ws_$disconnect_request
(capability_number,
mcb_ptr,
code);
Arguments:
capability_number: (Input)
The major capability number of the application which is to
be disconnected.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$disconnect_request (bft_major_cap, mcb_ptr, code);
MOWSE Design MTB741-07
PC Entry: disrqst - disconnect_request
Function:
Request that conversation to the specified application be
terminated by sending a "WSRQSTDS" to the specified
capability.
Syntax:
int disrqst(cap_num,mcb_ptr);
int cap_num;
mcb *mcb_ptr;
Arguments:
cap_num: (Input)
The major capability number of the application which is to
be disconnected.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to cretinst.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = disrqst (bft_major_cap, mcb_ptr);
MTB741-07 MOWSE Design
Multics Entry: ws_$disconnect_response
Function:
Notify the application which requested a disconnect that the
disconnect was accepted or rejected. A RESPONSE_DISCONNECT
message will be sent to the application which made the
disconnect request.
Syntax:
dcl ws_$disconnect_response
(fixed bin(17),
fixed bin(17),
ptr,
fixed bin(35));
call ws_$disconnect_response
(status,
major_capability,
mcb_ptr,
code);
Arguments:
status: (Input)
The acceptance/rejectance of the disconnect request.
Values: ACCEPT
REJECT
major_capability: (Input)
The major capability number of the application to which
the response is destined.
mcb_ptr: (Input)
The pointer to the application's MOWSE control block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$disconnect_response (ACCEPT,
request_capability,
mcb_ptr, code);
call ws_$disconnect_response (REJECT,
request_capability,
mcb_ptr, code);
MOWSE Design MTB741-07
PC Entry: disresp - disconnect_response
Function:
Notify the application which requested a disconnect that the
disconnect was accepted or rejected. A "WSRESPDS" message
will be sent to the application which made the disconnect
request.
Syntax:
int disresp(status,cap_num,mcb_ptr);
int status,
cap_num;
mcb *mcb_ptr;
Arguments:
status: (Input)
The acceptance/rejectance of the disconnect request.
Values: WSACCEPT
WSREJECT
cap_num: (Input)
The major capability number of the application to which
the response is destined.
mcb_ptr: (Input)
The pointer to the application's MOWSE control block
assigned by a call to cretinst.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = disresp (WSACCEPT, request_capability, mcb_ptr);
ecode = disresp (WSREJECT, request_capability, mcb_ptr);
MTB741-07 MOWSE Design
Execute Capability: ws_$execute_capability, execap
Execute capability provides an application with a means of
executing a capability on the local or remote system. The
capability must have been loaded with execute_command.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{major + data} {major + data}
app ----------> execute_capability ========> WS_EXECUTE_CAPABILITY
<-------------------+ ||
{code} | ||
| ||
V {failure} ||
app(FAIL_CAPABILITY) <====================================/
When an application requests a capability to be executed, whether
or not the requested application was remote or local,
"execute_capability" will immediately return. If MOWSE fails to
properly execute the capability, then the requesting application
is notified through the predefined minor capability
"EXECUTE_CAPABILITY_REPLY".
MOWSE Design MTB741-07
Multics Entry: ws_$execute_capability
Function:
Execute the minor capability function of the specified major
capability with the arguments provided.
Syntax:
dcl ws_$execute_capability entry
(fixed bin(17),
fixed bin(17),
ptr,
fixed bin(17),
ptr,
fixed bin(35));
call ws_$execute_capability
(major_capability_number,
minor_capability_number,
arg_ptr,
arg_length,
mcb_ptr,
code);
Arguments:
major_capability_number: (Input)
The identifier of the capability to be executed.
minor_capability_number: (Input)
The identifier of a specific function to be performed by
the specified major_capability.
arg_ptr: (Input)
A pointer to the argument data to be supplied to the
specified capability, NULL if there is no argument data.
arg_length: (Input)
The length of the argument data in bytes, zero if there is
no data.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$execute_capability (pc_foo_id, add_num_id, num_arg_ptr,
num_arg_len, mcb_ptr, code);
MTB741-07 MOWSE Design
Notes:
MOWSE assumes that the argument data has been converted to
character string format by the calling application. If not,
MOWSE will lose every 9th bit of the argument data as only 8
of the 9 bits per character are transferred to the remote
capability.
If MOWSE was incapable of starting execution of the specified
application, the calling application will be notified through
the predefined minor capability FAIL_CAPABILITY.
MOWSE Design MTB741-07
PC Entry: execap - execute_capability
Function:
Execute the minor capability function of the specified major
capability with the arguments provided.
Syntax:
int execap (major_num, minor_num, arg_ptr, arg_len, mcb_ptr);
int major_num;
int minor_num;
char *arg_ptr;
int arg_len;
mcb *mcb_ptr;
Arguments:
major_num: (Input)
The identifier of the capability to be executed.
minor_num: (Input)
The identifier of a specific function to be performed by
the specified major_capability.
arg_ptr: (Input)
A pointer to the argument data to be supplied to the
specified capability, NULL if there is no argument data.
arg_len: (Input)
The length of the argument data in bytes, zero if there is
no data.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to "cretinst".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = execap (pcfooid, addnumid, numarg_ptr, numarg_len,
mcb_ptr);
Notes:
It is up to the calling application to convert the argument
data into character string format which can be interpreted by
the application being called as a character string of data.
If MOWSE was incapable of starting execution of the specified
application, the calling application will be notified through
the predefined minor capability WSFAILCP.
MTB741-07 MOWSE Design
Execute Command: ws_$execute_command, execom
Execute command provides an application with the means of
executing system commands on either the remote or the local
system through the respective command processor. The primary
purpose of this function is to provide the application with a
means of loading other applications for use through MOWSE.
Although this command can be used to load and execute non-mowse
applications, the practice is not recommended since the MOWSE
scheduler will not perform any other function until the
application returns control to MOWSE.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{command} {com_id + command}
app --------> execute_command ===============> WS_EXECUTE_COMMAND
<--------------+ ||
{com_id} | ||
| {com_id + status + {major}} ||
V ||
app(EXECUTE_COMMAND_REPLY) <==========================/
When an application requests a command to be executed,
"execute_command" will immediately return with a "command_id".
This command_id is to be used to identify the command in order to
provide a means of associating command results with a particular
command.
There are two cases of execution, one is when the command is
local, and the other remote. In either case, MOWSE performs the
command by calling the appropriate command processor. Upon
completion, the requesting application is notified through the
predefined minor capability "EXECUTE_COMMAND_REPLY" with the
status of the execution of the command - failed or succeeded -
and the command_id to which these results are associated.
The return information may contain in addition to the status a
major capability number. In the event that the command caused an
application to be loaded and initialized into MOWSE, the major
capability number will identify to the requesting application the
capability number of the application which was loaded. This is
to allow for the eventual case of multiple instances of a single
capability name where as a simple "find_capability" will not
suffice to locate the capability number based on name only.
MOWSE Design MTB741-07
Multics Entry: ws_$execute_command
Function:
Send a command string to the command processor on the
specified system.
Syntax:
dcl ws_$execute_command entry
(char(*),
fixed bin(17),
fixed bin(17),
ptr,
fixed bin(35))
call ws_$execute_command
(command_string,
system,
command_id,
mcb_ptr,
code)
Arguments:
command_string: (Input)
The string of characters that would be typed on the system
to execute the command.
system: (Input)
A constant specifying which system command_string will be
executed on.
Values: LOCAL_SYSTEM
REMOTE_SYSTEM
command_id: (Output)
The tag which will be associated with the command_string
being executed and the resultant EXECUTE_COMMAND_REPY
predefined minor capability.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$execute_command ("dir usersmith*.*",
REMOTE_SYSTEM, com_id, mcb_ptr, code);
call ws_$execute_command ("ls -d >udd>m>Smith",
LOCAL_SYSTEM, com_id, mcb_ptr, code);
call ws_$execute_command ("bft", REMOTE_SYSTEM,
com_id, mcb_ptr, code);
MTB741-07 MOWSE Design
Notes:
There are two manners in which information will be returned to
the calling application. One is the immediate return which
will provide the error information as specified in code. The
second is through a delayed response message via the
predefined minor capability EXECUTE_COMMAND_REPLY which will
provide the calling application with information at the
completion of the command. Two types of information will be
provided. One is a success or failure of the command - this
is important in the case of remote commands which caused the
command processor on the remote system to fail. The second is
to provide the handler with the major capability number of the
application which may have been loaded by the command.
Since execute_command will call the system's command processor
with the command_string, an application may be called which
will load itself into the MOWSE. Thus an application may use
execute_command to load another application.
Output from a command executing on the PC (by the PC's command
processor) will appear on the terminal screen with total
disregard to MOWSE. If a terminal emulator is executing and
it calls a PC routine through execute_command - such as "dir"
- the output will appear on the screen without passing through
the terminal emulator.
MOWSE Design MTB741-07
PC Entry: execom - execute_command
Function:
Send a command string to the command processor on the
specified system.
Syntax:
int execom (command_string, system, command_id, mcb_ptr);
char *command_string;
int system;
int *command_id;
mcb *mcb_ptr
Arguments:
command_string: (Input)
A null terminated string of characters that would be typed
on the system to execute the command.
system: (Input)
A constant specifying which system command_string will be
executed on.
Values: WSLOCAL
WSREMOTE
command_id: (Output)
The tag which will be associated with the command_string
being executed and the resultant WSCOMREP predefined minor
capability.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to "cretinst".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = execom ("dir usersmith*.*", WSREMOTE, &com_id,
mcb_ptr);
ecode = execom ("ls -d >udd>m>Smith",WSLOCAL, &com_id,
mcb_ptr);
ecode = execom ("bft", WSREMOTE, &com_id, mcb_ptr);
Notes:
There are two manners in which information will be returned to
the calling application. One is the immediate return which
will provide the error information as specified in code. The
second is through a delayed response message via the
predefined minor capability WSCOMREP which will provide the
calling application with information at the completion of the
MTB741-07 MOWSE Design
command. Two types of information will be provided. One is a
success or failure of the command - this is important in the
case of remote commands which caused the command processor on
the remote system to fail. The second is to provide the
handler with the major capability number of the application
which may have been loaded by the command.
Since execute_command will call the system's command processor
with the command_string, an application may be called which
will load itself into the MOWSE. Thus an application may use
execute_command to load another application.
Output from a command executing on the PC (by the PC's command
processor) will appear on the terminal screen with total
disregard to MOWSE. If a terminal emulator is executing and
it calls a PC routine through EXECOM - such as "dir" - the
output will appear on the screen without passing through the
terminal emulator.
MOWSE Design MTB741-07
Find Capability Name: ws_$find_capability_name, findname
Find capability name provides an application with the means of
extracting the capability name of an application based on its
capability number. There is no need for messages to be
generated as all of the necessary information is stored
locally by MOWSE.
MTB741-07 MOWSE Design
Multics Entry: ws_$find_capability_name
Function:
Find the name of a capability given its major capability
number.
Syntax:
dcl ws_$find_capability_name entry
(fixed bin(17),
char(*),
fixed bin (35));
call ws_$find_capability_name
(major_capability_number,
capability_name,
code);
Arguments:
major_capability_number: (Input)
The major capability number of the capability name to be
found.
capability_name: (Output)
The name of the capability.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
ws_$find_capability_name (major_cap, cap_name, code);
Notes:
MOWSE Design MTB741-07
PC Entry: findname - find_capability_name
Function:
Find the name of a capability given its major capability
number.
Syntax:
int findname (major_num, cap_name);
int major_number;
char cap_name[WSCAPLEN];
Arguments:
major_number: (Input)
The major capability number of the capability name to be
found.
cap_name: (Output)
The name of the capability found, 0 length if not found.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = findname (major_cap, cap_name);
Notes:
MTB741-07 MOWSE Design
Find Capability Number: ws_$find_capability_number, findnumb
Find capability number provides an application with the means
of extracting the capability number of an application based on
its capability name. There is no need for messages to be
generated as all of the necessary information is stored
locally by MOWSE.
MOWSE Design MTB741-07
Multics Entry: ws_$find_capability_number
Function:
Find the major capability number of an application given a
capability name.
Syntax:
dcl ws_$find_capability_number entry
(char(*),
fixed bin(17),
fixed bin(17),
fixed bin(35));
call ws_$find_capability_number
(capability_name,
system_id,
major_capability_number,
code);
Arguments:
capability_name: (Input)
The capability name to be looked for.
system_id: (Input)
The system which is to be looked at to find the capability
name.
Values: LOCAL_SYSTEM
REMOTE_SYSTEM
major_capability_number: (input/output)
Indicates where MOWSE is to begin searching of the
capability table for the name specified, 0 will find the
first case, and returns the major capability number of the
found name.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$find_capability_number ("bft",
major_capability_number, code);
Notes:
MOWSE looks for the capability name in its capability table in
the following fashion:
MTB741-07 MOWSE Design
1) If the provided major capability number is invalid,
MOWSE will begin searching from the top of the table
specified by the system_id.
2) If the major capability number is valid, MOWSE will
begin searching from the next entry on the same system of
the major capability number.
3) If the system id is invalid, MOWSE will search from the
first entry on the local CAT.
MOWSE Design MTB741-07
PC Entry: findnumb - find_capability_number
Function:
Find the major capability number of an application given a
capability name.
Syntax:
int findnumb (cap_name, sys_id, major_num);
char cap_name[WSCAPLEN];
int sys_id;
int *major_num;
Arguments:
cap_name: (Input)
The capability name to be looked for.
sys_id: (Input)
The system which is to be looked at to find the capability
name.
Values: WSLOCAL
WSREMOTE
major_num: (input/output)
Indicates where MOWSE is to begin searching of the
capability table for the name specified, 0 will find the
first case, and returns the major capability number of the
found name.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = findnumb ("bft_", WSLOCAL, &major_num);
ecode = findnumb ("bft_", WSREMOTE, &major_num);
Notes:
MOWSE looks for the capability name in its capability table in
the following fashion:
1) If the provided major capability number is 0, MOWSE
will begin searching from the top of the table specified
by the sys_id.
2) If the major capability number is valid, MOWSE will
begin searching from the next entry.
3) If the provided sys_id is invalid, MOWSE will search
the local CAT table from its first entry.
MTB741-07 MOWSE Design
Get Background Message: ws_$get_background_message,
getbgmes
When get_background_message is requested, there is one of
two types of messages returned, if any.
1) background messages - informative/error messages
2) query messages - a background application requires some
user response.
Get_background_message provides an application with a means of
getting the next of these background messages out of the local
background buffer. It is up to the application running at the
time to use get_background_message to read from this buffer
and display it on the screen. If the background buffer is
empty when get_background_message is called, it returns a zero
string length.
MOWSE Design MTB741-07
PC Entry: getbgmes - get_background_message
Function:
Returns one of two types of background messages - placed there
by a call to "putbgmes".
1) Info messages which are for display only.
2) Query messages which are to be used to prompt the user
to provide information which is to be returned to the
requesting application through a call to "sendqrep".
Syntax:
int getbgmes (string, type, sender_major);
char *string;
int *type;
int *sender_major;
Arguments:
string: (Output)
The next background message available from MOWSE, placed
there by a call to "putbgmes". The string buffer into
which the background message is placed must be at least
one packetsize (WSPAKSIZ characters) long.
type: (Output)
A specifier to the type of background message returned.
Values: WSQUERY
WSINFO
sender_major: (Output)
The major capability number of the application which
stored the background message through a call to
"putbgmes".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = getbgmes (string, &type, &sender_major);
Notes:
The application which makes this call must be a foreground
application which is responsible for all user I/O.
If the message type returned is WSQUERY, the application which
made this call must send a reply to the sender major as it is
stopped, expecting a reply.
MTB741-07 MOWSE Design
Get Status: ws_$get_status, getstat
Put Status: ws_$put_status, putstat
A foreground application may request status information from a
specified application through this call. It is up to the calling
application and the called application to coordinate their
efforts in obtaining the necessary status information.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{major_cap + request} {request}
app ------------------> get_status ===========> app (STATUS)
|
<--------- STATUS_REPLY <========= put_status <----+
{result} {result} {result}
When a foreground application requests status information of a
background application through a call to get_status, MOWSE will
send the request string to the specified application and invoke
it with the predefined minor capability STATUS. The called
application then provides the requested status information by a
call to put_status. Put_status then sends the result to the
application which made the get_status request. MOWSE then
returns to the calling application of get_status with the result
data.
MOWSE Design MTB741-07
Multics Entry: ws_$get_status
Function:
Requests status information from the specified application.
Syntax:
dcl ws_$get_status entry
(fixed bin(17),
char(*),
char(*),
fixed bin(35));
call ws_$get_status
(major_number,
status_request,
status_result,
code);
Arguments:
major_number: (Input)
The major capability number of the application to get
status information from.
status_request: (Input)
The argument data to be provided to the application to be
called.
status_result: (Output)
The resultant character status information.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$get_status (bft_major_cap, "pending", status, code);
Notes:
This entry must only be called by a foreground application as
it will wait within the call until a response is received.
The requested application is notified of the request via the
predefined minor capability STATUS.
MTB741-07 MOWSE Design
PC Entry: getstat - get_status
Function:
Requests status information from the specified application.
Syntax:
int getstat (major_num, status_request, status_result);
int major_num;
char *status_request;
char *status_result;
Arguments:
major_num: (Input)
The major capability number of the application to get
status information from.
status_request: (Input)
The argument data to be provided to the application to be
called.
status_result: (Output)
The resultant character status information.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = getstat (bft_major_cap, "pending", status);
Notes:
This entry must only be called by a foreground application as
it will wait within the call until a response is received.
The requested application is notified of the request via the
predefined minor capability WSSTATUS.
MOWSE Design MTB741-07
Get Terminal Data: gettdata (PC only)
Get_terminal_data provides an application with a means of
getting foreground data out of the local terminal buffer. It
is up to the foreground application running at the time on the
PC to call get_terminal_data to retrieve from this buffer and
display it on the screen. If the terminal buffer is empty
when get_terminal_data is called, it returns a zero string
length.
MTB741-07 MOWSE Design
PC Entry: gettdata - get_terminal_data
Function:
Retrieve a string from the terminal buffer and a flag which
determines whether or not there are pending background message
(see PUTBGMES and GETBGMES). The string is destined to be
used as terminal data, ie. it is expected to be displayed by
the retrieving application on the PC's CRT.
If there is no data in the terminal buffer, a zero length
string will be returned.
Syntax:
int gettdata (getdata_ptr)
struct get_struc {
char *local_buffer_pointer;
int local_buffer_size;
int minor_capability;
int background_pending_flag;
} *getdata;
Arguments:
string_length: (Output)
The length of the terminal string that it pointed to in
the structure below. 0 if the terminal buffer is empty.
getdata_ptr: (Input)
The pointer to the calling routine's structure which is
used for input and output arguments.
local_buffer_ptr: (Input)
A pointer to a buffer into which the retrieved terminal
data will be placed.
local_buffer_size: (Input)
The size of the local buffer. Determines the maximum
number of characters that can be retrieved.
minor_capability: (Output)
The entry point specified by the remote system for
specialized handling of received terminal data.
background_pending_flag: (Output)
Determines if there are background messages pending. 0 if
none are pending, N for the number of messages pending.
Returns:
N - length of terminal data retrieved, 0 if none.
Notes:
MOWSE Design MTB741-07
Put Background Message: ws_$put_background_message, putbgmes
Put_background_message provides an application with a means of
sending a message to the system responsible for all user I/O to
be specially displayed to the user. Such data is destined for
subsequent special display on the user's terminal. A background
message must be less than or equal to PACKETSIZE characters in
length.
The following is a description of the method which MOWSE employs
to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{mcb + code +
control + args } {message}
app ----> put_background_message ===> WS_BACKGROUND_MSG
When an application requests this function,
"put_background_message" will form a message based on the control
string and code and send it to the system responsible for user
I/O. If the responsible system is remote, MOWSE sends the data
to the remote system via the MOWSE internal
PUT_TO_BACKGROUND_BUFFER which places the data into the
background message buffer for subsequent display by the
foreground application.
Note that there is a crossing of messages from a background
application which normally has nothing to do with the user I/O
(foreground) data stream.
MTB741-07 MOWSE Design
Multics Entry: ws_$put_background_message
Function:
Provides a background application with the means of displaying
one of two types of special messages to the foreground channel
through a foreground application such as the terminal
emulator.
1) Information messages which inform the user such as
errors and status.
2) Query messages which ask the user for input, which is
relayed back to the requesting application through the
predefined minor capability "QUERY_REPLY".
Syntax:
dcl ws_$put_background_message entry options (variable);
call ws_$put_background_message
(mcb_ptr,
code,
caller,
control_string,
arg1, ..., argN);
Arguments:
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Input)
Determines the type of the message to be displayed.
If code is 0, the message will consist only of the
contents of the control string.
If code is a standard Multics code, it will be expanded as
in com_err_.
If code is "SEND_QUERY", the control string will be used
to prompt the user for a response.
caller: (Input)
The name of the routine making the call to
ws_$put_background_message.
control_string: (Input)
An ioa_ subroutine control string. This argument is
optional (see com_err_).
argI: (Input)
ioa_ subroutine arguments to be substituted into the
control_string argument. These arguments are optional.
They can only be used however, if the control_string
argument is given first.
MOWSE Design MTB741-07
Example:
call ws_$put_background_message (mcb_ptr, error_code, "bft",
"retrieve error ^d", bft_$invalid_dir);
call ws_$put_background_message (mcb_ptr, 0, "bft",
"transfer of file ^a complete", trans.name);
call ws_$put_background_message (mcb_ptr,
SEND_QUERY, "bft",
"File ^a exists: overwrite?", trans.name);
Notes:
All arguments are exactly as under com_err_ with the exception
of the contents of the code parameter (as discussed above) and
the mcb_ptr.
All messages are placed into MOWSE for future retrieval
through a call to ws_$get_background_message. If there is no
foreground application executing to retrieve these messages,
they will go unnoticed. This is especially important in the
case of query messages as no response will be returned until
the message has been retrieved and processed by the foreground
application.
If the code is specified as SEND_QUERY, the user's response
will be provided to the calling application through the
predefined minor capability "QUERY_REPLY".
MTB741-07 MOWSE Design
PC Entry: putbgmes - put_background_message
Function:
Provides a background application with the means of displaying
one of two types of special messages to the foreground channel
through a foreground application such as the terminal
emulator.
1) Information messages which inform the user such as
errors and status.
2) Query messages which ask the user for input, which is
relayed back to the requesting application through the
predefined minor capability WSQRYREP.
Syntax:
int putbgmes (mcb_ptr, code, caller, control, arg1,...,argN);
mcb *mcb_ptr;
int code;
char *caller;
char *control;
Arguments:
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to "cretinst".
code: (Input)
Determines the type of the message to be displayed.
If code is 0, the message will consist only of the
contents of the control string.
If code is WSQUERY, the control string will be used to
prompt the user for a response.
caller: (Input)
The name of the routine making the call to "putbgmes".
control: (Input)
A "printf" control string.
argI: (Input)
printf control arguments to be substituted into the
control argument. These arguments are optional. They can
only be used however, if the control argument is given
first.
Returns:
0 - always
MOWSE Design MTB741-07
Example:
putbgmes (mcb_ptr, ecode, "bft", "retrieve error %d",
BFTINVDIR);
putbgmes (mcb_ptr, 0, "bft", "transfer of file %s complete",
trans.name);
putbgmes (mcb_ptr, WSQUERY, "bft",
"File %s exists: overwrite?", trans.name);
Notes:
All messages are placed into MOWSE for future retrieval
through a call to "getbgmes". If there is no foreground
application executing to retrieve these messages, they will go
unnoticed. This is especially important in the case of query
messages as no response will be returned until the message has
been retrieved and processed by the foreground application.
If the code is specified as WSQUERY, the user's response will
be provided to the calling application through the predefined
minor capability WSQRYREP.
MTB741-07 MOWSE Design
Multics Entry: ws_$put_status
Function:
Sends a status string to the application which made a request
for status information.
Syntax:
dcl ws_$put_status entry
(fixed bin(17),
char(*),
ptr,
fixed bin(35));
call ws_$put_status
(destination_major,
status,
mcb_ptr,
code);
Arguments:
destination_major: (Input)
The major capability number of the application to which
the status information is to be sent.
status: (Input)
Character string which comprises the status information up
to a length PACKET_SIZE.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to ws_$create_instance.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$put_status (major_cap, "status: no pending requests",
mcb_ptr, code);
Notes:
The calling application must have been invoked with the
predefined minor capability STATUS as it is then only that the
requesting application is awaiting status information. This
must be performed.
MOWSE Design MTB741-07
PC Entry: putstat - put_status
Function:
Sends a status string to the foreground application which made
a request for status information.
Syntax:
int putstat (status, mcb_ptr);
char *status;
mcb *mcb_ptr;
Arguments:
status: (Input)
A null terminated character string which comprises the
status information up to a length WSPAKSIZ.
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to "cretinst".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = putstat ("status: no pending requests", mcb_ptr);
Notes:
The calling application must have been invoked with the
predefined minor capability WSSTATUS as it is then only that
the requesting application is awaiting status information.
This must be performed.
MTB741-07 MOWSE Design
Put Terminal Data: puttdata (PC only)
Put_terminal_data provides an application with a means of
sending foreground data to Multics. Such data can be obtained
by a program running on Multics by a get_chars or get_line
operation.
The following is a description of the method which MOWSE
employs to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{data} {data}
app ------> put_terminal_data ==========> FG_TERMINAL_DATA
<--------------+
When an application requests this function put_terminal_data
will send the data to Multics.
MOWSE Design MTB741-07
PC Entry: puttdata - put_terminal_data
Function:
Send a data string to the Multics user i/o switch.
Syntax:
puttdata(minor_cap, string_ptr, string_len);
int minor_cap;
char *string_ptr;
int string_len;
Arguments:
minor_cap: (Input)
The destination minor capability number to receive the
data. This is to distinguish between control information
and regular terminal data. The minor capability number
for regular terminal data is WSFGDATA.
string_ptr: (Input)
A pointer to the character string to be sent.
string_len: (Input)
The length of above character string.
Returns:
0 - no error.
Notes:
MTB741-07 MOWSE Design
Reset Capability: ws_$reset_capability, resetcap
Reset capability provides an application with the means of
resetting a capability on the local or remote system. This is
done by stopping execution on capability, flushing out its
input and output buffers, and starting up the capability
again.
The following is a description of the method which MOWSE
employs to support the request.
LOCAL SYSTEM REMOTE SYSTEM
{major_cap}
app ----------->reset_capability
<------------------+======> RESET_APPLICATION
++---> app (RESET_APPLICATION)
||
app (RESET_REPLY) <=======/ RESET_REPLY generated
When an application requests a capability to be reset, there
are two cases of execution: one is the capability on the
local and the other is when the capability is on the remote.
If the capability is not found, this call will be ignored.
In the local case, the application to be reset will be
immediately notified through the predefined minor capability
RESET_APPLICATION. All pending messages that are from the
application to be reset to the requesting application will be
removed from the queue. Once the application has handled the
reset and returns (to MOWSE), an automatic RESET_REPLY is sent
to the capability issuing the RESET. In the remote case,
MOWSE will set a flag indicating that the specified
application is being reset, thus all messages from the
specified application to the requesting application will be
discarded until MOWSE gets the RESET_REPLY internal MOWSE
message. The application being requested to be reset will be
notified through the predefined minor capability
RESET_APPLICATION (identical to the case of the local reset).
When the application has completed the RESET operation, a
RESET_REPLY will be sent back to the originating system (as in
the local case). Upon receipt of this message, the flag set
will be cleared and the RESET_REPLY message passed to the
originating capability.
MOWSE Design MTB741-07
Multics Entry: ws_$reset_capability
Function:
Tells MOWSE to reset the specified application. The
application to be reset is notified via the predefined minor
capability RESET_APPLICATION.
Syntax:
dcl ws_$reset_capability entry
(fixed bin(17),
ptr,
fixed bin(35));
call ws_$reset_capability
(major_number,
mcb_ptr,
code);
Arguments:
major_number: (Input)
The major capability number of the application to be
reset.
mcb_ptr: (Input)
A pointer to the mcb of the application executing the
function.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$reset_capability (bft_major_cap, code);
Notes:
MOWSE notifies the application through the predefined minor
capability RESET_APPLICATION and clears all of the flags
associated with the application. All messages occuring
between the request and the completion of the request will be
discarded by MOWSE.
MTB741-07 MOWSE Design
PC Entry: resetcap - reset_capability
Function:
Tells MOWSE to reset the specified application. The
application to be reset is notified via the predefined minor
capability RESET.
Syntax:
int resetcap (major_number, mcb_ptr);
int major_number;
mcb *mcb_ptr;
Arguments:
major_number: (Input)
The major capability number of the application to be
reset.
mcb_ptr: (Input)
The pointer to the caller's MOWSE Control Block.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = resetcap (bft_major_cap, mcb_ptr);
Notes:
MOWSE notifies the application through the predefined minor
capability WSRSTAPP and clears all of the flags associated
with the application. All messages occuring between the
request and the completion of the request will be discarded by
MOWSE.
MOWSE Design MTB741-07
Resume Capability: ws_$resume_capability, resume
Resume capability provides an application with the means of
resuming a capability which has been suspended through a call
to suspend_capability.
The following is a description of the method which MOWSE
employs to support the request.
LOCAL SYSTEM REMOTE SYSTEM
{major_cap}
app ----------->resume_capability
<-----------------+
|
|===> app(RESUME_APPLICATION)
|
V
app (RESUME_APPLICATION)
When an application requests a capability to be resumed, there
are two cases of execution: one is the capability on the
local and the other is when the capability is on the remote.
If the capability is not already suspended or is not found,
this call will be ignored.
In the case that the specified capability is local, the
capability will be notified immediately via the predefined
minor capability RESUME_APPLICATION. In the remote case, a
message will be generated to the remote system and the
application will be notified in the same manner.
MTB741-07 MOWSE Design
Multics Entry: ws_$resume_capability
Function:
Tells MOWSE to resume the specified application. The
application to be resumed is notified via the predefined minor
capability RESUME_APPLICATION.
Syntax:
dcl ws_$resume_capability entry
(fixed bin(17),
ptr,
fixed bin(35));
call ws_$resume_capability
(major_number,
mcb_ptr,
code);
Arguments:
major_number: (Input)
The major capability number of the application to be
resumed.
mcb_ptr: (Input)
A pointer to the mcb of the application executing this
function.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$resume_capability (bft_major_cap, code);
Notes:
If the specified capability is not in suspension, the request
will be ignored. The capability to be resumed is informed via
the predefined minor RESUME_APPLICATION.
MOWSE Design MTB741-07
PC Entry: resume - resume_capability
Function:
Tells MOWSE to resume the specified application. The
application to be resumed is notified via the predefined minor
capability RESM.
Syntax:
int resume (major_number, mcb_ptr);
int major_number;
mcb *mcb_ptr;
Arguments:
major_number: (Input)
The major capability number of the application to be
resumed.
mcb_ptr: (Input)
The pointer to the caller's The MOWSE Control Block.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = resume (bft_major_cap, mcb_ptr);
Notes:
If the specified capability is not in suspension, the request
will be ignored. The capability to be resumed is informed via
the predefined minor WSRSMAPP.
MTB741-07 MOWSE Design
Send Query Reply: ws_$send_query_reply, sendqrep
In the case that the background message type is a query
message from a call to get_background_message, the foreground
application which retrieved the message must obtain a response
from the user and provide the results to the application which
sent the query message. The reply is done by
send_query_reply. A query message must be less than or equal
to PACKET_SIZE characters in length.
The following is a description of the method which MOWSE
employs to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{major_cap + response}
app --------------> send_query_reply
<----------------------+
|{response}
|=====> app(QUERY_REPLY)
+
V
app (QUERY_REPLY)
The application which is replying with the message calls the
MOWSE routine send_query_reply with the response and the major
capability number of the application which made the request
for background query (via put_background_message). MOWSE then
sends the message to the appropriate application with the
predefined minor capability background_query_reply.
MOWSE Design MTB741-07
Multics Entry: ws_$send_query_reply
Function:
Send the user's response to a query message to the originator
of the background query message (see
ws_$get_background_message).
Syntax:
dcl ws_$send_query_reply entry
(char(*),
fixed bin(17),
fixed bin(35));
call ws_$send_query_reply
(reply_string,
destination_major,
code);
Arguments:
reply_string: (Input)
The user's response to the query message obtained through
a call to ws_$get_background_message.
destination_major: (Input)
The major capability number of the application which is to
receive this response string (see
ws_$get_background_message).
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$send_query_reply (user_response, sender_major,
code);
Notes:
A call to this procedure must be performed whenever a
QUERY_MESSAGE type is returned from ws_$get_background_message
as the requesting application is waiting for the response.
Currently, ws_$send_query_reply is a null routine, as only the
terminal emulator is capable of such functions.
MTB741-07 MOWSE Design
PC Entry: sendqrep - send_query_reply
Function:
Send the user's response to a query message to the originator
of the background query message (see "getbgmes").
Syntax:
int sendqrep (reply_string, destination_major);
char *reply_string;
int destination_major;
Arguments:
reply_string: (Input)
The user's response to the query message obtained through
a call to "getbgmes".
destination_major: (Input)
The major capability number of the application which is to
receive this response string (see "getbgmes").
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = sendqrep (user_response, sender_major);
Notes:
A call to this procedure must be performed whenever a WSQUERY
type is returned from "getbgmes" as the requesting application
is waiting for the response.
MOWSE Design MTB741-07
Sleep: ws_$sleep, wssleep
An application may request MOWSE to cause itself to sleep for
an amount of time, in seconds, thus ignoring all messages with
the exception of TERMINATE_APPLICATION and RESET_APPLICATION.
The following is a description of the method which MOWSE
employs to support the request:
LOCAL SYSTEM REMOTE SYSTEM
{time}
app ------> sleep =====================> SET_SLEEP_FLAG
(time_up) ====================> RESET_SLEEP_FLAG
|
V
app(WAKE_UP)
When an application requests the sleep, MOWSE sets an internal
flag that specifies that the application is sleeping. MOWSE
then sends a message to the remote system to let it know that
an application has been set to sleep. The remote system then
sets its sleep flag for that specified application.
When the specified time period has elapsed, MOWSE clears the
local sleep flag and sends a message to the remote system so
that the remote system can clear its sleep flag for the
application (through the internal function RESET_SLEEP_FLAG).
MOWSE also "awakens" the sleeping application with a
predefined minor capability WAKE_UP.
When a capability is sleeping, all messages to it are refused,
with the exception of TERMINATE_CAPABILITY and WAKE_UP.
MTB741-07 MOWSE Design
Multics Entry: ws_$sleep
Function:
Forces the calling application to sleep (suspend execution)
for the specified number of seconds. When an application is
put to sleep, it cannot accept any messages except
TERMINATE_CAPABILITY and RESET_CAPABILITY. The calling
application will be notified through the predefined minor
capability WAKE_UP.
Syntax:
dcl ws_$sleep entry
(ptr,
fixed bin(17)
fixed bin(35));
call ws_$sleep
(mcb_ptr,
time,
code);
Arguments:
mcb_ptr: (Input)
A pointer to the mcb of the application executing this
function.
time: (Input)
The number of seconds the application is to sleep.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$sleep (mcb_ptr, 10);
Notes:
The application is notified to awaken via the predefined minor
capability WAKE_UP.
MOWSE Design MTB741-07
PC Entry: wssleep - sleep
Function:
Forces the calling application to sleep (suspend execution)
for the specified number of seconds. When an application is
put to sleep, it cannot accept any messages except TERM and
RESET. The calling application will be notified through the
predefined minor capability WSWAKEUP when the specified time
has elapsed.
Syntax:
int wssleep (time, mcb_ptr);
int time;
mcb *mcb_ptr;
Arguments:
time: (Input)
The number of seconds the application is to sleep.
mcb_ptr: (Input)
The pointer to the application's MOWSE control block
assigned by a call to "cretinst".
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
wssleep (10);
Notes:
The application is notified to awaken via the predefined minor
capability WSWAKEUP.
It is important that MOWSE applications use this sleep
function as opposed to the sleep routine provided by the
standard "C" library as MOWSE cannot perform anything until
the application has returned to it, thus all further message
processing would be suspended until the call to the "C" sleep
has expired.
MTB741-07 MOWSE Design
PC Entry: stayres - terminate_and_stay_resident
Function:
To terminate execution of a MOWSE capability at the end of its
initialization and keep its object code resident in the PC's
memory for later invocations through "execap" calls.
Syntax:
stay_res (mcb_ptr);
mcb *mcb_ptr;
Arguments:
mcb_ptr: (Input)
The pointer to the application's MOWSE Control Block
assigned by a call to "cretinst".
Returns:
A call to "stayres" will not return.
MOWSE Design MTB741-07
Suspend Capability: ws_$suspend_capability, suspend
Suspend capability provides an application with the means of
suspending a capability on the local or remote system. This will
decrease the burden on the CPU running the capability.
The following is a description of the method which MOWSE employs
to support the request.
LOCAL SYSTEM REMOTE SYSTEM
{major_cap}
app ----------->suspend_capability
<----------------+
|
|===> app(SUSPEND_APPLICATION)
|
V
app (SUSPEND_APPLICATION)
When an application requests a capability to be suspended, there
are two cases of execution: one is the capability on the local
and the other is when the capability is on the remote. If the
capability is not found, or the capability is already in
suspension, the command will be ignored by MOWSE.
In the case that the specified capability is local, the
capability will be notified immediately via the predefined minor
capability SUSPEND_APPLICATION. In the remote case, a message
will be generated to the remote system and the application will
be notified in the same manner.
When a capability is suspended, all messages sent to it are
refused, with the exception of TERMINATE_APPLICATION and
RESUME_APPLICATION. If the capability is suspended, then refused
messages are returned as an execute_capability_reply
(FAIL_CAPABILITY). A capability suspended will not be allowed to
send messages.
MTB741-07 MOWSE Design
Multics Entry: ws_$suspend_capability
Function:
Tells MOWSE to suspend the specified application. The
application to be suspended is notified via the predefined
minor capability SUSPEND_APPLICATION. A suspended application
is unable to send or receive messages.
Syntax:
dcl ws_$suspend_capability entry
(fixed bin(17),
ptr,
fixed bin(35));
call ws_$suspend_capability
(major_number,
mcb_ptr,
code);
Arguments:
major_number: (Input)
Capability number of the application to be suspended.
mcb_ptr: (Input)
A pointer to the mcb of the application executing this
library function.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$suspend_capability (bft_major_cap, code);
Notes:
The specified application will be suspended - unable to send
or receive messages - by MOWSE until a call to
ws_$resume_capability has been called for that application.
MOWSE Design MTB741-07
PC Entry: suspend - suspend_capability
Function:
Tells MOWSE to suspend the specified application. The
application to be suspended is notified via the predefined
minor capability WSSUSAPP. A suspended application is unable
to send or receive messages.
Syntax:
int suspend (major_number, mcb_ptr);
int major_number;
mcb *mcb_ptr;
Arguments:
major_number: (Input)
Capability number of the application to be suspended.
mcb_ptr: (Input)
The pointer to the caller's MOWSE Control Block.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = suspend (bft_major_cap, mcb_ptr);
Notes:
The specified application will be suspended - unable to send
or receive messages - by MOWSE until a call to "resume" has
been called for that application.
MTB741-07 MOWSE Design
Terminate Capability: ws_$terminate_capability, termcap
Terminate capability provides an application with the means of
requesting that another capability terminate itself (i.e.
destroy_instance), thus terminating a capability on the local
or remote system. This is done by clearing and deleting all
information associated for a given capability on both systems.
The following is a description of the method which MOWSE
employs to support the request.
LOCAL SYSTEM REMOTE SYSTEM
{major_cap}
app -----------> terminate_capability
<-------------------+
|
|========> app (TERMINATE_APPLICATION)
|
V
app (TERMINATE_APPLICATION)
When an application requests a capability to be terminated,
there are two cases of execution: one is the capability on
the local and the other is when the capability is on the
remote. If the capability is not found, this call will be
ignored.
In the case that the specified capability is local, the
capability will be notified immediately via the predefined
minor capability TERMINATE_APPLICATION. In the remote case, a
message will be generated to the remote system and the
application will be notified in the same manner.
MOWSE Design MTB741-07
Multics Entry: ws_$terminate_capability
Function:
Tells MOWSE to terminate the specified application. The
application to be terminated is notified via the predefined
minor capability TERMINATE_APPLICATION.
Syntax:
dcl ws_$terminate_capability entry
(fixed bin(17),
ptr,
fixed bin(35));
call ws_$terminate_capability
(major_number,
mcb_ptr,
code);
Arguments:
major_number: (Input)
The major capability number of the application to be
terminated.
mcb_ptr: (Input)
A pointer to the mcb of the application executing this
function.
code: (Output)
The error code immediately returned from MOWSE.
Values:
0 - no error
Or a standard Multics system error code.
Example:
call ws_$terminate_capability (bft_major_cap, code);
Notes:
MOWSE will remove the specified application from its
capability table after the application has been notified.
MTB741-07 MOWSE Design
PC Entry: termcap - terminate_capability
Function:
Tells MOWSE to terminate the specified application. The
application to be terminated is notified via the predefined
minor capability WSTRMAPP.
Syntax:
int termcap (major_number, mcb_ptr);
int major_number;
mcb *mcb_ptr;
Arguments:
major_number: (Input)
The major capability number of the application to be
terminated.
mcb_ptr: (Input)
The MOWSE Control Block of the calling capability.
Returns:
0 - no error
Or an error code defined in the appendix.
Example:
ecode = termcap (bft_major_cap, mcb_ptr);
Notes:
MOWSE Design MTB741-07
4.3. Dedicated Minor Capability Numbers
The primary purpose of the MOWSE environment is to provide a
means in which applications on one system may request the
capabilities of applications on another system. In order for
MOWSE to be able to perform such operations for the applications,
MOWSE must be able to know of all the capabilities on each of the
systems established in the MOWSE environment. This knowledge is
maintained in two tables called the Capability Address Tables
(CAT) (see section 3.4).
When an application requests the services of a capability, it
requests the software library function "execute_capability"
specifying the function of the requested capability (minor
capability) and the argument data for the requested application.
MOWSE then takes the data provided by the requesting application
and formulates a message to send to the remote system.
The remote system is then informed of the request via the
External MOWSE Function and the requested application is
executed. An application may provide many types of functions of
which another application may make use of. These capability
functions are identified by a minor capability number of which
the requesting application has knowledge.
These minor capability numbers provide two important mechanisms
which MOWSE makes use of. One mechanism is as described above in
which a requesting application may specify a specific function of
the requested application.
The second is to provide a means for MOWSE to inform the
application of some specific event. An example of such a
"specific" event is when an application requests
"execute_command" for a remote system and MOWSE on the remote
system experienced an error in the attempt to execute the
request. The only manner in which to inform the requesting
application is to invoke it with a minor capability which
describes the event. Thus MOWSE requires certain "dedicated"
minor capability numbers which must be supported by each MOWSE
application. The values of these dedicated minor capabilities
will be in the range of 0 - 31, thus allowing the application to
use the values 32 - 127 for its own purposes.
The following is a description of each of the dedicated minor
capability numbers which MOWSE requires that each MOWSE
application support. These are used to communicate special
events between MOWSE and application programs.
MTB741-07 MOWSE Design
Argument data which is returned through these minor capabilities
will have the fields separated by a ";". In the following
descriptions, the argument fields will be specified by name, and
then the number of characters which comprise of the field and the
type of the field.
Execute Capability Failure: FAIL_CAPABILITY, WSFAILCP
In the event that an attempt to begin execution of a
capability caused problems, the application which generated
the request is informed of the problem via this minor
capability. The reason for this is to provide the requesting
application with control as there will be no return of control
due to a message by the requested capability.
Argument Data:
No data is required.
Execute Command Reply: EXECUTE_COMMAND_REPLY, WSCOMREP
When an application requests a system command, it will be
notified when the command has completed execution. The
contents of the data will indicate whether or not the command
succeeded and a new major capability number if the call
resulted in an application being loaded.
Argument Data:
command_id: char 2; integer
status: char 1; integer (32 - succeeded, 33 - failed)
Query Reply: QUERY_REPLY, WSQRYREP
When the remote foreground application has performed the
requested query, it is the responsibility of that foreground
application to generate a call to ws_$send_query_reply with
the user's response. The application waiting for the reply is
notified through this minor capability.
Argument Data:
free format: up to the application
Suspend Application: SUSPEND_APPLICATION, WSSUSAPP
When an application requests that the specified application be
"suspended", the application to be suspended is notified
through this minor capability. This allows an application to
temporarily suspend an application which is consuming
tremendous amounts of the CPU.
Argument Data:
No data is required.
MOWSE Design MTB741-07
Resume Application: RESUME_APPLICATION, WSRSMAPP
An application which has been "suspended" through
ws_$suspend_capability can be resumed through this minor
capability.
Argument Data:
No data is required.
Terminate Application: TERMINATE_APPLICATION, WSTRMAPP
A remote application may request that an application be
terminated. This is accomplished through notification by this
minor capability. It is up to the notified application to
perform the clean up functions necessary. When the
application returns to MOWSE, it will be removed from the
capability tables.
Argument Data:
No data is required.
Request Connect: REQUEST_CONNECT, WSRQSTCN
A remote application may request to connect to the
application. The application must then perform the necessary
functions to accept or reject the request.
Argument Data:
No data is required.
Request Disconnect: REQUEST_DISCONNECT, WSRQSTDS
A remote application may request to disconnect from the
application. The application must then perform the necessary
functions to accept or reject the request.
Argument Data:
No data is required.
Reset Application: RESET_APPLICATION, WSRSTAPP
A remote application may request that the specified
application "start again". This can be used if the requesting
application detects some confusion and requires everything to
be started again.
Argument Data:
No data is required.
Response Connect: RESPONSE_CONNECT, WSRESPCN
MTB741-07 MOWSE Design
The request for connection to an application has completed,
and the status of rejection or acceptance is provided.
Argument Data:
major_cap: char (2); integer (WS)ACCEPT, (WS)REJECT
status: char (1); integer
Response Disconnect: RESPONSE_DISCONNECT, WSRESPDS
The request for disconnection from an application has
completed, and the status of rejection or acceptance is
provided.
Argument Data:
major_cap: char (2); integer (WS)ACCEPT, (WS)REJECT
status: char (1); integer
Wake Up: WAKE_UP, WSWAKEUP
When the specified time period of the library function "sleep"
has elapsed, MOWSE sends to the sleeping application a message
which indicates that the sleep period is up.
Argument Data:
No data is required.
Status: STATUS, WSSTATUS
An application may request status information from another
application, the requested application is notified through
this minor capability.
Argument Data:
free format: up to the calling application
Receive Buffer Overflow: OVERFLOWED_BUFFER, WSOVRFLW
In the event that a message exceeded the maximum size of the
receive buffer which was provided by the application, this
minor capability will inform the application of the error.
Argument Data:
free format: what is currently in the buffer
System Error: SYSTEM_ERR0R, WSSYSERR
In the event that MOWSE detects an unrecoverable error, this
message will be passed on to the application for which the
error occurred.
MOWSE Design MTB741-07
Argument Data:
No data is required.
MTB741-07 MOWSE Design
4.4. Video Manager
This section describes the general framework of implementing
support for the use of the Multics Video system in conjunction
with MOWSE. Four sections are included below: an overview, a
general description of the protocol used to implement negotiated
echoing, changes to the video system proper and new support
modules are discussed.
The intent of the proposed enhancements to the video system is to
cause echoing of input to be done by the remote PC terminal
emulator instead of either the Multics hardcore supervisor or the
user ring video system code. Full echo negotiation support is to
be provided.
Overview
The general structure of the current video system lends itself to
changes to allow use of video with the MOWSE protocol. Real I/O
in video is done by direct calls to the Multics supervisor via
the hcs_$tty_xxx entrypoints. These calls are isolated to a
small number of modules. In fact, support for DSA echo
negotiation is currently being implemented by providing parallel
interfaces and making relatively minor changes to the video
system.
Currently, echoing is performed either by the Multics FNP, by the
Multics supervisor or by user ring code such as the video system
or EMACS. Supervisor or user ring echoing occurs when either FNP
support is not available (X.25 network access) or in response to
typing ahead while processing of non-echoed characters is done.
The new DSA support moves echoing out to the remote front end (if
you will) with host side echoing provided by either the host
resident DSA support code or user ring video system code. Echo
negotiation is the process of determining at which point a
character is to echoed.
In the above cases, a protocol for negotiation of the
distribution of character echo forms the basis of operation. For
the proposed Video with MOWSE case, such a protocol is needed.
MOWSE Design MTB741-07
One possibility is to mimic the current host to FNP protocol. A
second choice would be to use a different method. Such a
protocol has been specified in MTB-708 published by Barry
Margolin. It seems that this protocol will offer the needed
functionality and it appears to be much easier to implement than
the FNP model. The implementation proposed here is a modified |
version of Barry's protocol. As the protocol is being |
implemented above MOWSE, the major change is that escape
sequences for protocol exchange are not used. Instead, specific
minor capabilities can be used to identify each required
function.
The specific details of the protocol are described in the section
describing the new modules.
The diagram in Figure 1 (below) depicts the process terminal |
I/O routings that are possible after implementation of MOWSE
video support. The vertical path labelled (1) shows the
conventional routings when a user process is not using either the
video system or MOWSE. Path (2) represents the case of video
being in effect without MOWSE. Paths (3) and (4) show the I/O
streams when MOWSE is in effect without and with the video
system, respectively.
(1) (2) (3) (4)
user_i/o user_i/o user_i/o background user_i/o background
-------- -------- -------- ---------- -------- ----------
| | | | | |
tty_ window_io_ | | window_io_ |
| tc_io_ | | tc_io_ |
| | | | | |
| | | | ws_tty_ |
| | | | | |
| | ___ ___/ ___ ___/
| | / /
| | mowse_io_ mowse_io_
| | | |
_____________ __________/____________________/
/
hcs_
|
TERMINAL
Figure 1 - Possible I/O Routings |
General Protocol Description
MTB741-07 MOWSE Design
The protocol that will be implemented between the ws_tty_ modules
and the terminal emulator in the PC is a synchronous protocol.
This means that the Multics host side of the protocol is in
control of the link. The terminal emulator is not to generate
any input to the host unless it has received a prior request that
requires the emulator to respond either with an acknowledgement
or with input data. The only exception to this is a message
generated to signal a break condition to the host.
All communication between Multics and the emulator will be via
MOWSE minor capabilities, most of which carry either additional
parameters, text data or both.
minor cap name abbrev sender receiver |
------------------- --------- --------- -------- |
Set-Break-Table SBT ws_tty_ TE |
Display-Text DT ws_tty_ TE |
Abort A ws_tty_ TE |
Read-With-Echo RWE ws_tty_ TE |
Read-No-Echo RNE ws_tty_ TE |
Enter-Sync-Mode ESM ws_tty_ TE |
Exit-Sync-Mode XSM ws_tty_ TE |
Exited-Sync-Mode SMX TE ws_tty_ |
End-Echoed-Input EEI TE ws_tty_ |
End-Unechoed-Input EUI TE ws_tty_ |
------------------------------------------------ |
Table 1 Minor Capabilities Required for Video Support |
Initially, the terminal emulator is operating in an asynchronous
mode under which characters input at the keyboard are transmitted
to the host at the discretion of the emulator. Invoking the
modified video system on the host will result in the emulator
being instructed to operate in synchronous mode. Revokation of
the video system causes the emulator to return to asynchronous
mode.
If the video system is invoked after the MOWSE system is running
on both Multics and the PC and the async TE is running, a minor
capability of Enter-Sync-Mode will be sent from Multics to the TE
informing it of the change in I/O environment. This is an
environment in which the TE will be expected to manage a "smart"
video display in conjunction with windowing software on the host.
MOWSE Design MTB741-07
The primary functions that the TE is to perform are display of
text with embedded screen control and the provision of negotiated
local character echoing. This is to be done under the control of
a table referred to as the break table which defines those
characters that are to be echoed locally. All other characters
are to cause transmission to Multics. No processing local to the
TE other than echo determination is to be performed on input
characters.
As its name suggests, this emulator must operate in a synchronous
environment. With the exception of handling a break, it is to
send data to Multics only when asked to do so.
As mentioned above, sync mode is entered upon receipt of a
min-cap of Enter-Sync-Mode. When in sync mode, the TE may
receive minor capability messages from the list: Exit-Sync-Mode,
Set-Break-Table, Display-Text (this may be the same min-cap that
the async TE uses), Abort (this may also be used by async TE),
Read-With-Echo or Read-No-Echo.
The default, or initial, break table specifies all characters as |
break characters; no characters are to be echoed until a new |
break table is received. Also, this default break table is to be |
assumed after each Enter-Sync-Mode mincap is received; that is, |
break tables are not to be 'remembered' across invokations of the |
SYNC TE. The TE is to assume a state of broken echo and is to |
hold all new type in until a Read type min-cap is received.
The Set-Break-Table min-cap message will consist of a list of
those ASCII graphic characters that are NOT to be echoed locally
but instead cause echoing to break down (hence the name break
table). The ASCII control codes (000 through 037 octal) and the
RUBOUT (177) character are always assumed to be non-echoable
characters. All ASCII graphics not listed are to be assumed
echoable. The new table supersedes any existing table.
When the TE receives the min-cap Exit-Sync-Mode, it is to respond
with a min-cap message of Exited-Sync-Mode acknowledging this.
It is to now operate in async mode. Any type ahead may be
replayed through the async input routines (or discarded).
The Display-Text min-cap message from Multics may contain display
text data or display control information or both. The TE is to
interpret the control information. If there is an outstanding
Read pending in the TE, it is to send the type ahead as described
below. In any case, the TE is to stop echoing immediately upon
receipt.
MTB741-07 MOWSE Design
When in Sync mode, the TE may only send input to the host in
response to either a Read-With-Echo (RWE) or a Read-No-Echo (RNE)
min-cap request. The two reads support local echoing of input
and input without echoing to the TE display. When input is
processed by the TE in sync mode, no interpretation of characters
is to occur except for break character checking and possibly the
handling of an "escape to TE control" character. If such local
escape is implemented, provision for input of the escape
character must be made as Sync mode input is generally considered
to allow all 128 7-bit ASCII codes. The display must be restored
to its state at the point that the escape was issued.
The RWE min-cap contains a numeric argument which specifies a
limit on the number of characters to be echoed prior to
transmission to the host. This is generally the number of
positions remaining from the cursor to the right display edge.
The RNE min-cap also contains a limit value but it specifies the
number of characters to buffer prior to transmission; echoing is
not performed by an RNE. In either case, if TE has a limited
input buffer, it is to consider the limit as the minimum of the
received limit and the buffer size.
If the TE is holding an outstanding read and it receives any
message from the host, it is to immediately transmit any buffered
input before processing the message. If it was handling an RWE,
the characters are sent under the min-cap End-Echoed-Input (EEI)
whereas an End-Unechoed-Input (EUI) is used to close off a
pending RNE.
The RWE function uses the current break table (as received with
the last SBT min-cap) to determine whether local character
echoing is to continue. Each input character is checked against
the table; if it is present, local echoing breaks down (hence the
name break table). Any echoed characters are sent under the
min-cap EEI and echoing stops. The break character may be sent
with the echoed characters. Similarly, if echo stops because an
input character causes limit exhaustion, that character is sent
but it will have been echoed. Subsequent input is to be held
awaiting a read min-cap from the host.
It should be noted that upon the receipt of any host message, if
the TE is holding an outstanding Read, it must respond with the
appropriate End min-cap even if there is no buffered input
(echoed or not).
As noted above, following a break condition input is buffered but
not echoed. When an RNE is received, if there is any buffered
input an EUI min-cap message is generated. For all read min-caps |
the read limit value specifies the upper bound on the reply. Any |
excess characters are to be held in the TE for subsequent reads. |
MOWSE Design MTB741-07
If an RWE is received, the preferable action for the TE is to |
play back any (unechoed) buffered input through the echo process |
breaking at the appropriate point. But the TE may respond with |
an empty EEI as well. |
If an RNE is received and the TE holds no type ahead, one of two
actions occurs. If the RNE ask for blocking, the TE is to buffer
input without echoing until either the limit is exhausted or a
host message arrives. If no blocking was asked for, the TE is to
respond with an immediate empty EUI.
Video System Changes
General Structure of Changes:
The changes to the video system will be modelled after the
changes currently being implemented for the DSA project. The DSA
changes are roughly structured such that any call to hcs_$tty_xxx
is replaced by a call to either hcs_$tty_xxx or to the new entry
point dsa_tty_$xxx (in most cases). Support for MOWSE will add a
new entry point named ws_tty_$xxx which has the same interface
functionality as the entry point hcs_$tty_xxx. For example, a
new entry point named ws_tty_$read_echoed will be provided. This
entry point will behave in the same way as hcs_$tty_read_echoed
and dsa_tty_$read_echoed do.
New Entrypoints Provided for Video Changes:
The following entry points will be provided:
ws_tty_$abort
ws_tty_$attach
ws_tty_$detach
ws_tty_$event
ws_tty_$index
ws_tty_$order
ws_tty_$read_echoed
ws_tty_$read |
ws_tty_$write
ws_tty_$write_whole_string
These routines will provide the interface between tc_io_ (and its
internal modules) and the ws_ subroutine. The interfaces will be
identical to those provided by the corresponding hcs_$tty_
modules. Parameters will have the same data types and will serve
the same functions.
Changes to network_ids.incl.pl1:
MTB741-07 MOWSE Design
An additional 'network_type' value will be added to the new
include file network_ids.incl.pl1. This will be the constant
MOWSE_NET with a value yet to be decided. For most calls on
hcs_, the following code framework can then be used:
if tc_data.network_id = DSA_NET then
call dsa_tty_$<function> (...);
else if tc_data.network_id = MOWSE_NET then
call ws_tty_$<function> (...);
else if tc_data.network_id = MCS_NET then
call hcs_$tty_<function> (...);
else call O_BOY_WE_HAVE_A_PROBLEM;
Changed Video System Modules:
The following modules in the video system will require changes:
tc_.pl1
tc_input.pl1
tc_io_.pl1
tc_request.pl1
video_utils_.pl1
Of these module changes, those to video_utils_.pl1 will be the
most complex. This module provides video invocation and
revocation services for application programs. For this change,
it must find the current attachment of the user_i/o switch, but
it must not close and detach it before invoking video on the
underlying terminal stream. As other MOWSE traffic may already
be in progress, the attachment through the mowse_io_ i/o module must
be removed without affecting the lower level attachment through
tty_.
The remaining changes fall into the framework outlined above.
This process can be expedited by examining the changes being
implemented for the DSA project.
New Module Descriptions
As mentioned above, the following new entry points will be
provided in support of video system use with MOWSE:
MOWSE Design MTB741-07
ws_tty_$abort
ws_tty_$attach
ws_tty_$detach
ws_tty_$event
ws_tty_$index
ws_tty_$order
ws_tty_$read_echoed
ws_tty_$read |
ws_tty_$write
ws_tty_$write_whole_string
Of the above interfaces, several appear to be relatively simple
to implement in the Multics host side. Minimal support would be
needed in the PC TE. These interfaces are:
tty_abort
- dump any buffered input and stop echo
tty_event
- host side only event channel management
tty_index
- host side only
tty_order
- most video control orders are handled exclusively
by ring 4 video system code and few calls on
hcs_$tty_order are made
- set_break_table is the most notable exception. This
will need support in the TE.
The attachment and detachment routines will interact with the PC
by establishing and reverting SYNC mode (as described in Barry's
MTB-708). Some host side work is needed to connect video to
MOWSE.
tty_attach
- establish environment for video/MOWSE communications
Turns on SYNC mode in PC TE.
tty_detach
- put MOWSE environment back to state before video
Turn off SYNC mode in TE.
The remaining entries deal with actual I/O. The easiest I/O
primitives are the write calls. These would interact with the TE
by causing it to stop echo, forward any held keyboard input and
display received data.
tty_write
- TE displays text (interpreting control sequences
if appropriate)
MTB741-07 MOWSE Design
tty_write_whole_string
- same as tty_write. Host side MOWSE code must
ensure no other TE bound characters intervene
if the string does not fit into a single MOWSE
packet.
*
The read entry points are more complex and at this point still
need further study to determine the underlying design for
implementation. In their current implementation, these
interfaces have several 'kludge' uses to turn echoing off when
certain argument values are used (eg, line size of 0). Host
echoing is also performed by the hcs_$tty_read* entrypoints if
echo negotiation races are detected. In the MOWSE support case,
this echoing will not be done. The video system already
implements host echoing and this will be sufficient for those
cases requiring it. (No major efficiency loss should occur, as
the expensive process wakeup will already have occurred in either
case.)
These entrypoints will require that the TE support the READ
functions as described in MTB-708. These are actually one
command with 3 parameters:
READ echoed/unechoed, 0/non-0 limit, block/no-block
The entrypoints are:
tty_read_echoed
- in all but the 'kludge' cases this is the echo
negotiated read initiator. The TE would be given
the command READ(echoed,limit=screen left,block).
- echoing stops on a break character.
- type ahead is not echoed by TE
tty_read |
- this is an unechoed read
*
Magnitude of Video system changes
The total changes to the video system for DSA involve on the
order of 500 lines of code modifications and additions. The work
required for MOWSE should be of this order. As noted above, much
of these changes is very straight forward and simple. The bulk
of the work has been done in identifying and implementing changes
for DSA support.
MOWSE Design MTB741-07
5. MOWSE Major Capabilities
The MOWSE Internal Functions provide MOWSE with a means of
communicating special information between each of the MOWSE
components on the systems using the MOWSE environment. For
instance, MOWSE must maintain certain data information such as
the Capability Address Table (CAT) which keeps track of
applications which are known to MOWSE. It is necessary for all
of the "MOWSEs" to know about this information and each must be
told of changes to this information. This is done through
internal MOWSE functions.
The following is a description of the functions which are
performed by each of the Internal MOWSE Functions.
EXECUTE_COMMAND
When the application running on the remote system requests
the library function "execute_command" this MOWSE function
is invoked which causes the specified command to be
executed on the local system.
This function is to be used primarily to load MOWSE
applications on the local system. The application that
made the request (from the remote system) should be a
MOWSE application that is identified in the CAT. The
reason for this is that a return error message must have
somewhere to go in the event of a failure.
A message will be returned via "execute_command_reply" to
the remote system. This message will indicate whether the
"execute_command" succeeded or failed.
ADD_TO_REMOTE_CAT
When a MOWSE application on the remote system adds itself
to the CAT via the library call "create_instance", this
function updates the local CAT for the remote system.
DELETE_FROM_REMOTE_CAT
When a MOWSE application on the remote system deletes
itself from the CAT via the library call
"destroy_instance", this function updates the local CAT
for the remote system.
PUT_TO_SCREEN_BUFFER
MTB741-07 MOWSE Design
This function places the contents of the message directly
into the terminal buffer as the result of a remote
application requesting the library function
"put_terminal_data" . The foreground application, which
is handling I/O such as the terminal emulator, is
responsible for the display of this buffer.
PUT_TO_BACKGROUND_BUFFER
When the application running on the remote system requests
one of the functions "put_error_message",
"put_background_message", or "put_background_query", MOWSE
places the contents of the message directly into the
background message buffer of the MOWSE which is
responsible for user I/O. If this MOWSE component
contains this responsibility, the information is passed
via this MOWSE function. The foreground application which
is handling I/O such as the terminal emulator is
responsible for the display of the contents of this
buffer.
A message will be returned to "background_message_reply"
on the remote system. This message will indicate whether
the placing of the contents of the message into the buffer
succeeded or failed.
BACKGROUND_MESSAGE_REPLY
After a local MOWSE application has requested a
"put_to_background_buffer" on the remote system, this
function will be invoked indicating that the request to
place a message into the background buffer was completed
on the remote system.
If the message indicates a failure in the attempt to place
the message into the background message buffer on the
remote system, the background message is stored in a local
queue of background messages for future extraction by the
remote system through "extract_background_message".
EXTRACT_BACKGROUND_MESSAGE
When the application running on the remote system requests
the function "display_background_message" this MOWSE
function is invoked on the local system only if the
remote's background buffer is empty yet it knows that
there are pending background messages in the local queue.
If there are any messages in the queue, each of the
pending messages are sent to the remote system via
"put_to_background_buffer".
MOWSE Design MTB741-07
SET_SLEEP_FLAG
A remote application may request the library function
"sleep", usually because all error and message buffers are
full. At this request, no messages are allowed to the
application, with the exception of "terminate_capability"
and "reset_capability", until the remote application has
"awaken". This forces all calls to "execute_capability"
by a local application to fail until the sleep period of
the application has expired.
This function sets the sleep flag in the Multics CAT, for
the specified application.
RESET_SLEEP_FLAG
When the specified sleep time period of a remote
application has expired, the remote system sends the
"reset_sleep_flag" request to the local MOWSE. This
causes MOWSE to clear the sleep flag in the CAT of the
entry of the application specified. This allows
subsequent calls to the remote application (via the
library function "execute_capability") to pass through to
the remote capability.
RESET_REPLY
When an application requests that another application be
reset, MOWSE will set a flag so that it may ignore all
messages which may occur between the time which the
reset_capability request was made and when the application
to be reset was notified. This internal function tells
MOWSE to clear the "being reset" flag for the reset
application.
REQUEST_CONNECT
A remote application may request to connect to the
application. The application must then perform the
necessary functions to accept or reject the request.
REQUEST_DISCONNECT
A remote application may request to disconnect from the
application. The application must then perform the
necessary functions to accept or reject the request.
RESPONSE_CONNECT
The request for connection to an application has
completed, and the status of rejection or acceptance is
provided.
MTB741-07 MOWSE Design
RESPONSE_DISCONNECT
The request for disconnection from an application has
completed, and the status of rejection or acceptance is
provided.
MOWSE Design MTB741-07
6. MOWSE Commands
6.1. PC Commands
Entering MOWSE:
mowse
Syntax: mowse {/control_args}
Function:
Enters the PC MOWSE terminal environment. This environment
provides a teletype terminal connection to Multics. The user
can now communicate with Multics with the PC acting as a
terminal. To run software on Multics and/or the PC that uses
the WS subroutine library, the user must subsequently invoke
MOWSE on Multics (see the attach_mowse command for Multics).
Any argument values specified on the command line will
override any conflicting specifications included in the file
specified with the /F option. In addition, the first
specification of an argument value overrides any subsequent
specification for the same parameter. In the case of using /L
to load applications, ALL the applications specified are
loaded, whether they are specified on the command line, or in
the file used with /F.
Arguments:
/B BAUD
This is the baud rate for the specific line that you are
using. This may be from 110 bps to 9600 bps. (DEFAULT --
9600).
/C COMMUNICATIONS_PORT_INTERRUPT_NUMBER
The communications port (COM1 and COM2) number provides
the user (applications) with a means of specifying which
communication port is to be used by MOWSE.
1 - COM1 port (default)
2 - COM2 port
/D DATA_BITS
This is a one integer specification of the number of Data
bits in each byte of data coming over the line.
7 - Seven data bits/byte (DEFAULT)
8 - Eight data bits/byte |
/E N |
Specifies that the character represented by the octal |
value N is to be escaped when the PAD transmits it over |
MTB741-07 MOWSE Design
the communications link. |
/F FILE
Specifies the name of a PC file which is to be analyzed by
MOWSE at startup. This file (created by the user)
contains parameter options which would normally be
specified in the MOWSE command line. Any of the options
may be specified, except /F itself. (DEFAULT FILENAME --
MOWSE.INI)
/I USER_INTERRUPT_NUMBER
The User Software Interrupt - 97 to 101 inclusive -
provides the user (application) with a means of setting up
MOWSE with a software interrupt number which, to his
knowledge, is not going to be used by any application
which will be using MOWSE. Only one of these interrupts
is required by MOWSE. (DEFAULT -- 97).
/L CAPABIL
Specifies that CAPABIL is to be loaded as an application
at the time MOWSE is started up. CAPABIL is the name of
the application to be loaded. You may load more than one
application at a time, but the name of each application
must be preceeded by /L. |
/N |
Specifies that the communications link is over a network. |
This causes the end of packet character used in the PAD to |
be a CR. This argument must be used in conjunction with |
the -network argument to the attach_mowse command. |
/P PARITY
This is a one letter indication of Parity.
E - Even (DEFAULT)
O - Odd
M - Mark
S - Space
N - None
/S STOP_BITS
This is a one integer specification of the number of stop
bits in each byte of data coming over the line.
1 - One stop bit/byte (DEFAULT)
2 - Two stop bits/byte
MOWSE Design MTB741-07
Exiting MOWSE:
exitmows
Syntax: exitmows
Function:
Exits the MOWSE terminal environment on the PC and restores
the interrupt vectors to their original value (before MOWSE
was invoked.)
Notes:
Before exiting MOWSE, you must detach MOWSE on Multics (see
the detach_mowse command for Multics).
In addition, a region of the PC memory which MOWSE occupied is
written with NULL bytes. This is to prevent sensitive data
from remaining in the PC's memory when the MOWSE has been
revoked.
MTB741-07 MOWSE Design
6.2. Multics Commands
Entering MOWSE:
attach_mowse, atm
Syntax: attach_mowse {-control_args}
Function:
Enters the MOWSE environment. Sends a message to the PC
requesting that it enter the complete MOWSE environment (i.e.
accept MOWSE messages). On Multics, moves the attachment of
the specified switch to a mowse_i/o switch. Attaches the
first switch via mowse_i/o to the second.
Control arguments:
-debug {path}
Enables packet recording. Writes all incoming and
outgoing packets to the specified file, defaults to
[wd]>debug.mowse_io_
-no_debug
Disables packet recording. (DEFAULT)
-force, -fc
Forces the mowse_i/o attachment irregardless of terminal
type.
-no_force, -nfc
Does not force the mowse_i/o attachment thus requiring the
terminal type setting "MOWSE". (DEFAULT)
-io_switch {switchname}, -iosw {switchname}
Specifies the switch beneath which the mowse_i/o switch
will be attached. (DEFAULT -- user's login_channel)
-start_up {entryname}, -su {entryname}
Specifies which capabilities (if any) are to be loaded at
the initialization of MOWSE on Multics.
-no_start_up, -nsu
Does not allow start_up. (DEFAULT)
-trace {path}
Enables tracing of Multics application messages by writing
them to a Multics segment. (DEFAULT -- trace.mowse_io_)
-no_trace
Disables tracing of Multics application messages.
(DEFAULT) |
-escape N, -esc N |
Specifies that the N character (given as an octal value) |
is to be escaped when transmitted to the PC. |
-network |
Specifies that the connection to Multics from the PC has |
been established over a network. This causes the PAD end |
MOWSE Design MTB741-07
of packet character to be a CR. This must be used in |
conjunction with the /N argument to the PC MOWSE command. |
Notes:
The MOWSE environment provides a special connection between a
Multics process and a Personal Computer. To enter the MOWSE
environment on Multics, the corresponding environment must
have been previously entered on the PC. To establish the
MOWSE environment, the user must:
1. First enter the MOWSE environment on the PC
2. Connect to Multics.
3. Invoke MOWSE on Multics (attach_mowse).
MTB741-07 MOWSE Design
Exiting MOWSE:
detach_mowse, dtm
Syntax: detach_mowse
Function:
Exits the MOWSE environment on Multics and the remote system.
Sends a message to the remote system requesting that it return
to the MOWSE terminal environment. (i.e. do not process any
future MOWSE requests) Removes mowse_i/o from the specified
switch on Multics.
Notes:
To completely exit the MOWSE environment, the user must first
exit the Multics MOWSE environment, and then the PC MOWSE
terminal environment. To exit the MOWSE environment, the
user:
1. Quits MOWSE on Multics (detach_mowse).
2. Quits MOWSE terminal environment on the PC (exitmows).
MOWSE Design MTB741-07
7. Installing MOWSE on the PC
Downloading MOWSE
If you have file transfer facilities:
If you have a PC-Multics file transfer facility capable of
transferring binary files, the process of downloading MOWSE
involves transferring the files MOWSE.COM and BFT.COM from
Multics to the PC. These files are located in the >unb directory
on Multics.
If you do NOT have PC-Multics file transfer facilities:
In this case, it is necessary to type in a Basic program on the
PC in order to download MOWSE. The basic program is
approximately 100 lines long. This will allow you to log on to
Multics from where the transfer will begin. It will transfer the
two binary files named MOWSE.COM and BFT.COM. Note that this
program is NOT a general purpose file transfer facility.
Once the program is entered you use the RUN function key to start
it working or type 'run'. You then have to log on to Multics.
The PC will act as a Multics terminal until you type 'load_mowse
{filename}', where filename is mowse.com or bft.com. This will
place the program into file transfer mode. It will begin
transferring the file named. It does this in the following
manner:
-the basic program starts load_mowse on Multics
-load_mowse reads 8 chars from the binary file MOWSE.COM
-load_mowse converts these to ascii and adds a checksum
-load_mowse sends this packet to the PC basic program
-load_mowse waits for a reply(ACK/NACK) before sending
the next packet or aborting the transfer accordingly
-the PC reads the incoming packet and checks it against
the checksum
-on any error the program is aborted and everything is lost
-if the checksum is all right then the PC decodes the ascii
transmission and saves it in the appropriate file
-the PC then sends a request to load_mowse to send the
next packet
-when both files are transferred you return to Multics
command level
The same process is followed for BFT.COM.
When the transfer finishes you are returned to Multics command
level so that you can logout. To exit the PC program you hit the
ESC key. This returns you to basic on the PC.
MTB741-07 MOWSE Design
Load_mowse on Multics works in the following way:
1) it finds MOWSE.COM (or BFT.COM)
2) it reads a fixed number of characters from the file into bit
strings
01 bit_string_in
02 drop bit(1)
02 top bit(4)
02 bot bit(4)
......
3) it adds 32 (concatenates "0010"b) to top and bot to form
new_top and new_bot which are ascii characters
01 bit_string_out
02 new_top bit(8)
02 new_bot bit(8)
......
4) it creates a check sum from outgoing characters
5) it puts the characters and check sum on the communication line
to the PC
6) it waits for a reply from the PC and then repeats until
MOWSE.COM is finished
7) it then does the same thing for BFT.COM
8) it returns to command level when done
Multics Entry: load_mowse
Function: To transfer MOWSE.COM and BFT.COM to the PC when
called by the file transfer Basic program.
Syntax: load_mowse {filename}
Arguments:
filename is the name of the file to be transferred (mowse.com
or bft.com)
Example:
load_mowse mowse.com
Notes:
Load_mowse can be called by the Basic program from the PC or
from Multics command line. It transfers only 8 characters
from the *.COM file at a time in order not to overflow any
buffers along the communication channel. The checksum is the
sum of all outgoing characters.
MOWSE Design MTB741-07
8. Glossary
AH Register
Register used to store a MOWSE function number so that an
application can access the specific function.
AX Register
Register used by each MOWSE function to store an error code.
Application
A program or group of programs which are required in order
to perform a useful function, such as word processing,
accounting, calculation, games, and education. See also:
Foreground Application, Background Application, and MOWSE
Application
Application Interface
The subroutine library that is used by both foreground and
background applications to commiunicate with MOWSE.
Background Activities
Activities that do not utilize the display or keyboard input
facilities on Multics or on the Personal Computer at any
time except explicitly through MOWSE.
Background Application
An application running in MOWSE which does not use the
keyboard or display screen, and may use the processor only
under strictly defined circumstances. It should be viewed
as a subroutine that is called by MOWSE whenever a message
is received that is to be analyzed by the subroutine. To
distinguish between the usually understood meanings of
"applications" and "subroutines", MOWSE background
applications are referred to as "major capabilities".
Background Channel
The logical channel for communications between applications.
Background Processing
Occurs when a background application is processing a
background message.
BFT
Acronym for Background File Transfer. Provides a facility
for transferring files between two computers by means of
cooperating processes running on each of the computers.
This facility is intended to operate as a background process
on each computer. BFT is a MOWSE application in that it
makes use of MOWSE facilities for user I/O and
communications.
MTB741-07 MOWSE Design
BIOS
Acronym for Basic Input/Output System. A collection of
programs that control the handling of characters between the
Central Processing Unit and other devices of the computer
system (keyboard, monitor, printer, etc.) in the IBM PC.
Capability
Any function that a system is capable of performing.
Multics performs many functions, and therefore could be said
to have many capabilities. These capabilities are known
only to Multics and used solely by Multics. The same
applies to most other systems, including a Personal
Computer.
Capability Driver
The software used to activate a capability.
Capability Loading
The act of making a capability known to MOWSE. This
consists of requesting the command processor to execute the
program that provides the capability and having that program
notify MOWSE of its entry points.
Capability Message
A variable length sequence of characters that contains a
major capability number, a minor capability number, and data
parameters. Multics and the Personal Computer communicate
through capability messages.
CAT
Acronym for Capability Address Table. A table that
maintains information on the availability of capabilities,
the calling of capabilities, and the certain states of
capabilities. It contains the name of each major
capability, and its program address.
DOS
Acronym for Disk Operating System. A program which remains
in the computer's memory, consisting of instructions to
enable the computer to manage the storage and retrieval of
data from disks. It also enables the user to interact with
the computer by entering commands at the console.
External Capability
All capabilities which are not directly required for MOWSE
functioning.
Foreground Activity
Any activity which uses the terminal screen and keyboard.
MOWSE Design MTB741-07
Foreground Application
An application that has control over the use fo a display
screen and terminal keyboard. These applications are
permitted to use the processor by default, except when
required by the operating system.
Foreground Channel
The logical channel transmitting all user I/O.
FNP
Front-end Network Processor
Internal Capability
Functions MOWSE requires in order to operate.
Interrupt Handler
A procedure which serivces an interrupt.
MS-DOS
A single user disk operating system for 8086/8088-based
computers. Through MS-DOS, you communicate with the
computer, disk drives, and printer, managing these resources
to your advantage.
Major Capability
A MOWSE background application, which makes its existence
known to MOWSE and is prepared to accept and process MOWSE
messages.
Major Capability Number
A numerical identifier for a major capability. This number
is used by all programs or other major capabilities as an
address to which they can send messages to the major
capability.
Minor Capability
A specific function to be performed by a major capability.
Each major capability may or may not have a set of minor
capabilities associated with it. For example, the major
capability 'calculate' may have minor functions of 'add',
'subtract', 'multiply', and 'divide'. There are some
functions (such as error handling) that all major
capabilities must be prepared to support, and these are
assigned fixed minor capability numbers.
Minor Capability Number
A numerical identifier for a minor capability.
MTB741-07 MOWSE Design
MOWSE
Acronym for Multics Online Work Station Environment; a
mechanism whereby one system may dynamically determine the
capabilities present on another system and may utilize these
capabilities.
MOWSE Application
A program that uses MOWSE.
PAD
Stands for "Packet Assembly/Disassembly", a routine that,
given a string of data to transmit over a communication
facility, will assemble or disassdmble the packets that are
received or transmitted over the communications facilities
that link the two computer systems.
PC
Acronym for Personal Computer; in the context of this MTB,
an IBM PC or close equivalent running MS-DOS 2.0 or greater.
Scheduler
Examines all messages received from the PAD and takes
appropriate action depending on whether the message is
received over the foreground or the background channel.
MOWSE Design MTB741-07
9. Appendix
9.1. Error Codes
The following is a list of the PC error codes and their meaning.
Multics errors are not given here, as they are presented in
standard Multics system error format.
Error codes between -1000 and -1200 are general
-1201 and -1300 are PC only
-1301 and -1400 are Multics only
Error Codes
WSNOERR 0 No error
WSACTIVE -1000 MOWSE is currently active
WSNOTACT -1001 Mowse not active
WSINVSYS -1002 Invalid system number
WSINVMCB -1003 Invalid MCB pointer
WSINVNUM -1005 Invalid capability number
WSSUSPND -1006 Suspended
WSERROR -1007 Some kind of error
WSINVMIN -1008 Invalid minor capability
WSBUFOVR -1009 Buffer Overflow
WSDISPEN -1010 Disconnect pending
WSCNTCRE -1011 Couldn't create instance
WSINVNAM -1012 Invalid capability name
WSINVTIM -1013 Invalid sleep interval
WSNOSPND -1014 Not suspended
WSSLPING -1015 Already sleeping
WSNOMESS -1201 No background message
WSINVBUF -1202 Invalid buffer size
WSINVCAT -1203 Invalid CAT entry
WSINVENM -1301 Invalid entry name
WSINVCON -1302 Invalid connect status