Hardware manual

GetCompleteFa(s, completeFileAddress) stores both the file pointer and the current position in the
complete file address (CFA). This is enough information to create a stream (passing the file pointer to
CreateDiskStream) and then to return to the current position (passing the file address to JumpToFa).
KsBufferAddress(s) returns address: returns the address in memory of the buffer for the stream. This is
useful if you want to move the buffer; you can do so, and then reset the address with KsSetBufferAddress.
KsGetDisk(s) returns a pointer to the DSK object that describes the disk on which this stream is open (see
Disks documentation).
KsHintLastPageFa(s) returns a pointer to a hint for the end of the file opened by stream s.
ReadLeaderPage(s, ld) reads the 256 word leader page for the file on which s is open into the vector
pointed to by ld. The stream is left positioned at data byte 0.
3.4. Setting state
TruncateDiskStream(s) truncates the stream at its current position. Afterwards, Endofs(s) will be true.
PositionPage(s, page, doExtend [true]) returns wantedToExtend: positions the stream to byte 0 of the
specified page. If doExtend is true, it will extend the file with zeros if necessary in order to make it long
enough to contain the specified page. If doExtend is false, it will not do this, but will return true if it was
unable to position the stream as requested because the file wasn’t long enough. NOTE: This routine
interprets "page" in the units associated with the disk on which the stream is open. If you wish a device-
independent positioning command, see SetFilePos.
PositionPtr(s, byteNo, doExtend [true]) returns wantedtoExtend: positions the stream to the specified byte
of the current page. DoExtend is interpreted exactly as for PositionPage.
JumpToFa(s, fileAddress) positions the file to the specified address (FA). It tries to use the disk address
hint in the address, but falls back to PositionPage if that fails.
SetFilePos(s, filePos): positions the file to the byte specified by the double-precision number in filePos
(FPOS).
SetFilePos(s, filePosH, filePosL): positions the file to the byte specified by the filePosH*2**16+filePosL.
KsSetBufferAddress(s, address): sets the buffer address to the specified memory address. It is the caller’s
responsibility to be sure that the buffer has the proper contents, and that it was allocated from the proper
zone, so that when it is freed using the zone which was used by CreateDiskStream the right thing will
happen.
ReleaseKs(s) will release all the storage used by the stream s, without referencing the disk at all. This is a
way of aborting a stream, often useful when recovering from an unrecoverable disk error.
WriteLeaderPage(s, ld) writes the 256-word vector pointed to by ld on the leader page of the file on which
s is open. The stream is left postioned at data byte 0.
3.5. File Scanning
The disk stream procedures described above have the property that they perform disk operations
synchronously. When one of these procedures requires a disk transfer to be performed, it initiates the
transfer and waits for it to complete. While certain procedures (e.g., ReadBlock, WriteBlock, SetFilePos,
etc.) are capable of transferring many consecutive pages in a single disk operation, most stream routines are
limited to one page per disk revolution. This performance is an order of magnitude below the raw transfer
rate of the disk.
Disk Streams September 9, 1979 42
For Xerox Internal Use Only -- December 15, 1980