Hardware manual

The default value of returnOnCheckError is false. If returnOnCheckError is true and an error is
encountered, ActOnDiskPages will not retry a check error and then report an error. Instead, it will return
-(#100+i), where i is the page number of the last page successfully transferred. This feature allows
ActOnDiskPages to be used when the user it not sure whether the disk address he has is correct. It is used
by the disk stream and directory routines which take hints; they try to read from the page addressed by the
hint with returnOnCheckError true, and if they get a normal return they know that the hint was good. On
the other hand, if it was not good, they will get the abnormal return just described, and can proceed to try
again in a more conservative way.
The hintLastPage argument, if supplied, indicates the page number of what the caller believes to be the last
page of the file (presumably obtained from the hint in the leader page). If the hint is correct,
ActOnDiskPages will ensure that the disk controller does not chain past the end of the file and seek to
cylinder zero (as described earlier under "Oversights"). If the hint is incorrect, the operation will still be
performed correctly, but perhaps with a loss in performance. Note that the label is not rewritten by
DCwriteD, so that the number of characters per page will not change. If you need to change the label, you
should use WriteDiskPages unless you know what you are doing.
ActOnDiskPages can be used to both read and write a file as long as the length of the file does not have to
change. If it does, you must use WriteDiskPages.
pageNumber = WriteDiskPages(disk, CAs, DAs, filePtr, firstPage, lastPage, lastAction, lvNumChars,
lastNumChars, fixedCA, nil, lvErrorRoutine, nil, hintLastPage).
Arguments beyond lastPage are optional and may be defaulted by omitting them or making them 0 (but
lastNumChars is not defaulted if it is 0).
This routine writes the specified pages from CAs (or from fixedCA if CAs is 0, as for ActOnDiskPages). It
fills in DAs entries in the same way as ActOnDiskPages, and also allocates enough new pages to complete
the specified write. The numChars field in the label of the last page will be set to lastNumChars (which
defaults to 512 [Trident]: 2048). It is generally necessary that DAs!firstPage contain a disk address. The
only situation in which it is permissible for DAs!firstPage to contain fillInDA is when firstPage is zero and
no pages of the file yet exist on the disk (i.e., when creating page zero of a new file).
In most cases, DAs!(firstPage-1) should have the value which you want written into the backward chain
pointer for firstPage, since this value is needed whenever the label for firstPage needs to be rewritten. The
only case in which it doesn’t need to be rewritten is when the page is already allocated, the next page is not
being allocated, and the numChars field is not changing.
If lastPage already exists:
1) the old value of the numChars field of its label is left in rv lvNumChars.
2) if lastAction is supplied, it is applied to lastPage instead of DCwriteD. It defaults to DCwriteD.
WriteDiskPages handles one special case to help in "renaming" files, i.e. in changing the FP (usually the
serial number) of all the pages of a file. To do this, use ActOnDiskPages to read a number of pages of the
file into memory and to build a DAs array of valid disk addresses. Then a call to WriteDiskPages with
lastAction=-1 will write labels and data for pages firstPage through lastPage (DAs!(firstPage-1) and
DAs!(lastPage+1) are of course used in this writing process). The numChars field of the label on the last
page is set to lastNumChars. To use this facility, the entire DAs array must be valid, i.e. no entries may be
fillInDA.
In addition to these two routines, there are two others which provide more specialized services:
Disks & Bfs August 10, 1980 57
For Xerox Internal Use Only -- December 15, 1980