MULTICS TECHNICAL BULLETIN MTB-758-03
To: MTB Distribution
From: Gary Dixon
Date: January 31, 1987
Subject: Video Support for DSA
-----------------------------------
This MTB describes the interface between the Multics Video System
and the communications system which is part of the Honeywell
Distributed Systems Architecture (DSA) protocols.
-----------------------------------
Revision 1 corrects typographical and minor calling sequence
errors. Revisions 2 and 3 correct correct terminology used for |
the session identifier, provide a better definition for the |
correspondent parameter of dsa_tty_$connect, and correct the list |
of orders supported by dsa_tty_$order. |
Send comments by Multics mail to:
GDixon.Multics on System M
ACKNOWLEDGMENTS: I thank Ron Barstad for laying much of the
groundwork for the video system to DSA interface. His MTB756
describes the very similar interface between video and MOWSE.
_________________________________________________________________
Multics project internal documentation; not to be reproduced or
distributed outside the Multics project without permission of the
Director of MDC.
MTB-758-03 Video Support for DSA
CONTENTS
Page
1: Purpose of this MTB . . . . . . . . . . . . . . 1
2: Attaching a DSA Channel: Functional Overview . 2
2.1: Attaching via tty_ . . . . . . . . . . . . . 2
2.2: Attaching via tc_io_ . . . . . . . . . . . . 2
2.3: Attaching via
video_utils_$turn_on_login_channel . . . . . . . . 2
3: New dsa_tty_ Subroutines . . . . . . . . . . . 4
dsa_tty_ . . . . . . . . . . . . . . . . . . . . 5
dsa_tty_$abort . . . . . . . . . . . . . . . 5
dsa_tty_$attach . . . . . . . . . . . . . . . 6
dsa_tty_$connect . . . . . . . . . . . . . . 7
dsa_tty_$detach . . . . . . . . . . . . . . . 9
dsa_tty_$event . . . . . . . . . . . . . . . 10
dsa_tty_$index . . . . . . . . . . . . . . . 11
dsa_tty_$order . . . . . . . . . . . . . . . 12
dsa_tty_$read . . . . . . . . . . . . . . . . 15
dsa_tty_$read_echoed . . . . . . . . . . . . 16
dsa_tty_$read_with_mark . . . . . . . . . . . 18
dsa_tty_$write . . . . . . . . . . . . . . . 19
dsa_tty_$write_whole_string . . . . . . . . . 20
Video Support for DSA MTB-758-03
111::: PPPUUURRRPPPOOOSSSEEE OOOFFF TTTHHHIIISSS MMMTTTBBB
This document provides a short functional description of the
Multics modules needed to use the Video system with DSA terminal
channels.
Support for DSA communications protocols was planned for Multics
Release 12.0 as an RPQ requested by Bull. Roger Negaret of Bull
implemented a set of video system changes, based upon the
proposal in this MTB. The MOWSE developers then built on these
changes to add MOWSE support to the video system. The MOWSE
changes are described in MTB741 by Michael Flegel, and MTB756 by
Ron Barstad.
Unfortunately, DSA support has been delayed until MR12.1. For
MR12.0, we need to MCR and install the video system to DSA
interface, so that the already-implemented changes supporting
both MOWSE and DSA channels can be installed. This MTB describes
the video to DSA interface. The remainder of the Multics DSA
support will be described in future MTBs for MR12.1 installation.
MTB-758-03 Video Support for DSA
222::: AAATTTTTTAAACCCHHHIIINNNGGG AAA DDDSSSAAA CCCHHHAAANNNNNNEEELLL::: FFFUUUNNNCCCTTTIIIOOONNNAAALLL OOOVVVEEERRRVVVIIIEEEWWW
This section gives a brief overview of how a DSA terminal becomes
attached to a Multics process, how the video system learns that
the login channel is a DSA terminal, and how it interfaces with a
DSA channel.
222...111::: AAAttttttaaaccchhhiiinnnggg vvviiiaaa ttttttyyy_
A Multics process first attaches a DSA terminal using tty_, just
as for MCS terminals. tty_ will detect connection to a DSA
channel by examining the channel name format (a channel name
beginning with "dsa." is a DSA channel). For DSA connections,
tty_ performs I/O operations via new dsa_tty_$XXX subroutines and
the network type is set to DSA_NETWORK_TYPE. For nonDSA (MCS)
channel names, tty_ performs I/O operations via the existing
hcs_$tty_XXX interface and sets the network type to
MCS_NETWORK_TYPE. These network type constants are already
defined in net_event_message.incl.pl1 (based on an earlier MCR).
222...222::: AAAttttttaaaccchhhiiinnnggg vvviiiaaa tttccc_iiiooo_
Similarly, when the video system (tc_io_$tc_io_attach) is called
to attach a DSA terminal, it will examine the channel name,
detect the "dsa." prefix, set the network type to
DSA_NETWORK_TYPE and perform I/O operations through the new
dsa_tty_$XXX subroutines.
222...333::: AAAttttttaaaccchhhiiinnnggg vvviiiaaa vvviiidddeeeooo_uuutttiiilllsss_$$$tttuuurrrnnn_ooonnn_lllooogggiiinnn_ccchhhaaannnnnneeelll
video_util_$turn_on_login_channel will examine the current
attachment of the login channel to determine if it is an MCS or
DSA channel. It does this by issuing a new iox_$control request,
get_network_type.
When tty_ is attached to an MCS channel, iox_$control operations
are routed (via the iocb.control entry variable) to
tty_io_$control, and its ring 0 helper, hcs_$tty_order. MCS will
not be changed to support the new get_network_type control, and
will therefore return error_table_$undefined_order_request when
asked to perform an unknown control request.
When tty_ is attached to a DSA channel, iox_$control operations
will be routed to dsa_tty_io_$control. This subroutine will
implement the new get_network_type control request, which will
return the network type of the connection, DSA_NETWORK_TYPE.
video_utils_$turn_on_login_channel will make the MCS/DSA
determination as follows. If it receives a zero code from the
Video Support for DSA MTB-758-03
call, it assumes the login channel is connected to a DSA channel.
If it receives a nonzero code from the call, it assumes it is
attached via MCS.
After learning the network type, video_utils_ then preserves
information about the tty_ attachment of the channel (eg, modes,
editing chars, delays, output conversion and special chars
tables, etc), closes/detaches the tty_ connection, and reattaches
the channel via tc_io_, and sets the output conversion and
special chars tables from the preserved information. It uses the
network type to tailor its information preservation operations,
based upon the types of information available for each network.
MTB-758-03 Video Support for DSA
333::: NNNEEEWWW DDDSSSAAA_TTTTTTYYY_ SSSUUUBBBRRROOOUUUTTTIIINNNEEESSS
As mentioned above, tc_io_ will interface with the DSA
communications system in MR12.1 by calling new dsa_tty_
subroutines. However DSA itself and dsa_tty_ will not be
installed for MR12.0. Since tc_io_ will never see a DSA channel,
it will never attempt to call dsa_tty_, so no linkage faults will
occur.
The paragraphs below describe the dsa_tty_ subroutine calls coded
into tc_io_ for MR12.0. These calls are similar in calling
sequence and function to the tty_io_ and hcs_$tty_XXX subroutines
of the MCS communications system. The subroutine calls in tc_io_
are:
dsa_tty_$abort
dsa_tty_$attach
dsa_tty_$connect
dsa_tty_$detach
dsa_tty_$event
dsa_tty_$index
dsa_tty_$order
dsa_tty_$read_echoed
dsa_tty_$read_with_mark
dsa_tty_$write
dsa_tty_$write_whole_string
These subroutine interfaces are briefly described in the
following sections of this MTB. These are the interfaces used in
the DSA modules currently being developed for MR12.1.
________ ________
dsa_tty_ dsa_tty_
________ ________
NNNaaammmeee::: dddsssaaa_ttttttyyy_
This subroutine provides the interface between the video system
and the DSA session control and terminal manager programs.
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$aaabbbooorrrttt
This entry resets the read and/or write buffers for a given
channel.
UUUsssaaagggeee
dcl dsa_tty_$abort entry (fixed bin(35), fixed bin, fixed bin,
fixed bin(35));
call dsa_tty_$abort (tty_dsa_id, reset_switch, state, code); |
AAArrrggguuummmeeennntttsss
tty_dsa_id |
is tty_'s DSA session identifier for the channel, returned by |
dsa_tty_$attach. (Input)
reset_switch
indicates whether read or write are to be reset. (Input)
1 reset read
2 reset write
3 reset both
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$aaattttttaaaccchhh
This entry attaches an existing DSA session to the process, given
| its channel name. It returns tty_'s DSA session identifier
associated with the channel. This session ID is used in future
dsa_tty_ calls to identify the channel.
UUUsssaaagggeee
dcl dsa_tty_$attach entry (char(*), fixed bin(71), fixed bin(35),
fixed bin, fixed bin(35));
| call dsa_tty_$attach (channel_name, event, tty_dsa_id, state,
| code);
AAArrrggguuummmeeennntttsss
channel_name
is the channel name of the DSA channel to be attached.
(Input)
event
is the event channel over which the caller of dsa_tty_ events
are to be reported to the caller. (Input)
| tty_dsa_id
| is tty_'s DSA session identifier which dsa_tty_$attach assigns
| to the channel. (Output)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$cccooonnnnnneeecccttt
This entrypoint creates a new DSA session. It is used by tc_io_
to create an outbound, dial-out connection through DSA.
UUUsssaaagggeee
dcl dsa_tty_$connect entry (char(*), ptr, fixed bin(71),
char(*) var, ptr, char(*), fixed bin(35), ptr,
fixed bin(21), char(*) var, (2) bit(72), fixed bin(35));
call dsa_tty_$connect (correspondent, area_ptr, event_channel,
network_address, user_id_ptr, channel_name, session_handle,
dsa_connection_info_ptr, dsa_connection_info_len,
attach_description, access_class_range, code);
AAArrrggguuummmeeennntttsss
correspondent
is the name of an application which must be defined in a |
correspondent entry in the Network Information Table (NIT). |
This NIT entry describes how to access the application (eg, |
name of the network used to access the application, system on |
which the application exists, name of the endpoint which |
handles requests to use the application, etc). (Input) |
area_ptr
is a pointer to an area in which dsa_connection_info can be
allocated. (Input)
event_channel
is an event channel dsa_tty_ uses to signal events associated
with this channel. If 0, then events are not signalled. |
(Input) |
network_address
is the network address to use when making the dial-out
connection. (Input)
________ ________
dsa_tty_ dsa_tty_
________ ________
user_id_ptr
| is a pointer to a user identification structure. Currently,
| this is used only to dial_out from Multics to an application
| running on the DN8 (eg, edit or debug). Thus, information in
| the structure defines person_id, project_id, billing_id and
| password of a user application on the DN8. The submitter_id
| structure is declared in dsa_scu_sec_info.incl.pl1. For
| caller not connecting to a DN8 application, this can be a null
| pointer. (Input)
channel_name
is the name of the actual DSA channel to be used for the
dial-out connection. (Output)
session_handle
is a handle used for communications between session control
and the Login_Server. (Output)
dsa_connection_info_ptr
is a pointer to information about the DSA connection. This
information is allocated in the area pointed to by area_ptr.
This information currently isn't used. (Output)
dsa_connection_info_len
is the length in words of the DSA connection information.
(Output)
attach_description
is an attach description that can be used to attach the tty_
I/O module to the dial-out channel. (Output)
access_class_range
is the access class of the dial-out channel. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$dddeeetttaaaccchhh
This entry detaches a DSA session from the process. The session
may optionally be disconnected at the same time.
UUUsssaaagggeee
dcl dsa_tty_$detach entry (fixed bin(35), fixed bin, fixed bin,
fixed bin(35));
call dsa_tty_$detach (tty_dsa_id, dflag, state, code); |
AAArrrggguuummmeeennntttsss
tty_dsa_id |
is tty's DSA session identifier for the channel. (Input) |
dflag
is the disconnection flag. (Input)
1 disconnect (destroy) the session.
0 just detach the session from the process.
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$eeevvveeennnttt
This entry sets the event channel associated with the connection.
UUUsssaaagggeee
dcl dsa_tty_$event entry (fixed bin(35), fixed bin(71),
fixed bin, fixed bin(35));
| call dsa_tty_$event (tty_dsa_id, event_channel, state, code);
AAArrrggguuummmeeennntttsss
| tty_dsa_id
| is tty_'s DSA session identifier for the channel. (Input)
event_channel
identifies the event channel to be used. (Input)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$iiinnndddeeexxx
This entry returns tty_'s DSA session identifier for a channel, |
given its channel name.
UUUsssaaagggeee
dcl dsa_tty_$index entry (char(*), fixed bin(35), fixed bin,
fixed bin(35));
call dsa_tty_$index (channel_name, tty_dsa_id, state, code); |
AAArrrggguuummmeeennntttsss
channel_name
is the channel name. (Input) |
tty_dsa_id |
is tty's DSA session identifier for the channel. (Output) |
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$ooorrrdddeeerrr
This entry performs the specified control order on the i/o
switch.
UUUsssaaagggeee
dcl dsa_tty_$order entry (fixed bin(35), char(*), ptr, fixed bin,
fixed bin(35));
| call dsa_tty_$order (tty_dsa_id, order, info_ptr, state, code);
AAArrrggguuummmeeennntttsss
| tty_dsa_id
| is tty's DSA session identifier for the channel. (Input)
order
is the name of the control order. (Input)
info_ptr
is null or points to the data whose form depends on the
control order. (Input)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
NOTES:
The following list of tty_ control requests are also supported by
dsa_tty_. Requests followed by an asterisk (*) are used
explicitly by tc_io_ in managing the screen. Others are
available to the user from command level and from applications.
________ ________
dsa_tty_ dsa_tty_
________ ________
get_echo_break_table quit_enable
get_editing_chars read_status
get_event_channel resetread
get_input_conversion resetwrite
get_input_translation set_echo_break_table *
get_line_status_enabled set_editing_chars
get_meters set_input_conversion
get_output_conversion set_input_translation
get_output_translation set_line_status_enabled
get_special set_output_conversion
hangup set_output_translation
interrupt set_prompt
line_length set_special
line_status set_terminal_data *
modes * start *
printer_off * store_id
printer_on terminal_info *
quit_disable write_status
The following tty_ control requests are supported in dsa_tty_ by
ignoring the request and returning a code of 0. None are used by
the video system.
accept_printer_off reset_more
input_flow_control_chars set_delay
output_flow_control_chars set_framing_chars
refuse_printer_off
The following control requests are implemented especially for DSA
connections. None are used by the video system, therefore they
are not documented in this MTB.
________ ________
dsa_tty_ dsa_tty_
________ ________
| attention1 get_line_indicator
| attention2 get_modes
| attention3 get_network_type
| attention4 get_page_indicator
| attention5 get_switch_logical_device
| attention6 get_tabulation
| attention7 get_terminal_characteristics
| attention8 request_device_status
| attention9 select_output_device
| begin_ack_unit set_attention_fcn
| conceal_input set_delimiter_fcn
| conceal_next_line set_editing_fcn
| demand_turn set_event_info
| disable_input_device set_line_indicator
| enable_input_device set_modes
| end_ack_unit set_page_indicator
| get_attention_fcn set_switch_logical_device
| get_delimiter_fcn set_tabulation
| get_editing_fcn set_terminal_characteristics
| get_event_info
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd
This entry reads unechoed characters from the terminal.
UUUsssaaagggeee
dcl dsa_tty_$read entry (fixed bin(35), ptr, fixed bin(21),
fixed bin(21), fixed bin(21), fixed bin, fixed bin(35));
call dsa_tty_$read (tty_dsa_id, buffer_ptr, offset, |
n_chars_to_read, n_chars_read, state, code); |
AAArrrggguuummmeeennntttsss
tty_dsa_id |
is tty's DSA session identifier for the channel. (Input) |
buffer_ptr
pointer to buffer in which characters read from terminal are
placed. (Input)
offset
is the offset in buffer at which first input character is
placed. (Input)
n_chars_to_read
is the maximum number of characters to return. (Input)
n_chars_read
is the actual number of characters returned. (Output)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd_eeeccchhhoooeeeddd
This entry reads echoed characters from the terminal.
Echo-negotiated input starts when this entrypoint is called and
no unechoed characters exist in the input already read.
Negotiated echoing continues until a break character is reached,
or the remaining space in the current window line is filled with
echoed characters. Type ahead entered before echo negotiation
begins or after it stops is not echoed by the terminal.
UUUsssaaagggeee
dcl dsa_tty_$read_echoed entry (fixed bin(35), ptr,
fixed bin(21), fixed bin(21), fixed bin(21), fixed bin(21),
fixed bin, fixed bin, fixed bin(35));
| call dsa_tty_$read_echoed (tty_dsa_id, buffer_ptr, offset,
| n_chars_to_read, n_chars_read, echoed, screen_left, state,
code);
AAArrrggguuummmeeennntttsss
| tty_dsa_id
| is tty's DSA session identifier for the channel. (Input)
buffer_ptr
pointer to buffer in which characters read from terminal are
placed. (Input)
offset
offset in buffer at which first character is to be placed.
(Input)
n_chars_to_read
is the maximum number of characters to return. (Input)
n_chars_read
is the actual number of characters returned. (Output)
echoed
is the number of characters echoed during echo negotiated
input. (Output)
screen_left
is the space left on current line of current window. (Input)
________ ________
dsa_tty_ dsa_tty_
________ ________
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$rrreeeaaaddd_wwwiiittthhh_mmmaaarrrkkk
This entry is like read, but an additional argument indicates the
number of input characters read prior to the mark set in the
input by dsa_tty_$write_whole_string.
UUUsssaaagggeee
dcl dsa_tty_$read_with_mark entry (fixed bin(35), char(*),
fixed bin(21), fixed bin(21), fixed bin, fixed bin(35));
| call dsa_tty_$read_with_mark (tty_dsa_id, buffer, n_chars_read,
| mark_index, state, code);
AAArrrggguuummmeeennntttsss
| tty_dsa_id
| is tty's DSA session identifier for the channel. (Input)
buffer
buffer in which characters read from terminal are placed.
(Input)
n_chars_read
is the actual number of characters returned. (Output)
mark_index
is the number of input characters read prior to setting of the
mark (by dsa_tty_$write_whole_string) in the input. (Output)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$wwwrrriiittteee
This entry writes text to the terminal screen.
UUUsssaaagggeee
dcl dsa_tty_$write entry (fixed bin(35), ptr, fixed bin(21),
fixed bin(21), fixed bin(21), fixed bin, fixed bin(35));
call dsa_tty_$write (tty_dsa_id, buffer_ptr, offset, |
n_chars_to_write, n_chars_written, state, code); |
AAArrrggguuummmeeennntttsss
tty_dsa_id |
is tty's DSA session identifier for the channel. (Input) |
buffer_ptr
pointer to buffer holding data to be written. (Input)
offset
offset in buffer of first character to be written. (Input)
n_chars_to_write
is the number of characters supplied. (Input)
n_chars_written
is the actual number of characters written. (Output)
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
EEEnnntttrrryyy::: dddsssaaa_ttttttyyy_$$$wwwrrriiittteee_wwwhhhooollleee_ssstttrrriiinnnggg
This entry is the same as $write, except that it guarantees to
send the entire buffer to the terminal as a single unit, rather
than sending a partial buffer. This ensures that terminal escape
sequences get sent to the terminal as a single unit, rather than
possibly being split across several transmissions to the
terminal.
UUUsssaaagggeee
dcl dsa_tty_$write_whole_string entry (fixed bin(35), char(*),
bit(1), fixed bin(21), fixed bin, fixed bin(35));
| call dsa_tty_$write_whole_string (tty_dsa_id, string, mark_flag,
n_chars_written, state, code);
AAArrrggguuummmeeennntttsss
| tty_dsa_id
| is tty's DSA session identifier for the channel. (Input)
string
is the character string to write. The buffer can be at most
512 characters long. This is the size of the video system
output holding buffer. (Input)
mark_flag
indicates whether to set a mark in the input stream to
separate input typed prior to printing string on the terminal
from characters typed after string is printed. This mark
allows type-ahead input to be separated from MORE responses.
(Input)
"0"b do not set mark
"1"b set mark
n_chars_written
is the actual number of characters written. This should equal
the length of string, if writing was successful, or 0 if the
string could not be written as a single unit. It may also be
some intermediate value if an unexpected error occurs.
(Output)
________ ________
dsa_tty_ dsa_tty_
________ ________
state
indicates the tty state. See tty_states.incl.pl1 for a list
of possible values. (Output)
code
is a standard status code. (Output)