Multics Technical Bulletin MTB-675
File Transfer
To: Distribution
From: Maureen Mallmes
Date: 16 October 1984
Subject: A File Transfer System for the XMODEM and IBM PC-to-PC
Protocols, Revision 1
1. Abstract
This MTB describes the data transfer protocols, XMODEM and
IBM PC-to-PC, and the file transfer system required as an
interface to these protocols.
This revision contains changes to the user interface for the |
file transfer system, micro_transfer, and corrects naming |
inconsistencies for the I/O modules. Change bars | indicate what |
differs from the original MTB. |
This MTB reflects the final MR11.0 version for the data |
transfer protocols and the file transfer system. |
________________________________________
Multics project internal documentation; not to be reproduced or
distributed outside the Multics project.
MTB-675 Multics Technical Bulletin
File Transfer
Comments on this MTB should be sent to the author -
via Multics mail to:
Mallmes.Multics on System M
via posted mail to:
Maureen Mallmes
Advanced Computing Technology Center
Foothills Professional Building
Room #301, 1620 - 29th Street N.W.
Calgary, Alberta T2N 4L7
CANADA
via telephone to:
(403)-270-5400
(403)-270-5411
via forum on System-M to:
>user_dir_dir>Multics>Mallmes>mtgs>Multics_pc_protocols
(pc_protocols)
Multics Technical Bulletin MTB-675
File Transfer
TABLE OF CONTENTS
Section Page Subject
======= ==== =======
1 i Abstract
2 1 Introduction
3 1 Goals
4 2 The File Transfer System on Multics
5 3 The IBM PC-to-PC Data Transfer Protocol on
Multics
6 4 The XMODEM Data Transfer Protocol on Multics
7 5 Documentation
7.1 5 . . The micro_transfer Command
7.2 9 . . The ibm_pc_io_ I/O Module
7.3 11 . . The xmodem_io_ I/O module
8 13 APPENDIX A. The IBM PC-to-PC Data Transfer
Protocol
8.1 13 . . Definitions
8.2 13 . . Transmission Medium Level Protocol
8.3 13 . . Message Block Level Protocol
8.4 14 . . Sending Program Considerations
8.5 14 . . Receiving Program Considerations
9 16 APPENDIX B. The XMODEM Data Transfer Protocol
9.1 16 . . Definitions
9.2 16 . . Transmission Medium Level Protocol
9.3 16 . . Message Block Level Protocol
9.4 17 . . File Level Protocol
9.4.1 17 . . . . Common to Both Sender and Receiver
9.4.2 17 . . . . Receive Program Considerations
9.4.3 17 . . . . Sending Program Considerations
Multics Technical Bulletin MTB-675
File Transfer
2. Introduction
A number of software communication packages for
microcomputers exist on the market. Each package, although
unique to a particular operating system, is based on some type of
protocol. As a result, any two machines talking to each other
use the same protocol, but may vary in the functions of their
individual packages. It is desirable that Multics enters this
marketplace by providing established data transfer protocols and
a software communication package. This document discusses the
Multics implementation of the XMODEM and IBM PC-to-PC data
transfer protocols, and the communication package required as an
interface to these protocols.
3. Goals
The goals may be defined as follows:
1. Implement the XMODEM data transfer protocol as defined
by Ward Christensen on Multics. It will be a system I/O
module accessible to users wishing to design their own
file transfer systems using the XMODEM protocol.
2. Implement the IBM PC-to-PC data transfer protocol as
defined by IBM in their "Asynchronous Communication
Support" manual. It will be a system I/O module
accessible to users wishing to design their own file
transfer systems using the IBM PC-to-PC protocol.
3. Provide a file transfer system that acts as an interface
between the Multics file system and the aforementioned
protocols.
MTB-675 Multics Technical Bulletin
File Transfer
4. The File Transfer System on Multics
The major purpose of the file transfer system on Multics is to
create the required environment for users wishing to transfer
files using a DATA transfer protocol. Data transfer protocols,
such as XMODEM and the IBM PC-to-PC, have no facilities for
specifying the filename or the type and direction of the
transfer. Such functions, if required, must be done outside of
the protocol by a file transfer system. Thus, the initial file
transfer system on Multics for MR11 is to act as an interface
between the Multics file system and the available data transfer
protocols. It will be invoked via a command line
(micro_transfer) with control arguments for setting up the
environment. Specifically, it will perform the following
operations:
1) Command line processing.
See the micro_transfer command, Section 7.1.
2) Initial file connection.
This includes file attachment, opening, etc.
3) Establishment of the communications environment.
This includes the setting of any modes when using the
default target switch. For example, the xmodem protocol |
requires breakall, rawi, rawo, 8bit and no_outp, while
the ibm-pc-to-pc protocol requires rawi, rawo, ^8bit and |
breakall.
4) File i/o.
This includes transport of the data between the Multics
file system and the applicable data transfer protocol
(I/O module). The transport phase may require certain
conversions for ascii files. For example, changing the
end of line sequence received from the microcomputer to
a LF for Multics.
5) Clean up.
This includes the closing of files and setting of any
modes so that the process appears just as it did before
the micro_transfer command was invoked.
As mentioned, the file transfer system for MR11 will be
specifically designed for the transfer of files between Multics
and the microcomputer. Later versions may include the
specification of switches instead of files, new data transfer
protocols, and/or additional conversion facilities.
Multics Technical Bulletin MTB-675
File Transfer
5. The IBM PC-to-PC Data Transfer Protocol on Multics
The IBM PC-to-PC data transfer protocol, see Appendix A, is
to be implemented on Multics as an I/O module. The I/O module
can be attached for stream_input when receiving data from the
microcomputer, or for stream_output when sending data to the
microcomputer. It will read and write protocol packets from a
target switch specified in the attach description. The
ibm_pc_io_ I/O module will assume that the target switch has been |
appropriately configured by the caller. i.e. open for
stream_input_output with the appropriate modes set.
A read on this I/O module will return the data portion from
one or more protocol packets read by the I/O module. Data read
from the target switch by the I/O module, but not requested by
the caller, will be stored in an internal data buffer and will be
available on any subsequent reads.
A write on this I/O module will transmit the data one line
at a time in variable length packets. Data written to this I/O
module that does not contain any carriage return characters will
be accumulated in an internal data buffer until (1) there are 250
data characters to be written to the target switch, or (2) a
subsequent write operation passes data containing a carriage
return character or (3) the I/O module switch is closed.
MTB-675 Multics Technical Bulletin
File Transfer
6. The XMODEM Data Transfer Protocol on Multics
The xmodem data transfer protocol, see Appendix B, is to be
implemented on Multics as an I/O module. The I/O module can be
attached for stream_input when receiving data from the
microcomputer, or for stream_output when sending data to the
microcomputer. It will read and write XMODEM protocol packets
from a target switch specified in the attach description. The
xmodem_io_ I/O module will assume that the target switch has been |
appropriately configured by the caller. i.e. open for
stream_input_output with the appropriate modes set.
A read on this I/O module will return the data portion
(verbatim) from one or more XMODEM protocol packets read by the
I/O module. Data read from the target switch by the I/O module,
but not requested by the caller, will be stored in an internal
data buffer and will be available on any subsequent reads.
A write on this I/O module will issue zero or more protocol
packets containing that data. For write operations that are not
a multiple of 128 characters, data written to the I/O module will
be accumulated in an internal data buffer until either (1) there
are 128 data characters to be written to the target switch, or
(2) the I/O module switch is closed. For write operations that
are always a multiple of 128 characters, (i.e. the internal
buffer does not contain any data waiting to be written), data
will be transferred directly from the user's buffer to the target
switch.
Multics Technical Bulletin MTB-675
File Transfer
7. Documentation
The following is MPM-style documentation for the command and
I/O modules associated with the Multics file transfer system.
7.1. The micro_transfer Command
-------------- --------------
micro_transfer micro_transfer
-------------- --------------
NAME: micro_transfer, mt
SYNTAX AS A COMMAND
mt path {-control arguments}
FUNCTION
Allows a process to transfer a file between Multics and a |
microcomputer over a tty_ line using a data transfer protocol. |
The microcomputer must support the data transfer protocol |
specified by the user. |
ARGUMENTS
path
If transferring a file from Multics to a microcomputer, path
is the pathname of the source segment on Multics. If
transferring a file from a microcomputer to Multics, path is
the pathname of the target segment on Multics.
CONTROL ARGUMENTS
-attach_description STR, -atd STR |
Use STR as the attach description for the data transfer |
protocol I/O module. STR must be enclosed in quotes if it |
contains spaces or other command language characters. The |
default attach description is "xmodem_io_ user_i/o". See |
Data transfer I/O modules below. |
MTB-675 Multics Technical Bulletin
File Transfer
-eof CHR
Specifies the end-of-file sequence for the microcomputer,
where CHR is the end-of-file character. When transmitting a
file to a microcomputer, end-of-file will be transmitted as
CHR. When receiving a file from a microcomputer, the
occurrence of CHR will indicate end-of-file to Multics. |
-eol STR
Specifies the end-of-line sequence for the microcomputer,
where STR is one or more characters. When transmitting a
file to a microcomputer, each linefeed character will be
translated to STR. When receiving a file from a
microcomputer each occurrence of STR will be translated to a
linefeed character. Default is a carriage return, 015
(octal).
-modes STR |
sets the modes for file transfer according to STR, which is a |
string of mode names separated by commas. Many modes can be |
optionally preceded by "^" to turn the specified mode off. |
Modes not specified in STR are left unchanged. For a list of |
valid mode names, type 'help tty_modes.gi'. Modes are |
restored to their original value after the file transfer is |
complete. The default mode string for file transfer is: |
"no_outp,8bit,breakall,^echoplex,rawi,^crecho,^lfecho, |
^tabecho,rawo" |
-receive
Receive data from the microcomputer.
-send
Send data to the microcomputer.
DATA TRANSFER I/O MODULES |
The micro_transfer command provides an interface between the |
Multics file system and a data transfer protocol, where a |
data transfer protocol is implemented as an I/O module. Such |
I/O modules must support the switch_name argument, and the |
stream_input and stream_output opening modes. The switch |
identified by switch_name must be open for |
stream_input_output. The following I/O modules are currently |
available for use with micro_transfer: |
xmodem_io_ switch_name |
The xmodem data transfer protocol is to be used for the |
file transfer. For more information, type 'help |
xmodem_io_'. |
Multics Technical Bulletin MTB-675
File Transfer
ibm_pc_io_ switch_name |
The ibm pc-to-pc data transfer protocol is to be used for |
the file transfer. Note, this protocol does not support |
either the transfer of binary data or error-detecting |
codes. For more information, type 'help ibm_pc_io_'. |
MTB-675 Multics Technical Bulletin
File Transfer
USAGE
The standard usage of micro_transfer to transfer data is of the
following form:
1. Invoke the control program on the microcomputer. This
program is a terminal emulator and file transfer
program.
2. Connect to Multics.
3. Login to Multics.
4. Issue the micro_transfer command on Multics specifying
the pathname on Multics and the applicable parameters.
5. The user must now escape back to the microcomputer.
This escape sequence is micro-system dependent. Specify
to the microcomputer file transfer program the type and
direction of the file transfer and the microcomputer
file name. The microcomputer file transfer program must
be invoked to correspond to the Multics file transfer
system. i.e. If you issued the -send control argument
to micro_transfer, you must issue the receive command to
the microcomputer.
6. The file transfer begins. A display indicating the
status of the transfer may or may not occur, depending
on the communications package residing on the
microcomputer.
7. At the end of the transfer, you will return to the
communications command level on the microcomputer.
NOTES
Either -send or -receive must be specified.
EXAMPLES
! micro_transfer foobar.foo -send -atd "ibm_pc_io_ user_i/o" |
Multics Technical Bulletin MTB-675
File Transfer
7.2. The ibm_pc_io_ I/O Module |
---------- ----------
ibm_pc_io_ ibm_pc_io_|
---------- ----------
Name: ibm_pc_io_ |
The ibm_pc_io_ I/O module performs 7-bit stream I/O over an |
asynchronous communications channel. It uses the data transfer
protocol for the IBM Personal Computer as defined by IBM in their
"Asynchronous Communication Support" manual.
Entry points in this module are not called directly by users;
rather the module is accessed through the I/O system. See
"Multics Input/Output System" in Section V of the MPM Reference
Guide for a general description of the I/O system.
Attach Description
ibm_pc_io_ switch_name |
where:
switch_name
is the name of the target I/O switch. The switch must be
open for stream_input_output. The I/O module for the target
switch must be supported by the timed_io_ module.
Open Operation
The ibm_pc_io_ I/O module supports the stream_input and |
stream_output opening modes.
Close Operation
When opened for stream_output, the close entry transmits any
remaining data in the internal buffer before closing the
switch. See Buffering below.
Put Chars Operation
The put_chars entry transmits the data one line at a time in
variable length data blocks, where the end-of-line character
is a carriage return. Lines exceeding 250 characters will be
transmitted using multiple blocks. See Notes below.
For further explanation of the put_chars entry, see the
iox_$put_chars entry in MPM subroutines.
Get Chars Operation
The get_chars entry reads protocol blocks and returns the
message text to the caller's buffer.
MTB-675 Multics Technical Bulletin
File Transfer
For further explanation of the get_chars entry, see the
iox_$get_chars entry in MPM subroutines.
Get Line Operation
The get_line entry reads protocol blocks and returns the
message text to the caller's buffer. Characters are returned
until either a carriage return character is placed in the
buffer or the buffer is filled.
For further explanation of the get_line entry, see the
iox_$get_line entry in MPM subroutines.
Control Operation
This operation is not supported.
Modes Operation
This operation is not supported.
Buffering
The ibm-pc protocol uses variable length data packets. Data |
not ending with a carriage return character will be stored in
an internal buffer by the ibm_pc_io_ I/O module.
Notes
A line is a string of characters terminated by a carriage
return character, 015 (octal). Transmitting lines longer
than 250 characters will result in the insertion of one or
more carriage returns before transmission. For example, a
call to ibm_pc_io_ to transmit a 260 character line will
transmit two lines, the first line containing the first 249
characters plus a carriage return, and the second line
containing the last 11 characters.
Multics Technical Bulletin MTB-675
File Transfer
7.3. The xmodem_io_ I/O module
---------- ----------
xmodem_io_ xmodem_io_
---------- ----------
Name: xmodem_io_
The xmodem_io_ I/O module performs 8-bit stream I/O over an
asynchronous communications channel. It uses the xmodem protocol
as defined by Ward Christensen.
Entry points in this module are not called directly by users;
rather the module is accessed through the I/O system. See
"Multics Input/Output System" in Section V of the MPM Reference
Guide for a general description of the I/O system.
Attach Description
xmodem_io_ switch_name
where:
switch_name
is the name of the target I/O switch. The switch must be
open for stream_input_output. The I/O module for the target
switch must be supported by the timed_io_ module.
control_args
-error_detecting_code STR, -edc STR
Specifies the error-detecting code to be used for the file
transfer, where STR may be one of:
check_sum, cs
The checksum error-detecting code is to be used for the
file transfer.
cyclic_redundancy_code, crc
The CRC-CCITT error-detecting code is to be used for the
file transfer. Note, because it is the receiver that
determines the type of error-detecting code, this control
argument is incompatible with the stream_output opening
mode.
Default is check_sum.
Open Operation
The xmodem_io_ I/O module supports the stream_input and
stream_output opening modes.
MTB-675 Multics Technical Bulletin
File Transfer
Close Operation
When opened for stream_output, the close entry transmits any
remaining data in the internal buffer before closing the
switch. If there are less than 128 bytes in the buffer, the
buffer is filled with the NUL ASCII character, 000 (octal),
before transmission. See Buffering below.
Get Chars Operation
The get_chars entry reads and decodes xmodem blocks, removes
the xmodem control characters, and returns the message text
to the caller's buffer. For further explanation of the
get_chars entry, see the iox_$get_chars entry in MPM
subroutines.
Put Chars Operation
The put_chars entry splits the data to be written into
128-character blocks. The appropriate xmodem control
characters are added to the beginning and end of each block.
For further explanation of the put_chars entry, see the
iox_$put_chars entry in MPM subroutines.
Get Line Operation
The get_line entry reads and decodes xmodem blocks, removes
the control characters, and returns the message text to the
caller's buffer. Characters are returned until either a
newline character is placed in the buffer or the buffer is
filled. For further explanation of the get_line entry, see
the iox_$get_line entry in MPM subroutines.
Control Operation
This operation is not supported.
Modes Operation
This operation is not supported.
Buffering
The xmodem protocol uses 128 data characters per packet.
Data that is not a multiple of 128 characters will be stored
in an internal buffer by the xmodem_io_ i/o module. Thus,
those users concerned with efficiency, should provide a
multiple of 128 data characters for the put_chars operation.
Multics Technical Bulletin MTB-675
File Transfer
8. APPENDIX A. The IBM PC-to-PC Data Transfer Protocol
The following describes the IBM PC-to-PC data transfer
protocol as defined by IBM in their "Asynchronous Communication
Support" manual, version 2.0.
8.1. Definitions
CR$ Carriage Return (Hex 0D) (Oct 15)
XON$ XON Character (Hex 11) (Oct 21)
XOFF$ XOFF Character (Hex 13) (Oct 23)
IBG$ Begin Transmission Code (Hex 1C) (Oct 34)
ITM$ Terminate Transmission Code (Hex 17) (Oct 27)
8.2. Transmission Medium Level Protocol
Asynchronous, 7 data bits.
Files must be ASCII text files and have no lines longer than
250 characters.
8.3. Message Block Level Protocol
The standard transmission portion of the block is a variable
length character block, maximum 250 characters, followed by a
carriage return.
MTB-675 Multics Technical Bulletin
File Transfer
8.4. Sending Program Considerations
1. The program loops, reading the communications line and
waiting for reception of a text line ending with the control
characters IBG$ CR$.
2. When such a line is received, the program sends a text line
ending with IBG$ CR$. (This line may contain an informative
message as well, such as Starting file transmission)
3. The program transmits the file. Each line in the file should
be sent as a line ending in a Carriage Return (CR$)
4. While transmission is taking place the program should monitor
the input from the communications line and take the following
actions:
a. If an XOFF$ CR$ is seen, stop transmission of lines.
When an XON$ CR$ is seen, resume transmission.
b. If a line ending in ITM$ CR$ is seen, stop all
transmission. This line will contain as text the reason
the receiving IBM Personal Computer has requested
termination.
c. When all lines in the file have been sent, the program
should send a line ending in ITM$ CR$. (This line can
contain an appropriate message, such as "file
transmission completed".)
8.5. Receiving Program Considerations
1. The program loops, sending out a message ending in IBG$ CR$
every 15 to 20 seconds. This message may also contain text,
such as Ready to receive file)
2. During the loop in Step 1, the communications line is
continually monitored for messages from the IBM Personal
Computer. When a line ending in IBG$ CR$ is received, the
program moves on to step 3.
3. Each line received (after the one ending in IBG$ CR$) is
stored as a file record. As these lines end with Carriage
Returns (CR$), the program might delete the CR$ before
storing a line. Before storing a line, the program checks it
to see if it ends in ITM$ CR$. If it does, the program does
not store that line, but closes the file and stops operation.
Multics Technical Bulletin MTB-675
File Transfer
4. The program can stop transmission by the IBM Personal
Computer by sending a line ending with an ITM$ CR$. This
line may also contain a message giving the reason for the
termination.
5. If the program is receiving lines faster that they can be
stored, it can suspend transmission by sending a line
consisting of an XOFF$ CR$ to the IBM Personal Computer.
When it has caught up with the input, it can start up
transmission by sending a line consisting of an XON$ CR$ to
the IBM Personal Computer.
MTB-675 Multics Technical Bulletin
File Transfer
9. APPENDIX B. The XMODEM Data Transfer Protocol
The following describes the xmodem data transfer protocol
as defined by the originator, Ward Christensen.
9.1. Definitions
<soh> 01(HEX) 01(OCT)
<eot> 04(HEX) 04(OCT)
<ack> 06(HEX) 06(OCT)
<nak> 15(HEX) 25(OCT)
9.2. Transmission Medium Level Protocol
Asynchronous, 8 data bits, no parity, one stop bit.
There are no restrictions on the contents of the data
being transmitted. Any kind of data may be sent: binary,
ASCII, etc. No control characters are looked for in the
128-byte data messages.
9.3. Message Block Level Protocol
The standard transmission portion of the block is a 132
or 133 character block without framing characters. Each
block of the transfer looks like:
<SOH><blk #><255-blk #><..128 data bytes..><edc> where:
<SOH> = 01 (Hex).
<blk #> = binary number, starts at 01 increments by 1
and wraps 0FF (Hex) to 00 (Hex).
<255-blk #> = The one's complement of the block number.
<edc> = A one-character checksum or two-character
CRC-CCITT. The checksum is the sum of the
data bytes only. The CRC-CCITT is a 16-bit
remainder obtained by dividing the data bit
string by the
16 12 5
polynomial X +X +X +1.
Multics Technical Bulletin MTB-675
File Transfer
9.4. File Level Protocol
9.4.1. Common to Both Sender and Receiver
All errors are retried 10 times.
9.4.2. Receive Program Considerations
The receiver has a 10-second timeout. Once transmission
begins, it sends a <nak> every time it times out.
Before transmission begins, the receiver performs a handshake
with the sender to determine the type of error detecting code to
be used during transmission. If in checksum mode, the receiver's
first timeout sends a <nak> to request checksum mode, and signals
the transmitter to start. If in CRC mode, the receiver's first
timeout sends a "C" to request CRC mode. It then waits for up to
10 seconds for an <soh>. This process continues until either (1)
six "C"'s have been sent without receiving an <soh>, or (2) an
<soh> is received within 10 seconds of sending a "C". If an
<soh> is received within 10 seconds of sending a "C", it is
assumed that the "C" was accepted by the sender and that it will
send in CRC mode. If six "C"'s are sent without receiving an
<soh>, the receiver switches to checksum mode and sends out a
<nak>.
Once into receiving a block, the receiver goes into a
one-second timeout for each character and the checksum. If a
valid block is received, the receiver will transmit an <ack>.
For invalid blocks, a <nak> is transmitted.
9.4.3. Sending Program Considerations
The sender has a high-level 110-second timeout. If a
timeout occurs, transmission is aborted.
The sender starts transmission upon receipt of a <nak> or a
"C". An initial <nak> causes the sender to transmit in checksum
mode, while a "C" signals the sender to transmit in CRC mode.
MTB-675 Multics Technical Bulletin
File Transfer
The sender starts transmission. If the block was successfully
received (receiver sends an <ack>), the next block is sent. If
the receiver responds with a <nak>, the sender retransmits the
last block. When the sender has no more data, it sends an <eot>,
and awaits an <ack>, resending the <eot> if it doesn't get one.