Hardware manual

A file address FA is a pointer to a specific byte in a file. It includes the address of the byte, divided into a
page number (the page size depends on the disk in use; normally pages contain 512 bytes) and a byte
number. It also includes a disk address, which is a hint as to the physical location of the specified page.
Stream routines which use file addresses check the hint; if it turns out to be correct, they proceed, and
otherwise they start at the beginning of the file and search for the desired page.
A complete file address CFA contains both a file pointer and a file address; it is a pointer to a specific byte
anywhere in the file system.
A file position (FPOS) is a double-precision number which addresses a byte in a file. The first word is the
most-significant half.
2. Properties of disk streams
All the stream procedures take as their first parameter a structure called a disk stream. A disk stream
provides access to a file stored on the Alto disk. Each stream is associated with exactly one file, although it
is possible to have several streams in existence at once which are associated with the same file. The file is a
permanent object, which will remain on the disk until explicitly deleted. The stream is an ephemeral
object, which goes away when it is closed, or whenever the Alto’s memory is erased.
A file consists of a leader page, a length L, and a sequence of L bytes of data; each byte contains 8 bits. A
stream is always positioned to some byte of the file, and the normal stream operations proceed sequentially
from the current position to later positions in the file. The first byte is numbered 0. When the stream is
positioned at byte n, this will be the next byte transferred by a Gets or Puts. There are also operations
which reposition the stream. When data is written into the stream, the file is lengthened if necessary to
make room for it. The file is never shortened except by TruncateDiskStream (which may be called by
Closes; see below).
A stream can transact business a word at a time or a byte at a time, depending on how it is created. In the
former case, if the length of the file is odd, the last word delivered will have garbage in its right byte.
You can replace the generic stream procedures if you wish (Gets, Puts, Closes, Resets, Errors, Endofs,
Stateofs). The one you are most likely to want to replace is the error procedure. It is initialized to SysErr.
3. Procedures
This section describes the calling sequences and behavior of all the user-callable procedures in the streams
package. If a parameter is followed by an expression in brackets, this means that the parameter will be
defaulted to that expression if you supply 0. If the last few parameters you are supplying are defaulted,
you can just omit them. Empty brackets mean that the parameter may be omitted. The parameter s stands
for the disk stream the procedure works on.
Warning: Because the stream procedures occasionally use the RetryCall function, a procedure address
cannot be computed, but must be the value of a static (global) or local variable. Thus "a>>proc(stream, b)"
is not permitted, but "let pr=a>>proc; pr(stream, b)" is fine.
3.1. Creating and destroying
CreateDiskStream(filePtr, type [ksTypeReadWrite], itemSize [wordItem], Cleanup [Noop], errRtn
[SysErr], zone [sysZone], nil, disk [sysDisk]) returns diskStream. A new disk stream is created and
returned. It is associated with the file specified by filePtr on the given "disk," and positioned at item 0. Its
type may be one of (see Streams.D for definitions):
Disk Streams September 9, 1979 40
For Xerox Internal Use Only -- December 15, 1980