47.47. $storageUnitRead

$storageUnitRead reads numStorageUnits storage units of data from the data file f to an ADDRESS computed as displace(IF adrBase THEN adrBase EL cva(ptrBase),dspl). An error occurs if both adrBase and ptrBase are Zero. The number of storage units read is returned.

If adrBase is non-Zero, the effect is undefined if displace(adrBase,dspl) does not lie within a region of scratch space obtained with newScratch, $newScratchChars, or newPage or if the region does not contain at least numStorageUnits of space beyond the computed ADDRESS. If adrBase is Zero, the effect is undefined if ptrBase does not point to a valid MAINSAIL dynamic object or if the object is smaller than dspl + numStorageUnits storage units.

For large amounts of data, $storageUnitRead is more efficient than a series of calls to the PROCEDURE read.

Garbage collections may occur during a call to $storageUnitRead or $storageUnitWrite. Therefore, converting an ARRAY to an ADDRESS before reading data into it or writing data from it by means of these PROCEDUREs has undefined effects. The proper way to do a $storageUnitRead of n elements of type t from a file f into an ARRAY ary (starting at the first element) is to convert it to POINTER:

$storageUnitRead(f,n * cvli(size(tCode)),cvp(ary),
    lDisplacement(cva(cvp(ary)),$adrOfFirstElement(ary)))

where tCode is the type code for type t, i.e., one of integerCode, longIntegerCode, bitsCode, etc. (This example assumes that $ioSize(f,tCode) = size(tCode), i.e., that f is a native format file. If this assumption is not satisfied, then $storageUnitRead is probably not suitable for reading data from f.)

$pageRead and $characterRead are other PROCEDUREs used to read large amounts of data from a file with a single PROCEDURE call.

$storageUnitRead does not modify or translate data from files opened for PDF I/O, since it has no way to know the data type(s) of the data read.