Direct access file streams are supported by LMFS. They are designed to facilitate reading and writing data from many different points in a file. They are typically used to construct files organized into discrete extents or records, whose positions within a file are known by programs that access them in nonsequential order.
Although this could be done with the :set-pointer message to input file streams, the direct access facility provides the following additional functions:
• Direct access to output files .
• Bidirectional file streams, which allow interspersed reading and writing of data to and from varied locations in a file .
• No use of network connections or file buffers during the time between data reading and the next call to position. In contrast, using the :set-pointer
message with ordinary ("sequential") input file streams incurs a significant network and data transfer overhead if the program repeatedly positions, reads several bytes, and then computes for a time.
2.4.1 Stream Messages
The following messages are relevant to direct access file streams.
:read-bytes n-bytes file-position Message
Sent to a direct access input or bidirectional file stream, this requests the transfer of n-bytes bytes from position file-position of the file. The message itself does not return any data to the caller. It causes the stream to be positioned to that point in the file, and the transfer of n-bytes bytes to begin. An EOF is sent following the requested bytes. The bytes can then be read using :tyi, : string-in, or any of the standard input messages or functions.
The stream enforces the byte limit, and presents an EOF if you attempt to read bytes beyond that limit. You must actually read all the bytes and read past (that is, consume from the stream) the EOF.
I t is also possible, before all the bytes have been read, to perform stream operations other than reading bytes. For example, an application might read several records at a time, to optimize transfer and buffering, and decide, after reading the first record, to position somewhere else. Direct access file streams handle this properly. Nevertheless, network and
buffering resources allocated to the stream (both on the local machine and server machine) are not freed unless all the requested bytes (of the last :read-bytes request) and the EOF following them are read.
If you request more bytes than remain in the file, you receive the remaining bytes followed by EOF.
2.4.2 Direct Access Output File Streams
You create direct access output to output and bidirectional direct access file streams by sending a :set-pointer message to the stream, and beginning to write bytes using standard messages, such as :tyo, : string-out, and so forth. The bytes are written to the file starting at the location requested, at successive file
positions. Although you can extend the file in this manner, you cannot do a :set-pointer to beyond the current end of the file.
Direct access output, therefore, consists of sequences of :set-pointer messages and data output. Data are not guaranteed to actually appear in the file until either the stream is closed or a :finish message is sent to the stream. See the message :finish, page 41.
2.4.3 Direct Access Bidirectional File Streams
Bidirectional direct access file streams combine the features of direct access input and output file streams. Sequences of :read-bytes messages and reading data can be interspersed with sequences of :set-pointer messages and writing data. The stream is effectively switched between "input" and "output" states by the
:read-bytes and :set-pointer messages. You cannot read data with :tyi or similar messages if a :set-pointer message has been sent to the stream since the last :read-bytes message. Similarly, you cannot write data with :tyo or similar
messages unless a :set-pointer message has been sent to the stream since the last :read-bytes or :tyi messages, or similar operation.
When the EOF of a byte sequence requested with a :read-bytes message has been read for a bidirectional stream, the system frees network and buffering resources.
2.4.4 Effect of Character Set Translation on Direct Access File Streams The Symbolics generic file access protocol was designed to provide access to ASCII-based file systems for Symbolics computers. Symbolics machines support 8-bit characters and have 256 characters in their character set. This results in difficulties when communicating with ASCII machines that have 7-bit characters.
The file server, on machines not using the Symbolics character set, is required to perform character translations for any character (not binary) opening. Some Symbolics characters expand to more than one ASCII character. Thus, for
character files, when we speak of a given position in a file or the length of a file, we must specify whether we are speaking in Symbolics units or server units.
This causes major problems in file position reckoning. It is useless for the Symbolics machine (or other user side) to carefully monitor file position, counting characters, during output, when character translation is in effect. This is because the operating system interface for "position to point x in a file", which the server must use, operates in server units, but the Symbolics machine (or other user end) has counted in Symbolics units. The user end cannot try to second-guess the translation-counting process without losing host independence.
Since direct access file streams are designed for organized file position
management, they are particularly susceptible to this problem. As with other file streams, it is only a problem when character files are used.
You can avoid this problem by always using binary files. If you must use character files, consider doing one of the following:
• Know the expansions of the Symbolics machine, that is, characters such as Return that do not expand into single host characters. Note that this sacrifices host independence.
• Do not use these characters. See the section "NFILE Character Set Translation" in Networks. This section explains which characters are expanded on the Symbolics computer.