Object Rexx supports a stream I/O model. In the stream model, your program reads data from various devices (such as hard disks, CD-ROMs, and keyboards) as a continuous stream of characters. Your program also writes data as a continuous stream of characters.
In the stream model, a text file is represented as a stream of characters with special new-line characters marking the end of each line of text in the stream. A binary file is a stream of characters without an inherent line structure. Rexx lets you read streams as lines or as characters.
To support the stream model, Object Rexx includes a Stream class and many methods to use on stream objects. To input or output data, you first create an instance of the Stream class that represents the device or file you want to use. For example, the following clause creates a stream object for the file C:\CONFIG.SYS:
/* Create a stream object for CONFIG.SYS */
file=.stream~new("c:\config.sys")Then you send the stream object messages that are appropriate for the device or data. CONFIG.SYS is a text file, so you would normally use methods that read or write data as lines. Some of these methods are LINES, LINEIN, and LINEOUT.
If the stream represents a binary file (such as a WAV, GIF, TIF, AVI, or EXE file), you can use methods that read and write data as characters. Some of these methods are CHARS, CHARIN, and CHAROUT.
The Stream class includes other methods for opening and closing streams, flushing buffers, seeking, retrieving stream status, and other input/output operations.
Many of the methods of the Stream class are also available as Rexx built-in functions. Although you can use the functions, it is preferable to use the Stream class.
Note: In any case, do not mix functions and methods on the same stream to avoid unpredictable results.
To use streams in Object Rexx, you create new instances of the Stream class. These stream objects represent the various data sources and destinations available to your program, such as hard disks, CD-ROMs, keyboards, displays, printers, serial interfaces, network. Because these sources are represented as objects, you can work with them in similar (but not identical) ways.
Stream objects can be transient or persistent. An example of a transient (or dynamic) stream object is a serial interface. Data can be sent or received from serial interfaces, but the data is not stored permanently by the serial interface itself. Consequently, you cannot, for example, search a position in the data stream. Once you read or write it, the data cannot be read again.
A disk file is an example of a persistent stream object. Because the data is stored on disk, you can search forward and backward in the stream and read data that you have previously read. Rexx maintains separate read and write pointers to a stream. You can move the pointers independently using arguments on methods such as LINEIN, LINEOUT, CHARIN, and CHAROUT. Rexx also provides SEEK and POSITION methods for setting the read and write positions.