10.0;siotf (sio_transmit_file), revision 1.0, 88/01/21
siotf (sio_transmit_file) -- Transmit a file to a remote host.
usage: siotf [[-l {1|2|3}] [-n] [-f] [-ae] [-x host_name] [file|*]]...
DESCRIPTION
siotf sends the Domain file(s) you specify to a remote computer ("host")
using the appropriate serial input/output (SIO) line and protocol.
Arguments and options may appear in any order and are processed and take
effect as encountered. This means options must be specified before the
file(s) for which they are intended.
You do not need to use the tctl command to set the sync and insync
parameters of the SIO line when receiving a non-ASCII file. siotf and
siorf recognize the types of the files being transferred and set these
parameters correctly.
The transmission protocols used by siotf are described in the section on
protocols, below.
ARGUMENTS
pathname (optional)
Specify the name of the file to be transmitted. If you wish to
transmit data from standard input, use the * option.
Default if omitted: must use *
OPTIONS
-l n Specify the SIO line to be used for transmission. The default
SIO line is 1.
-n Select the Nibble protocol. (See the "Protocols" section,
below.)
-f Cause siotf to continue monitoring the SIO line for
transmission requests from the remote host rather than
terminating when transmission is complete.
-obj Obsolete option. At SR9.5, siotf automatically detects binary
objects and transmits them properly. Prior configuration of the
SIO line (via the tctl command) is no longer necessary.
-ae Abort on error rather than attempting to continue.
-x host_file
Pass a filename to the remote host. The host can use this name
for the next file it receives from the node. This presumes a
host counterpart to siorf sio_receive_file is active.
* Read from standard input and send standard input to the remote
host. Signal end of data with an end of file (CTRL/Z).
EXAMPLES
Wait for file requests over SIO line 1 and transmit them.
$ siotf -f
Transmit file prog1.bin, then transmit file prog2.bin over SIO line 2.
$ siotf -l 2 prog1.bin prog2.bin
Send the name tell_file, then transmit the file /eng/notes. Presumably
the receiving side is in "forever" mode (-f) and
$ siotf -x tell_file /eng/notes
is thus waiting for instructions.
PROTOCOLS
To permit binary and ASCII file transmissions, we have implemented two
protocols: Plain and Nibbled.
Plain
Plain protocol is the default. It assumes that the host operating system
can transmit and receive all 256 bit patterns, so there is no need to use
escapes or to nibble at the ASCII or binary files. Even if the host can
handle only the ASCII character set, you should use the Plain protocol
for transmitting ASCII files.
The format of this protocol is as follows:
STX type COUNT...data...CHECKSUM CR
where:
STX is the standard ASCII STX (02).
type Is a small ASCII letter that identifies the record type as
follows:
a ACK
d DATA
e EOF
h HELLO
g ANSWER_HELLO
n NAK
p PARTIAL
t TYPE
x NAME
z EOT
? ERROR MESSAGE
COUNT is the number of data bytes in the record (not to exceed 255),
nibbled and transmitted as two ASCII bytes (@ and the capital
letters A through O).
CHECKSUM Is a 1-byte calculated checksum, nibbled and transmitted as two
ASCII bytes.
CR Is a standard ASCII carriage return.
The "t" and "p" types are provided primarily for file transfers occuring
between Domain nodes. "t" informs siorf of the type of file being
transmitted. In this case, the data field consists of a single character
that identifies the type of file as follows:
u uasc file (normal ASCII text file)
o Domain object file
m Non-streams file, accessed though the mapping primitives
r Streams record file
If you are transmitting a streams record file (type "r" above), the
protocol now offers the "p" message type, which siotf uses to transmit
partial records to siorf. siotf can transmit at most 255 bytes at a
time. If a record is larger than 255 bytes, transmission occurs in 255-
byte pieces; all but the last piece has the "p" type message. siotf
transmits the last piece using the normal "d" type message so that siorf
recognizes it as the end of the record.
Nibbled
If the host cannot send or receive anything but ASCII characters, use
Nibbled protocol to transmit non-ASCII data. Transmitted records use a
record format identical to that of Plain protocol, except that ~S
replaces the STX byte. For siotf, each byte from the file is nibbled
into two ASCII characters (@ or A through O). For siorf, the low four
bits of each two bytes received are concatenated; this protocol checks
the ASCII range of the received bytes. A byte out of range causes siorf
to send the host an NAK signal. A byte out of range in five consecutive
records causes siorf to issue an error message, and terminate. The count
field of nibbled records contains the original count (that is, the number
data bytes before nibbling). To select the Nibbled protocol, use the -n
option with siorf or siotf.
When you execute siorf, it issues the hello record to signal that it is
there, and to clear any transmission that may have preceded your command.
It expects to receive the answer_hello response. siotf also does this
before it begins transmitting records.
siorf acknowledges each remote host transmission. siotf waits for the
host to acknowledge each transmission. These acknowledgements have the
format:
STX a CR (or) STX n CR
STX is either STX or ~S, and a and n are the small letters a (ACK) and n
(NAK). The programs recover from a NAK by retransmitting the record in
question. After ten consecutive unsuccessful retries, the programs issue
an error message and abort. All messages must be acknowledged, including
error messages.
The end of file signal is a record with the following format:
STX e CR
where e must be the small letter e. Host programs should acknowledge the
EOF signal.
The end-of-transmission signal is a record with the following format:
STX z CR
where z must be the small letter z. Host programs should ACK the EOT
signal. If the programs do not receive transmissions or ACKs for 60
seconds, they issue time-out error messages and terminate.
NOTES
siotf opens a stream to its SIO line in "cooked" mode, siorf opens the
stream in "raw" mode. Both programs synchronize with host XON/XOFF
(CTRL/Q, CTRL/S) signals.
If you specify a Domain file that cannot be opened, the programs issue an
error message. If a file specified by a record received from the host
cannot be opened (or created), the programs issue an error message, and
transmit an error message to the host. However, they continue processing
their parameters or (if you specified -f) waiting for host requests.
siotf does not transmit EOT if you specify -f. siorf does not terminate
at EOT if you specify -f. If you omit -f, siorf waits until it receives
an EOT signal from the host, or times out.
The programs accept type "?" error messages instead of ACK or NAK
signals. The programs display the error messages, and terminate (even if
you specified -f). If siorf gets an error message while receiving a
file, it aborts. If you included -f, the programs try to remain active
as long as possible.
Model programs to serve as the host-side counterparts to siorf and siotf
have been supplied in /sys/source/emt. These are models in FORTRAN and in
Pascal. The FORTRAN subroutines that need to be modified for host-
specific use are in /fBhost_model_subs1.fin. The Pascal procedures to be
modified are clearly marked in the Pascal model programs. For a
particular host environment. You may also need to modify other areas of
these models.
SEE ALSO
More information is available. Type
help siorf For details about receiving a file from a remote host