Hardware manual

Disk Streams: A Byte-Oriented Disk Input/Output Package
The disk streams package provides facilities for doing efficient sequential input/output to and from Alto
disk files. It also includes operations for doing random positioning with moderate efficiency, and for
performing various housekeeping operations. An introduction to streams can be found in the Alto
Operating System Manual.
As part of these facilities, a "fast stream" capability permits very fast sequential byte access to objects
stored in memory. An extension to the disk streams package permits reading of a disk stream to be
overlapped with computation, thereby enabling the reading of files at full disk speed under favorable
conditions.
The source files for the disk streams package are kept with the Alto Operating System in OS.DM:
Streams.D: public declarations;
DiskStreams.decl: private declarations;
FastStreamsB.bcpl and FastStreamsA.asm: Memory streams;
DiskStreams.bcpl: create/destroy a stream;
DiskStreamsMain.Bcpl: the ’main line’ code;
DiskStreamsAux.bcpl: auxiliary disk stream functions;
DiskStreamsScan.bcpl: fast file scanning;
DiskStreamsOEP.bcpl: overlay entry point declarations.
The DiskStreams code (not the FastStreams code) may be swapped. To this end, the functions are
distributed among three moderate-sized modules and intermodule references are minimized.
Streams use the generic procedures of a "disk object" to do disk transfers. The stream routines default the
choice of disk to "sysDisk," a disk object created by the Alto operating system to provide access to the
standard disk drive. However, you are free to open streams to other disks.
1. Data structures
The file Streams.D contains the public declarations of the disk streams package. Most users will not be
concerned with these structures (except occasionally with their size, so as to be able to allocate the right
amount of space for one of them), because the streams package provides procedures to perform all the
operations which are normally needed.
The ST structure is common to all streams in the Alto operating system. It includes the procedures which
implement the generic stream operations for this particular stream: Closes, Gets, Puts, Resets, Putbacks,
Errors, and Endofs. In addition, there is a type, which for disk streams is always stTypeDisk, and three
parameter words whose interpretation depends on the stream. The parameter words are not used by disk
streams.
Fast streams are a specialization of streams, designed to quickly get or put bytes or words until a count is
exhausted, and then call on a fixup routine which supplies a new count. Usually the count specifies the
number of items remaining in a buffer, and the fixup routine empties or refills the buffer, but no such
assumptions are made by fast streams. This facility is described in a later section; it is used by disk streams,
but is of no concern to a program which simply wants to use disk streams.
A file pointer contains all the information required to access an Alto disk file. Its structure is described in
detail in the Disks documentation. For a normal user of streams, a file pointer is simply a small structure
which must be supplied to the CreateDiskStream routine to specify the file to which the stream should be
attached. File pointers are normally obtained from directories, but a user is free to store them wherever he
wishes.
Disk Streams September 9, 1979 39
For Xerox Internal Use Only -- December 15, 1980