1 02/26/85 xmodem_io_
2
3
4 The xmodem_io_ I/O module is used to transfer files between a Multics
5 process and a microcomputer that runs the XMODEM data transfer
6 protocol. It performs 8-bit stream I/O over an asynchronous
7 communications channel using the xmodem protocol.
8
9
10 Entry points in this module are not called directly by users; rather
11 the module is accessed through the I/O system.
12
13
14 Attach Description:
15 xmodem_io_ switch -control_args
16
17
18 Arguments:
19 switch
20 is the name of the target I/O switch. The switch must be open for
21 stream_input_output. The I/O module for the target switch must be
22 supported by the timed_io_ module. The user is responsible for
23 setting any modes required by the xmodem protocol. For example,
24 modes for the user_i/o switch would be:
25 "no_outp,8bit,breakall,^echoplex,rawi,^crecho,lfecho,^tabecho,rawo"
26
27
28 Control arguments:
29 -error_detecting_code STR, -edc STR
30 specifies the error-detecting code to be used for the file transfer,
31 where STR may be one of the following:
32 check_sum, cs
33 specifies that the checksum error-detecting code is to be used
34 for the file transfer.
35 cyclic_redundancy_code, crc
36 specifies that the CRC-CCITT error-detecting code is to be used
37 for the file transfer. Note, because it is the receiver that
38 determines the type of error-detecting code, this control
39 argument is incompatible with the stream_output opening mode.
40
41 Default is check_sum.
42
43
44 Open Operation:
45 The xmodem_ I/O module supports the stream_input and stream_output
46 opening modes.
47
48
49 Close Operation:
50 When opened for stream_output, the close entry transmits any remaining
51 data in the internal buffer before closing the switch. If there are
52 less than 128 bytes in the buffer, the buffer is filled with the NUL
53 ASCII character, 000 octal, before transmission. See Buffering
54 below.
55
56
57 Put Chars Operation:
58 The put_chars entry splits the data to be written into 128-character
59 blocks. The appropriate xmodem control characters are added to the
60 beginning and end of each block. For further explanation of the
61 put_chars entry, see the iox_$put_chars entry.
62
63
64 Get Chars Operation:
65 The get_chars entry reads and decodes xmodem blocks, removes the xmodem
66 control characters, and returns the message text to the caller's
67 buffer. For further explanation of the get_chars entry, see the
68 iox_$get_chars entry.
69
70
71 Get Line Operation:
72 The get_line entry reads and decodes xmodem blocks, removes the control
73 characters, and returns the message text to the caller's buffer.
74 Characters are returned until either a newline character is placed in
75 the buffer or the buffer is filled. For further explanation of the
76 get_line entry, see the iox_$get_line entry.
77
78
79 Control Operation:
80 This operation is not supported.
81
82
83 Modes Operation:
84 This operation is not supported.
85
86
87 Buffering:
88 The xmodem protocol uses 128 data characters per packet. Data that is
89 not a multiple of 128 characters is stored in an internal buffer by the
90 xmodem_io_ I/O module. Thus, those users concerned with efficiency
91 should provide a multiple of 128 data characters for I/O operations.
92
93
94 Notes:
95 No particular line speed is guaranteed when transferring data between
96 Multics and a microcomputer. Line speed is dependent on the
97 microcomputer and the load of the FNP and communication system for
98 Multics. Due to the nature of the XMODEM protocol, files may not be
99 successfully transferred to Multics over high-speed lines. The actual
100 limit depends on the site configuration and current load.
101
102
103 Definitions:
104
105 <soh> 01HEX 01OCT
106 <eot> 04HEX 04OCT
107 <ack> 06HEX 06OCT
108 <nak> 15HEX 25OCT
109
110
111
112 Transmission Medium Level Protocol:
113 Asynchronous, 8 data bits, no parity, one stop bit.
114
115 There are no restrictions on the contents of the data being
116 transmitted. Any kind of data may be sent: binary, ASCII, etc. No
117 control characters are looked for in the 128-byte data messages.
118
119
120 Message Block Level Protocol:
121 The standard transmission portion of a message block is a 132 character
122 block without framing characters. Each block of the transfer looks
123 like:
124 <SOH><blk #><255-blk #><..128 data bytes..><edc> where:
125
126 <SOH> = 01 Hex.
127 <blk #> = binary number, starts at 01 increments by 1
128 and wraps 0FF Hex to 00 Hex.
129 <255-blk #> = The one's complement of the block number.
130 <edc> = A one-character checksum or two-character CRC-CCITT.
131 The checksum is the sum of the data bytes only. The
132 CRC-CCITT is a 16-bit remainder obtained by dividing
133 16 12 5
134 the data bit string by the polynomial X +X +X +1.
135
136
137
138 File Level Protocol:
139 When writing programs that implement the XMODEM protocol, users should
140 follow the procedures listed below:
141
142 In both sending and receiving programs, all errors should be retried
143 ten times.
144
145
146 The Receiving Program:
147 The receiver should have a 10-second timeout and send a <nak> every
148 time it times out. The first timeout that sends a <nak> signals the
149 transmitter to start.
150
151 Once into receiving a block, the receiver must go into a one-second
152 timeout for each character and the checksum. If a valid block is
153 received, the receiver must transmit an <ack>. For invalid blocks, a
154 <nak> must be transmitted.
155
156
157 The Sending Program
158
159 The sender should start transmission upon receipt of a <nak> from the
160 receiver. If the block is received successfully i.e. the receiver
161 sends an <ack>, the next block should be sent. If the receiver
162 responds with a <nak>, the transmission has failed, and the sender
163 should retransmit the last block. When the sender has no more data, he
164 should send an <eot> and await an <ack>. If it does not get one, the
165 sending program should repeat the <eot>.