2 Copyright (c) 1999 Massachusetts Institute of Technology
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 3 of the License, or (at
7 your option) any later version.
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17 ------------------------------
20 Description of the CHAOS FILE protocol designed by HIC.
22 The CHAOS FILE protocol is a protocol used to give access to the
23 file systems of remote hosts on the CHAOS net. Provided that the
24 foreign host has a CHAOS FILE server, one can read and write files,
25 delete, rename, etc. The protocol was originally designed to give LISP
26 machines access to the file systems of our PDP/10's, but is general
27 enough to support file transfer between 10's, and other purposes.
29 We will describe the protocol from the point of view of the
30 user, i.e., the implementor of a user program communicating to a foreign
31 server. Hence, terms such as "receive", "send", "input", and "output"
32 are from a user's point of view, unless explicitly indicated. The first
33 step in using the protocol is to open what is called a CONTROL
34 connection to the server on the foreign host. A CONTROL connection is
35 simply a standard CHAOS net connection to the contact name "FILE" on the
36 foreign host. The CONTROL connection is used to send commands, and
37 receive responses and most error message.
39 When reading or writing files, actual data is sent over separate
40 CHAOS net connections called DATA connections. DATA connections are
41 opened in conjunction with the foreign host, using commands on the
42 CONTROL connection. Hence, the CONTROL connection must be opened first.
43 We will present the details below; but here are some preliminary facts
44 about DATA connections. Like CONTROL connections, DATA connections are
45 bidirectional. Each half (send and receive) of a DATA connection is
46 used independently, so two file transfers may be active on a DATA
47 connection at the same time (but they must be in opposite directions).
48 There may be more than one DATA connection per CONTROL connection, but
49 each DATA connection is associated with a particular CONTROL connection.
50 This is because each CONTROL connection deals with a separate
51 incarnation of the server at the foreign host. We also note that DATA
52 connections are re-usable, i.e., can be used for many file transfers.
53 Simple programs might very well get by with a single DATA connection,
54 but it is possible to have several (the actual limit depends on
55 resources of the foreign host, and is 3 for ITS servers, and 8 for
58 The protocol is organized so that commands and responses have a
59 fairly uniform syntax. Further, each command (response) is sent
60 (received) in a single packet. Each command has a field for a unique
61 identifier, called the transaction id, or "tid" for short, which
62 identifies it. This is because the protocol permits asynchronous
63 processing of commands and responses, i.e., you can send a new command
64 without waiting for the response to the previous one. However, it is a
65 good idea to read the responses as they come in, so the server will not
66 block trying to send responses to you. The server is coded so that it
67 will not block if DATA connection packets back up.
69 Let us now discuss the details of command and response packets.
70 We will discuss error processing later. Each command must be sent in a
71 separate packet on the CONTROL connection. The packet must have the
72 packet opcode for ASCII data (%CODAT = 200). When you are done with the
73 CONTROL connection and wish to disconnect from the foreign host, you
74 should send an EOF packet (%COEOF = 014) on the CONTROL connection.
75 This will cause the server to abort any transfers in progress, close all
76 DATA connections pertaining to this CONTROL connection, and close the
79 Responses to commands, successful or not, will come as data
80 packets (i.e., opcode %CODAT) on the CONTROL connection. The only other
81 kind of packet you should see on the CONTROL connection (unless there
82 are network problems) and asynchronous mark packets, which will be
85 The contents of a command or response packet is simply the
86 sequence of ASCII bytes in the data portion of the packet. Fields are
87 generally separated by either spaces (040) or LISP machine newline
88 characters (NL = 215). We remark now that certain parts of the protocol
89 are oriented towards the LISP machine character set, which consists of
90 256 characters. This is in contrast to the 128 character set standard
91 on PDP/10's. The printing characters generally have the same
92 interpretation, though. Later we will explain the character set
93 translation features provided by the protocol in detail.
95 Here is the format of command and response packets:
97 command: tid <sp> [ fh ] <sp> cmd [ args ]
98 response: tid <sp> [ fh ] <sp> cmd [ <sp> results ]
100 <sp> means a space character (040), and brackets surround
101 optional fields. Each field is a sequence of printing characters. Here
102 is the interpretation and format of the common fields:
104 tid: Transaction identifier, used only to help the user program sort
105 out replies. Only the first 5 characters are significant; the
106 rest are discarded, and will not appear in a response. Tid's
107 may vary or be the same, as you wish.
109 fh: File handle, used to identify a DATA connection, and a direction
110 (in/out). That is, each DATA connection has two file handles
111 associated with it, one for indicating input (transfer to you
112 from the foreign host), and one for output (transfer from you to
113 the foreign host). Like tid's, file handles are also unique
114 only in the first 5 characters.
116 cmd: A command name. Only the first 5 characters are actually read
117 at the current time, but this should not be depended upon. The
118 full name of the command always appears in the response.
119 Command names must be presented in upper case.
121 The "args" and "results" fields vary depending on the command,
122 and will be described with each command below. The response to a
123 particular command will have the same tid as the command, and also the
124 same file-handle (if relevant), and the same command name. The only
125 differences are that the tid and file handle in the response will be
126 truncated to 5 characters, and the command name will always appear in
129 Conventions used in the descriptions:
131 Numbers we write (e.g., packet opcodes, ASCII codes, etc.) are
132 in octal, unless followed by a decimal point, in which case they are
133 decimal. Byte sizes are an exception to this rule: they are always in
134 decimal, even if not followed by a decimal point.
135 <none> means an empty field in a packet.
136 <num> means a sequence of ASCII characters that are all digits
137 (codes 060 through 071, i.e., '0' through '9'). Such numbers are always
138 expressed in decimal. These numbers are unsigned, but may have leading
139 zeroes. (The server may possibly send a negative <num> to you, e.g.,
140 the "-1" of the version field of an OPEN response, but you should never
141 send a negative <num> to it.)
142 Some syntax was too long to be presented on a single line here;
143 we note that there is no CRLF or newline in the packet when we continue
144 syntax on a second line. That is, all characters in every command or
145 response are written down explicitly.
146 A reminder: the end of a command or response is not marked by a
147 special character, because the length field of the CHAOS net packet
148 determines where the data ends.
150 ------------------------------------------------------------------------
153 args = <sp> ifh <sp> ofh
156 This is used to open a new DATA connection. The "ifh" and "ofh"
157 fields are the input and output file handles to associate with this data
158 connection. Each should be distinct from all other file handles of
159 other DATA connections pertaining to the same CONTROL. Since this
160 command does not pertain to any existing file handles, the file handle
161 field of the command must be omitted. As would be expected, the input
162 file handle is used to describe the receive half of the DATA connection
163 and the output file handle is use to describe the send half.
165 When the server receives a valid (well-formed, etc.)
166 DATA-CONNECTION packet, it will attempt to open a new CHAOS net
167 connection to your host, using "ofh" (the output file handle you
168 supplied in the command packet) as the contact name. Hence, you should
169 listen for such a connection. The server will respond to the
170 DATA-CONNECTION command immediately, even though the new DATA connection
171 may not yet be open. Of course, you cannot use the connection until it
172 is open, but you will know that, because you had to open it.
174 ------------------------------------------------------------------------
180 This command is used to close a DATA connection when you are
181 finished with it. There is probably little occasion to use this, since
182 any DATA connections will be closed when the CONTROL connection is
183 closed, and a DATA connection can be re-used for multiple file
184 transfers. The DATA connection closed is the one whose input or output
185 file handle appears in the file handle field of the UNDATA-CONNECTION
186 command. UNDATA-CONNECTION implies a CLOSE on each file handle of the
187 DATA connection for which there is a file transfer in progress.
189 ------------------------------------------------------------------------
192 args = [ options ] <NL> filename <NL>
193 options = <sp> option1 <sp> option2 ... <sp> optionN
194 results = <sp> version <sp> date <sp> len <sp> qfasl
197 This command is used to open a file for reading or writing at
198 the foreign host. The "filename" part is the filename to use at the
199 foreign host. It is always expressed in the foreign host's file name
200 syntax. The "options" field will be explained momentarily. If an input
201 file handle is given in the file handle field of the command, then the
202 file is to be opened for reading. If an output file handle is given,
203 then the file is to be opened for writing. In either case the file
204 handle serves to indicate not only the direction of transfer, but also
205 the DATA connection to be used for the transfer. A file handle must be
206 supplied, unless a PROBE is being done. PROBE will be explained below,
207 but breifly, it permits you to find out information about a file (i.e.,
208 the "results" information of an OPEN response) without actually opening
211 The "options" field of the OPEN command consists of a number of
212 options (most of them are simple ASCII strings), always in upper case,
213 each preceded by a space (to separate them from the "OPEN" and from each
214 other). The options permit you to specify whether the transfer is to be
215 BINARY or CHARACTER, and a number of other things. Some options apply
216 only to BINARY transfers, and others (character set translations in
217 particular) only to CHARACTER transfers. Here is a list of the options
220 READ - Indicates that we will be reading a file. This is
221 redundant, and is checked for consistency (i.e., we must have
222 given OPEN an input file handle).
224 WRITE - Analogous to READ.
226 CHARACTER - Specifies that we will be transferring character
227 data as opposed to binary. This affects the mode in which the
228 server will open a file, as well as whether or not character set
229 translations are performed. CHARACTER is the default, so it
230 need never be specified. The check for QFASL files is not
231 performed (see below).
233 BINARY - Specifies that we will be transferring binary data. A
234 check is made for QFASL files when reading (the result of the
235 test is supplied in the response to the OPEN; see below). The
236 default byte size is 16 bits (see the discussion of byte sizes
239 PROBE - This is used to check the existence of a file, and find
240 out information about it if it exists. The file is not actually
241 opened. This option is implied if no file handle is given in
242 the OPEN command. You should not supply a file handle when
243 doing a PROBE. The response packet will contain the same
244 information as a response to OPEN'ing the file for reading.
245 BINARY vs. CHARACTER makes a difference in a probe, as described
246 in the discussion of the response to OPEN.
248 Options pertaining to BINARY transfers only:
250 BYTE-SIZE <sp> <num> - Specifies to use bytes with <num> bits
251 each. The interpretation is explained below.
253 Options pertaining to CHARACTER transfers only:
255 RAW - Suppresses character set translation (see below).
257 SUPER-IMAGE - Suppresses rubout quoting (this pertains to
258 character set translation, see below).
260 Options specific to particular foriegn hosts:
262 At present there are only two kinds of servers: ITS servers
263 (e.g., AI and MC) and TOPS-20 servers (e.g., XX, EE, and SPEECH). There
264 are two options that are specific to TOPS-20 servers (i.e., they do not
265 work for ITS servers, and should not be presented to them):
267 TEMPORARY - TOPS-20 server only: says to use GJ%TMP in the
268 GTJFN. This is useful mainly when writing files, and indicates
269 that the foreign operating system is to treat the file as
270 temporary. See TOPS-20 documentation for more about the
271 implications of this option.
273 DELETED - TOPS-20 server only: says to set GJ%DEL in the GTJFN.
274 This is useful mainly for READ'ing or in PROBE's, and indicates
275 that deleted files should be considered when looking for a file.
276 See TOPS-20 documentation for information about this.
278 Details for ITS servers:
280 A CHARACTER OPEN will be in .UAI (.UAO) mode when reading
281 (writing). Similarly, a BINARY OPEN will be in .UII (.UIO)
282 mode. An OPEN for writing always opens _LSPM_ OUTPUT in the
283 spcified directory, but does a RENMWO just before the CLOSE, to
284 the appropriate file names. The server takes care of the
285 traditional screws associated with the last word of text files,
286 i.e., you don't have to worry about it -- you will never see the
289 Details for TOPS-20 servers:
291 GTJFN's - When OPEN'ing for READ or PROBE, GJ%OLD is always set.
292 When OPEN'ing for WRITE, GJ%FOU and GJ%NEW will be set. These
293 are independent of the setting of GJ%DEL and GJ%TMP (see the
294 TEMPORARY and DELETED options, above).
296 OPENF's - CHARACTER mode does a 7-bit OPENF, normal mode, with
297 line number checking off when reading. BINARY mode does a
298 36-bit DUMP mode OPENF -- the server handles the packing and
299 unpacking of bytes within words.
303 results = <sp> version <sp> date <sp> len <sp> qfasl
306 version = a <num>, expressing the version number of the file.
307 On ITS server, this will be the numeric second name, or the
308 leading numeric characters of the second name. If the name has
309 no numerics, the field will be "-1". On TOPS-20 this will be
310 the generation number of the file.
312 date = The creation date of the file, expressed in the form
313 "mm/dd/yy hh:mm:ss". (That is a real <sp> between the date and
316 len = ASCII digits for the length of the file in the byte size
317 being read. This will always be 0 when writing.
319 qfasl = "T" if we are doing a BINARY READ, and the first word
320 of the file is "QFASL" in sixbit. "NIL" otherwise. This is
321 clearly oriented towards LISP machines!
323 realname = the full name of the file, e.g., what RFNAME (on ITS)
324 or JFNS (on TOPS-20) will tell you, when asking for all the
325 usual fields (device, directory, first name, second name,
328 ------------------------------------------------------------------------
332 results = <sp> version <sp> date <sp> len
335 A file handle must be given, and a transfer must be active on
336 that handle. A synchronous mark will be sent or awaited accordingly,
337 and the file will be closed (but not the DATA connection). See the
338 discussion of data transfer protocol, below, for more details.
340 The results are mostly as for OPEN. However, the "len" field is
341 computed differently. For ASCII input, it will be the number of
342 characters, as returned by FILLEN on ITS. On TOPS-20, it will be the
343 number of bytes in the file, if it was written using 7-bit bytes,
344 otherwise, 5 times the number of words. For binary input, it is the
345 number of words in the file times 2. For ASCII output, "len" is the
346 exact number of characters written, and for binary output, it is the
347 number of words times the number of bytes per word for the current byte
348 size. [This stuff may be buggy anyway.]
350 ------------------------------------------------------------------------
352 FILEPOS, args = <sp> <num>
354 This must have a file handle, and it must be an input file
355 handle. It requests the foreign host to reset its file access pointer
356 to byte <num> of the file currently open, according to the current byte
357 size being used. As explained below, this sends a synchronous mark
358 before starting to send more data. FILEPOS is ILLEGAL for files being
361 ------------------------------------------------------------------------
364 args = <none> or <sp> filename <NL>
367 If a file handle is given the file being read or written on the
368 specified DATA connection will be deleted after we close it (regardless
369 of direction). The file handle must refer to an open DATA connection,
370 and the direction must be correspond to the current transfer. This is
371 called a "delete while open", or DELEWO. In such a case, DELETE should
374 If no file handle is given, then the optional argument must be
375 present, and specifies a file to be deleted immediately.
377 ------------------------------------------------------------------------
380 args = <NL> filename1 [ <NL> filename2 ] <NL>
383 If a file handle is given, only the first filename should be
384 present, and the file will be renamed to filename1 sometime. This is
385 called a "rename while open", or RENMWO. On ITS, a RENMWO call is done
386 immediately. On TOPS-20, a GTJFN is done to filename1, and when we do a
387 CLOSE on the file handle, the CLOSF is done with CO%NRJ set, and then an
388 RNAMF is done to the previously obtained jfn.
390 If no file handle is given, then both filenames must be present,
391 and the effect is to rename filename1 to be filename2. Don't forget
392 that on ITS renaming can only be done within a directory. The server
393 simply ignores the device and directory parts of filename2, so be
394 careful. On TOPS-20, renaming from one pack to another will fail.
396 ------------------------------------------------------------------------
402 This must have a file handle, and the indicated channel must be
403 in the asynchronously marked state. That is, an error of some kind
404 occurred. If the error might be recoverable, then CONTINUE will try to
405 resume from it. If the error is non-recoverable, you will get an error
406 response. See the discussion of marks below.
408 ------------------------------------------------------------------------
411 args = <sp> nbs <sp> [ npos ]
414 This must have a file handle, which must refer to a file open in
415 BINARY mode. Both nbs and npos are <num>'s. "nbs" is the new byte
416 size, and must be in the range 1 to 16. "npos" is the new position in
417 the file IN TERMS OF THE OLD BYTE SIZE. The npos part may be omitted
418 for output files, and is ignored if present (but the second <sp> MUST be
419 there). If npos is omitted for input files, it defaults to 0. This
420 command sends or awaits a synchronous mark.
422 ------------------------------------------------------------------------
425 args = <NL> userid [ <NL> password [ <NL> account ]]
426 results from ITS = <sp> uname <sp> hsname
428 results from TOPS-20 = <none>
430 This command is for logging in at the foreign host. You must
431 log in before any OPEN commands will be accepted. Logging in to ITS is
432 simple: you just give the desired UNAME, which may even legally be
433 blank. On TOPS-20, the userid must correspond to a real directory
434 (RCUSR is used), and the password and account are passed to a LOGIN
435 jsys. For most of our TOPS-20's, userid = ANONYMOUS and password =
436 ANONYMOUS will give you a login of low privilege. If the first character
437 in the password is an asterisk, capabilities will be enabled.
439 ------------------------------------------------------------------------
442 args = options <NL> pathname
443 results = same as for OPEN
445 The only option currently allowed is DELETED, which says to include deleted
446 files (TOPS20) or "*" files (ITS).
448 The DIRECTORY command is like opening an input file. The possible responses
449 are the same as for OPEN, except that the affirmative response says DIRECTORY
452 The input file that you read consists of a series of records; first a
453 header and then the name and properties of each file that matches the
454 pathname, which may contain wildcards in system-dependent fashion. Each
455 record read consists of a pathname, <NL>, a set of properties separated by
456 <NL>, and an extra <NL> to separate it from the next record. Each property
457 consists of the name of the property, optionally followed by a space and
458 the value. (If no value is present, the property is a yes/no property and
459 the value is yes). The header record is in the same format; it has a blank
460 pathname and has the properties for the file system as a whole rather than
461 for a particular file.
463 The properties are not documented here; consult the Lisp machine manual for
464 a list of the most useful ones.
466 ------------------------------------------------------------------------
469 args = options <NL> default-pathname <NL> string
470 results = status <NL> new-string <NL>
472 This does filename completion. String is a filename typed in by the user
473 amd default-pathname is the default name against which it is being typed.
474 The filename is completed according to the files present in the file system
475 and the possibly-expanded string is returned.
477 Allowed options are DELETED, READ, WRITE, OLD, NEW-OK. DELETED means not
478 to ignore deleted files; this applies to Tenex and TOPS-20 only. READ
479 means the file is going to be read (this is the default). WRITE means the
480 file is going to be written, and affects version number defaulting. OLD
481 means an existent file is required (this is the default). NEW-OK means that
482 it is permissible for the string to complete to the name of a file that does
485 The returned status is NIL, OLD, or NEW. NIL means that an error occured,
486 OLD means that the string completed to the name of an existent file, NEW
487 means that the string completed to a legal filename which is not the name
490 ------------------------------------------------------------------------
493 args = filename <NL> property-name <SP> new-value <NL> ...
496 This allows you to change one or more properties of a file. The properties which
497 are legal to change are those in the SETTABLE-PROPERTIES property of the header
498 record returned by the DIRECTORY command. The legal values for yes/no
499 properties are T and NIL.
501 ------------------------------------------------------------------------
503 About character set translations:
505 As mentioned somewhere above, the protocol was originally
506 designed to provide access to PDP/10 file systems for LISP machines.
507 LISP machines support 8-bit characters, and hence have 256 characters in
508 their character set. This results in minor difficulties when conversing
509 with PDP/10's, which prefer 7-bit characters. Translations apply ONLY
510 to CHARACTER transfers, not BINARY transfers. Below is a table showing
511 the "normal" (i.e., default) correspondence between LISP machine and
512 PDP/10 characters. Some LISP machine characters expand to more than one
513 PDP/10 character. The notation "x in <c1, c2>" means "for all
514 character codes x such that c1 <= x <= c2."
516 LISP machine character PDP/10 character(s)
519 x in <010, 012> 177 x
521 x in <014, 015> 177 x
524 x in <200, 207> 177 <x - 200>
525 x in <210, 212> <x - 200>
529 x in <216, 376> 177 <x - 200>
530 377 no corresponding code
532 This table may seem confusing at first, but there ARE some
533 general rules about it that should make it appear more sensible. First,
534 LISP machine characters in the range <000, 177> are generally
535 represented as themselves, and x in <200, 377> is generally represented
536 as 177 followed by <x - 200>. That is, 177 is used to quote LISP
537 machine characters with the high bit on. It was deemed that 177 is more
538 important than 377, so 177 177 means 177, and there is no way to
539 describe 377 with PDP/10 characters. On the LISP machine, the
540 formatting control characters appear shifted up by 200. This explains
541 why the preferred mode of expressing 210 (backspace) is 010, and 010
542 turns into 177 010. The same reasoning applies to 211 (tab), 212
543 (linefeed), 214 (formfeed), and 215 (newline). However, newline has an
544 added twist -- it is supposed to start at the beginning of a new line,
545 so it is deemed equivalent to 015 012 (CRLF) in PDP/10 characters. When
546 converting PDP/10 characters to LISP machine characters, an 015 always
547 turns into a 215; however, if it is followed by an 012, the 012 is
550 The above table applies in the case of NORMAL translation, i.e.
551 the default translation mode. Note that the server ASSUMES the user is
552 a LISP machine, and that all our servers are PDP/10's, so the labellings
553 "LISP machine" and "PDP/10" can be thought of as "user" and "server".
555 The other translation modes available are:
557 RAW - perform no translation (PDP/10 characters simply discard
558 the high order bit of LISP machine characters, and LISP machine
559 characters supplied by a server will always be in the range
562 SUPER-IMAGE - This suppresses the use of rubout for quoting.
563 That is, each entry beginning with a 177 in the PDP/10 column of
564 the translation table presented above, has the 177 removed. The
565 PDP/10 character 015 always maps to the LISP machine character
566 215, as in normal translation. Here is the corrected table:
568 LISP machine character PDP/10 character(s)
571 x in <200, 214> <x - 200>
573 x in <216, 376> <x - 200>
574 377 no corresponding code
576 User programs written for PDP/10's probably do not wish to have
577 any of the above translations performed, since they are using the PDP/10
578 7-bit character set. Hence, RAW is probably what you want. It is also
579 the most efficient method of transferring ASCII data using the protocol.
581 ----------------------------------------------------------------
583 Data transfer and byte packing issues:
585 Once a DATA connection has been established, and an OPEN has
586 succeeded, data transfer proceeds by sending/receiving packets on the
587 appropriate DATA connection. CHARACTER data is always in packets with
588 opcode %CODAT (200), and BINARY data in packets with opcode 300 octal.
589 Consider the data portion of a packet as a sequence of 8-bit bytes, in
590 the fashion usual for the CHAOS net. Then CHARACTER data is always
591 packed one character per packet byte. The organization is such that a
592 standard PDP/10 byte pointer of size 8-bits can be used to load or store
593 characters into a packet sequentially. (As usual, the low 4 bits of
594 each 36-bit word is ignored, and not even transmitted on the CHAOS net.)
595 There are no particular restrictions on the minimum or maximum sizes of
596 data packets, other than hardware or operating system limits. The
597 server will always send the largest packets it can.
599 The situation with BINARY data is slightly more complicated. We
600 must consider the data portion of a packet as a sequence of 16-bit
601 bytes. Each 16-bit byte consists of two 8-bit bytes, with the first of
602 the two 8-bit bytes being the high-order half of the 16-bit byte. (This
603 corresponds to PDP/10 conventions, but is the opposite of PDP/11
604 conventions regarding byte packing.) Each byte of binary data sent is
605 stored in one 16-bit byte in the packet. If the byte size is less than
606 16-bits, then the byte is right-justified within the 16-bits, with the
607 remaining high order bits set to unpredictable values. The organization
608 is such that loading or storing sequential bytes in a packet can be done
609 with a standard PDP/10 byte pointer of byte size 16 bits, and transfer
610 of the bytes so obtained to or from words of files can be done with a
611 byte pointer of the size in use for the transfer.
613 Each packet of BINARY data should contain an integral number of
614 16-bit bytes, i.e., it should have an even nmber of 8-bit bytes. If it
615 does not, the odd byte is discarded. The server always sends binary
616 packets with an even number of 8-bit bytes.
618 For transferring all 36 bits of a PDP/10 word to another 36 bit
619 machine, the byte size must divide 36. The most efficient value is 12,
620 since it is the largest divisor of 36 that is not greater than 16, which
621 is the largest byte size supported by the protocol.
623 ----------------------------------------------------------------
625 Protocol issues in data transfer:
627 In addition to just data packets, some other kinds of
628 informative packets are sent or received on the DATA connection.
630 EOF packets (opcode 014) are used to mark end of file when
631 reading or writing. That is, when you are writing a file and come to
632 the end of what you wish to write, you will send an EOF packet to tell
633 the server it has reached the end. Similarly, you will receive an EOF
634 packet at the end of a file when reading. EOF packets are always empty
635 (i.e., contain no data). There are additional details about closing a
636 file, however; read on.
638 In addition to EOF packets, SYNCHRONOUS MARKS (opcode 201) are
639 used to separate groups of packets in the transfer, mainly for purposes
640 of matching up with FILEPOS and SET-BYTE-SIZE commands. You will
641 receive a synchronous mark on the DATA connection sometime after each
642 successful FILEPOS and SET-BYTE-SIZE command. These marks indicate the
643 place in the data stream where the command actually occurred. They are
644 necessary because the server may be several packets ahead of you in
645 sending data, and without the marks there would be no easy way to tell
646 where the previous information ended and the new information starts. A
647 synchronous mark is also sent in response to a CLOSE command when
648 reading, and expected after an EOF when writing. The mark after a CLOSE
649 when reading allows you to find the end of the data packets for that
650 transfer, if you decide to stop the transfer in the middle. The mark
651 after EOF when writing performs a similar function for the server if you
652 terminate the transfer in the middle.
654 When writing, you should send a synchronous mark on the DATA
655 connection whenever you perform a successful SET-BYTE-SIZE command, and
656 also as part of a CLOSE, as described above. All other synchronous
657 marks are ones that you will receive.
661 1) Reading a file. Assume you have a CONTROL connection and an idle
662 DATA connection. Send an OPEN command, and await the response. Then
663 start reading data packets from the data channel. The transfer will
664 continue unless you stop it. Suppose you have read all the file. Then
665 you will see an EOF packet. Send your CLOSE command, to order the file
666 closed, and await a SYNC mark on the DATA connection, indicating that
667 the close is in fact done, and the DATA connection can be re-used for
668 some other purpose. If you decide to quit in the middle, send a CLOSE
669 command, and get the response, and read packets from the DATA connection
670 until you see a SYNC mark. (This assumes that there would be no other
671 SYNC marks in transit because of, say, a previous FILEPOS command, etc.
672 If there were any of those, you will have to wait through the
673 appropriate number of SYNC marks.)
675 2) Writing a file. Again assume you have established a CONTROL and DATA
676 connection. Send the OPEN command and await the reponse. Then start
677 writing packets on the DATA connection. Assuming there are no problems,
678 send an EOF. WAIT FOR THE EOF TO BE ACKNOWLEDGED BY THE SERVER. (That
679 is, a CHAOS net acknowledgement indicating that the server has actually
680 read the EOF packet.) Now send a SYNC mark on the DATA connection and a
681 CLOSE on the CONTROL connection (in either order). If you do not wait
682 for the EOF to be acknowledged, and you send a CLOSE anyway, the file
683 may be truncated because some data packets may not have been processed
686 ----------------------------------------------------------------
688 Errors and Ansynchronous marks:
690 ASYNCHRONOUS MARK packets (opcode 202) indicate error conditions
691 in the transfer, such as running out of disk space or allocation. Some
692 of these may be recoverable, some not. When reading, an asynchronous
693 mark will come in over the appropriate DATA connection. When writing,
694 it will come in on the CONTROL connection. (The DATA connection is not
695 used in this case because the receive half might be in use for another
696 transfer). Here is the format of an asynchronous mark packet:
698 tid <sp> fh <sp> ERROR <sp> erc <sp> c <sp> message
700 That is, it looks like a regular error response packet, except that it
701 has a different opcode (responses are data packets, opcode 200). The
702 tid should be ignored -- it will be somewhat random (whatever happens to
703 to be lying around). The file handle, fh, is useful when writing, to
704 see which DATA connection the error happened to. The "erc" part is a 3
705 character error code (a table of them is presented below, subject to
706 change without notice). The single character "c" will be either "R"
707 (for recoverable) or "F" (for fatal). A recoverable error can be
708 restarted from by sending an appropriate CONTINUE command. A fatal
709 error cannot be recovered from, and an appropriate CLOSE should be
710 performed. The "message" part is an ASCII error message, possibly
711 obtained from the host operating system.
716 C = command error (comes in data packet with cmd = "ERROR", on
717 the CONTROL connection).
718 F = fatal asynchronous error.
719 R = restartable asynchronous error.
721 Flag Code Message, Causes, Possible Diagnosis
723 C CCC - CHANNEL CANNOT CONTINUE
724 CONTINUE not possible.
725 C CNO - CHANNEL NOT OPEN
726 CLOSE on non-open channel.
727 C CRF - CANNOT RENAME OUTPUT FILE TO REAL NAMES
728 Final RENMWO for CLOSE on ITS failed.
729 F CSP - CANNOT SET POINTER
730 Response to this failure in FILEPOS or SET-BYTE-SIZE.
731 C FNF - message varies, depending on reason (FILE NOT FOUND).
733 C IBS - ILLEGAL BYTE SIZE
734 Response to byte size not in range 1 - 16.
735 F IDO - ILLEGAL DATA OPCODE
736 Bad packet opcode in the range 200 - 377 (you should use
737 200 for CHARACTER data, and 300 for BINARY)
738 C IFH - ILLEGAL FILE HANDLE FOR FILEPOS
739 Only input file handles are legal.
740 R IOC - message varies (INPUT OUTPUT CONDITION).
741 Generic code for possibly recoverable failures. This
742 will be sent in an ASYNC mark packet.
743 F IPO - ILLEGAL PACKET OPCODE
744 Received a packet with an illegal opcode, or a SYNC or
745 ASYNC mark when not expected.
746 C IRF - ILLEGAL REQUEST FORMAT
747 Generic response to ill-formed command.
748 C ISC - ILLEGAL CHANNEL FOR SET-BYTE-SIZE
749 SET-BYTE-SIZE may only be done on BINARY channels.
750 C NCN - NULL COMMAND NAME
751 Particular case of a bad command.
752 C NER - NOT ENOUGH RESOURCES
753 Possible causes are: no more I/O channels/jfns available
754 for new DATA connections, system failure to open a new
755 CHAOSnet channel, and inability to lookup a user's info
757 C NLI - NOT LOGGED IN
758 OPEN cannot be done until you are logged in.
759 C TMI - TOO MUCH INFORMATION
760 This happens if a response or error packet overflows.
761 C UFH - UNKNOWN FILE HANDLE
762 Particular case of an ill-formed command.
763 C UKC - UNKNOWN COMMAND
764 Particular case of an ill-formed command.
765 C UNK - USER NOT KNOWN
766 Bad LOGIN (TOPS-20 only).
767 C UOO - UNKNOWN OPEN OPTION
769 F xxx - ??? When a file system or other operating system call
770 fails, which is not covered in the above, then another code is
771 used. These are taken from a table for ITS, with the message
772 read from the ERR: device, and on TOPS-20, the letters are the
773 first letters of the first three words of the error message
774 returned by an ERSTR call. The only exception is code FNF,
775 special cased if the error is GJFX24 ("file not found") or OPNX2
776 ("file does not exist") on TOPS-20. No other FNF's will come
777 from TOPS-20, even by "accidient" -- a special check is made.
projects / its.git / blob