Open Object Rexx™: Reference
Prev	Chapter 5. The Builtin Classes	Next

The Stream Classes

This section describes the Rexx classes which implement Rexx data streams.

The InputStream Class

This class is defined as an abstract mixin class. It must be implemented by subclassing it or inheriting from it as a mixin. Many of the methods in this class are abstract and must be overridden or they will throw a syntax error when invoked.

Figure 5-8. The InputStream class and methods

Note: The InputStream class also has available class methods that its metaclass, the Class class, defines.

arrayIn

This is a default implementation of the arrayIn method using linein() method calls to fill the array.

charIn

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

charOut

This is an unsupported operation for InputSteams. Invoking it will cause syntax error 93.963 to be raised.

chars

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

close

This method is a NOP by default.

lineIn

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

lineOut

This is an unsupported operation for InputSteams. Invoking it will cause syntax error 93.963 to be raised.

lines

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

open

This method is a NOP method.

position

This method is an optionally supported operation. By default, it will cause syntax error 93.963 to be raised.

The OutputStream Class

Figure 5-9. The OutputStream class and methods

Note: The OutputStream class also has available class methods that its metaclass, the Class class, defines.

arrayOut

This method is a default arrayOut implementation that writes all lines to the stream using lineout.

charIn

This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be raised.

charOut

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

chars

This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be raised.

close

This method is a NOP by default.

lineIn

This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be raised.

lineOut

This method is defined as an abstract method. Invoking it will cause syntax error 93.965 to be raised.

lines

This is an unsupported operation for OutputSteams. Invoking it will cause syntax error 93.963 to be raised.

open

This method is a NOP by default.

position

This method is an optionally supported operation. By default, it will cause syntax error 93.963 to be raised.

The InputOutputStream Class

Figure 5-10. The InputOutputStream class

Note: The InputOutputStream class also has available class methods that its metaclass, the Class class, defines.

Inherited Methods

Methods inherited from the Object class.

new (class method)	instanceMethod	send
= \= == \== <> ><	instanceMethods	sendWith
class	isA	setMethod
copy	isInstanceOf	start
defaultName	objectName	startWith
hasMethod	objectName=	string
identityHash	Request	unsetMethod
init	Run

Methods inherited from the InputStream class.

Note: This class is searched second for inherited methods.

arrayIn	close	open
charIn	lineIn	position
charOut	lineOut
chars	lines

Methods inherited from the OutputStream class.

Note: This class is searched first for inherited methods.

arrayOut	close	open
charIn	lineIn	position
charOut	lineOut
chars	lines

The Stream Class

A stream object allows external communication from Rexx. (See Input and Output Streams for a discussion of Rexx input and output.)

The Stream class is a subclass of the InputOutputStream class.

Figure 5-11. The Stream class and methods

Note: The Stream class also has available class methods that its metaclass, the Class class, defines. It also inherits methods from the InputOutputStream class.

Inherited Methods

Methods inherited from the Object class.

new (class method)	instanceMethod	send
= \= == \== <> ><	instanceMethods	sendWith
class	isA	setMethod
copy	isInstanceOf	start
defaultName	objectName	startWith
hasMethod	objectName=	string
identityHash	Request	unsetMethod
init	Run

Methods inherited from the InputStream class.

Note: This class is searched second for inherited methods.

arrayIn	close	open
charIn	lineIn	position
charOut	lineOut
chars	lines

Methods inherited from the OutputStream class.

Note: This class is searched first for inherited methods.

arrayOut	close	open
charIn	lineIn	position
charOut	lineOut
chars	lines

new (Inherited Class Method)

>>-new(name)---------------------------------------------------><

Initializes a stream object for stream name, but does not open the stream. Returns the new stream object

arrayIn

            +-(LINES)-+
>>-arrayIn--+---------+----------------------------------------><
            +-(CHARS)-+

Returns a fixed array that contains the data of the stream in line or character format, starting from the current read position. The line format is the default.

If you have used the charIn method, the first line can be a partial line.

arrayOut

                  +-,--LINES-+
>>-arrayOut(array-+----------+-)-------------------------------><
                  +-,--CHARS-+

Writes the data in array array to the stream. If LINES is specified, each element of the array is written using lineout(). If CHARS is specified, each element is written using charout(). The default method is LINES.

charIn

>>-charIn-+----------------------------+-----------------------><
          +-(-+-------+--+---------+-)-+
              +-start-+  +-,length-+

Returns a string of up to length characters from the input stream. The stream advances advances the read pointer by the number of characters read. If you omit length, it defaults to 1. If you specify start, this positions the read pointer before reading. The start value must be a positve whole number within the bounds of the stream. If the value is not a positive whole number, a syntax condition is raised. When the value is past the end of the stream, the empty string is returned and the NOTREADY condition is raised. If the stream is not already open, the stream attempts to open for reading and writing. If that fails, the stream opens for input only.

charOut

>>-charOut-+----------------------------+----------------------><
           +-(-+--------+--+--------+-)-+
               +-string-+  +-,start-+

Returns the count of characters remaining after trying to write string to the output stream. The stream also advances the write pointer.

The string can be the null string. In this case, charOut writes no characters to the stream and returns 0. If you omit string, charOut writes no characters to the stream and returns 0. The stream is also closed.

If you specify start, this positions the write pointer before writing. If the stream is not already open, the stream attempts to open for reading and writing. If that fails, the stream opens for for output only.

chars

>>-chars-------------------------------------------------------><

Returns the total number of characters remaining in the input stream. The count includes any line separator characters, if these are defined for the stream. For persistent the count is the count of characters from the current read position. (See Input and Output Streams for a discussion of Rexx input and output.) The total number of characters remaining cannot be determined for some streams (for example, STDIN). For these streams. the CHARS method returns 1 to indicate that data is present, or 0 if no data is present. For Windows devices, CHARS always returns 1.

close

>>-close-------------------------------------------------------><

Closes the stream. close returns READY: if closing the stream is successful, or an appropriate error message. If you have tried to close an unopened file, then the close method returns a null string ("").

command

>>-command(stream_command)-------------------------------------><

Returns a string after performing the specified stream_command. The returned string depends on the stream_command performed and can be the null string. The following stream_commands:

Open a stream for reading, writing, or both
Close a stream at the end of an operation
Move the line read or write position within a persistent stream (for example, a file)
Get information about a stream

If the method is unsuccessful, it returns an error message string in the same form that the description method uses.

For most error conditions, the additional information is in the form of a numeric return code. This return code is the value of ERRNO that is set whenever one of the file system primitives returns with a -1.

Command Strings

The argument stream_command can be any expression that to one of the following command strings:

           +-BOTH--| Write Options |-+
>>-+-OPEN--+-------------------------+--+-------------+-+------><
   |       +-READ--------------------+  +-| Options |-+ |
   |       +-WRITE--+---------+------+                  |
   |                +-APPEND--+                         |
   |                +-REPLACE-+                         |
   +-CLOSE----------------------------------------------+
   +-FLUSH----------------------------------------------+
   |               +- = -+                    +-CHAR-+  |
   +-+-SEEK-----+--+-----+-offset--+-------+--+------+--+
   | +-POSITION-+  +- < -+         +-READ--+  +-LINE-+  |
   |               +- + -+         +-WRITE-+            |
   |               +- - -+                              |
   +-QUERY--+-DATETIME--------------------------+-------+
            +-EXISTS----------------------------+
            +-HANDLE----------------------------+
            |                       +-CHAR-+    |
            +-+-SEEK-----+--+-READ--+------+--+-+
            | +-POSITION-+  |       +-LINE-+  | |
            |               |        +-CHAR-+ | |
            |               +-WRITE--+------+-+ |
            |               |        +-LINE-+ | |
            |               +-SYS-------------+ |
            +-SIZE------------------------------+
            +-STREAMTYPE------------------------+
            +-TIMESTAMP-------------------------+

Write Options:

|--+---------+--------------------------------------------------|
   +-APPEND--+
   +-REPLACE-+

Options:

                   +-----------------------------------+
                   V                                   |
|--+------------+----+-NOBUFFER----------------------+-+--------|
   +-SHARED-----+    +-BINARY--+-------------------+-+
   +-SHAREREAD--+              +-RECLENGTH--length-+
   +-SHAREWRITE-+

OPEN

Opens the stream object and returns READY:. (If unsuccessful, the previous information about return codes applies.) The default for OPEN is to open the stream for both reading and writing data, for example: 'OPEN BOTH'. To specify that the stream be only opened for input or output, add READ or WRITE, to the command string.

The following is a description of the options for OPEN:

READ: Opens the stream only for reading.
WRITE: Opens the stream only for writing.
BOTH: Opens the stream for both reading and writing. (This is the default.) The stream maintains separate read and write pointers.
APPEND: Positions the write pointer at the end of the stream. The write pointer cannot be moved anywhere within the extent of the file as it existed when the file was opened.
REPLACE: Sets the write pointer to the beginning of the stream and truncates the file. In other words, this option deletes all data that was in the stream when opened.
SHARED: Enables another process to work with the stream in a shared mode. This mode must be compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by the process that opened the stream.
SHAREREAD: Enables another process to read the stream in a shared mode.
SHAREWRITE: Enables another process to write the stream in a shared mode.
NOBUFFER: Turns off buffering of the stream. All data written to the stream is flushed immediately to the operating system for writing. This option can have a severe impact on output performance. Use it only when data integrity is a concern, or to force interleaved output to a stream to appear in the exact order in which it was written.
BINARY: Opens the stream in binary mode. This means that line end characters are ignored; they are treated like any other byte of data. This is intended to process binary data using the line operations.
Note: Specifying the BINARY option for a stream that does not exist but is opened for writing also requires the RECLENGTH option to be specified. Omitting the RECLENGTH option in this case raises an error condition.
RECLENGTH length: Allows the specification of an exact length for each line in a stream. This allows line operations on binary-mode streams to operate on individual fixed-length records. Without this option, line operations on binary-mode files operate on the entire file (for example, as if you specified the RECLENGTH option with a length equal to that of the file). The length must be 1 or greater.

Examples:

stream_name~command("open")
stream_name~command("open write")
stream_name~command("open read")
stream_name~command("open read shared")

CLOSE

closes the stream object. The COMMAND method with the CLOSE option returns READY: if the stream is successfully closed or an appropriate error message otherwise. If an attempt to close an unopened file occurs, then the COMMAND method with the CLOSE option returns a null string ("").

FLUSH

forces any data currently buffered for writing to be written to this stream.

SEEK offset

sets the read or write position to a given number (offset) within a persistent stream. If the stream is open for both reading and writing and you do not specify READ or WRITE, both the read and write positions are set.

Note: See Input and Output Streams for a discussion of read and write positions in a persistent stream.

To use this command, you must first open the stream (with the OPEN stream command described previously or implicitly with an input or output operation). One of the following characters can precede the offset number.

=: explicitly specifies the offset from the beginning of the stream. This is the default if you supply no prefix. For example, an offset of 1 with the LINE option means the beginning of the stream.
<: specifies offset from the end of the stream.
+: specifies offset forward from the current read or write position.
-: specifies offset backward from the current read or write position.

The command method with the SEEK option returns the new position in the stream if the read or write position is successfully located, or an appropriate error message.

The following is a description of the options for SEEK:

READ: specifies that this command sets the read position.
WRITE: specifies that this command sets the write position.
CHAR: specifies the positioning in terms of characters. This is the default.
LINE: specifies the positioning in terms of lines. For non-binary streams, this is potentially an operation that can take a long time to complete because, in most cases, the file must be scanned from the top to count the line-end characters. However, for binary streams with a specified record length, the new resulting line number is simply multiplied by the record length before character positioning. See Line versus Character Positioning for a detailed discussion of this issue.
Note: If you do line positioning in a file open only for writing, you receive an error message.

Examples:

stream_name~command("seek =2 read")
stream_name~command("seek +15 read")
stream_name~command("seek -7 write line")
fromend  = 125
stream_name~command("seek <"fromend read)

POSITION

is a synonym for SEEK.

Used with these stream_commands, the COMMAND method returns specific information about a stream. Except for QUERY HANDLE and QUERY POSITION, the stream returns the query information even if the stream is not open. The stream returns the null string for nonexistent streams.

QUERY DATETIME

Returns the date and time stamps of a stream in US format. For example:

stream_name~command("query datetime")

A sample output might be:

11-12-95 03:29:12

QUERY EXISTS

Returns the full path specification of the stream object, if it exists, or a null string. For example:

stream_name~command("query exists")

A sample output might be:

c:\data\file.txt

QUERY HANDLE

Returns the handle associated with the open stream. For example:

stream_name~command("query handle")

A sample output might be: 3

QUERY POSITION

Returns the current read or write position for the stream, as qualified by the following options:

READ

Returns the current read position.

WRITE

Returns the current write position.

Note: If the stream is open for both reading and writing, this returns the read position by default. Otherwise, this returns the appropriate position by default.

CHAR

Returns the position in terms of characters. This is the default.

LINE

Returns the position in terms of lines. For non-binary streams, this operation can take a long time to complete. This is because the language processor starts tracking the current line number if not already doing so, and, thus, might require a scan of the stream from the top to count the line-end characters. See Line versus Character Positioning for a detailed discussion of this issue. For example:

stream_name~command("query position write")

A sample output might be:

SYS

Returns the operating system stream position in terms of characters.

QUERY SEEK

Is a synonym for QUERY POSITION.

QUERY SIZE

Returns the size, in bytes, of a persistent stream. For example:

stream_name~command("query size")

A sample output might be:

QUERY STREAMTYPE

Returns a string indicating whether the stream is PERSISTENT, TRANSIENT, or UNKNOWN.

QUERY TIMESTAMP

Returns the date and time stamps of a persistent stream in an international format. This is the preferred method of getting date and time because it provides the full 4-digit year. For example:

stream_name~command("query timestamp")

A sample output might be:

1995-11-12 03:29:12

description

>>-description-------------------------------------------------><

Returns any descriptive string associated with the current state of the stream or the Nil object if no descriptive string is available. The description method is identical with the STATE method except that the string that description returns is followed by a colon and, if available, additional information about ERROR or NOTREADY states.

flush

>>-flush-------------------------------------------------------><

Returns READY:. It forces the stream to write any buffered data to the output stream.

init

>>-init(name)-----------------------------------------------><

Initializes a stream object defined by name.

lineIn

>>-lineIn-+-------------------------+--------------------------><
          +-(-+------+-+--------+-)-+
              +-line-+ +-,count-+

Returns the next count lines. The count must be 0 or 1. The stream advances the read pointer. If you omit count, it defaults to 1. A line number may be given to set the read position to the start of a specified line. This line number must be positive and within the bounds of the stream, and must not be specified for a transient stream. A value of 1 for line refers to the first line in the stream. If the stream is not already open, the it tries to open the stream for reading and writing. If that fails, the stream is opened for input only.

lineOut

>>-lineOut-+--------------------------+------------------------><
           +-(-+--------+-+-------+-)-+
               +-string-+ +-,line-+

Returns 0 if successful in writing string to the output stream or 1 if an error occurs while writing the line. The stream advances the write pointer. If you omit string, the stream is closed. If you specify line, this positions the write pointer before writing. If the stream is not already open, the stream attempts to open for reading and writing. If that fails, the stream is opened for output only.

lines

           +-Count--+
>>-lines(--+--------+---)--------------------------------------><
           +-Normal-+

Returns the number of completed lines that available for input. If the stream has already been read with charInemphasis. this can include an initial partial line. For persistent streams the count starts at the current read position. In effect, lines reports whether a read action of charIn (see charIn) or lineIn (see lineIn) will succeed. (For an explanation of input and output, see Input and Output Streams.)

For a Queue, lines returns the actual number of lines.

Note: The chars method returns the number of characters in a persistent stream or the presence of data in a transient stream. The linesemphasis method determines the actual number of lines by scanning the stream starting at the current position and counting the lines. For large streams, this can be a time-consuming operation. Therefore, avoid the use of the LINES method in the condition of a loop reading a stream. It is recommended that you use the chars method.

The ANSI Standard has extended this function to allow an option: "Count". If this option is used, lines returns the actual number of complete lines remaining in the stream, irrespective of how long this operation takes.

The option "Normal" returns 1 if there is at least one complete line remaining in the file or 0 if no lines remain.

The default is "Count".

makeArray

              +-(LINES)-+
>>-makeArray--+---------+--------------------------------------><
              +-(CHARS)-+

Returns a fixed array that contains the data of the stream in line or character format, starting from the current read position. The line format is the default.

If you have used the charIn method, the first line can be a partial line.

open

         +-(BOTH-| Write Options |--+  +-SHARED-----+
>>-open--+--------------------------+--+------------+----------->
         +-(READ--------------------+  +-SHAREREAD--+
         +-(WRITE-| Write Options |-+  +-SHAREWRITE-+

   +-----------------------------------+
   V                                   |
>----+-------------------------------+-+--+---+----------------><
     +-NOBUFFER----------------------+    +-)-+
     +-BINARY--+-------------------+-+
               +-RECLENGTH--length-+

Write Options:

   +-------------+
   V +-APPEND--+ |
|----+---------+-+----------------------------------------------|
     +-REPLACE-+

Opens the stream and returns READY:. If the method is unsuccessful, it returns an error message string in the same form that the description method uses.

For most error conditions, the additional information is in the form of a numeric return code. This return code is the value of ERRNO, which is set whenever one of the file system primitives returns with a -1.

By default, open opens the stream for both reading and writing data, for example: 'open BOTH'. To specify that the stream be only opened for input or output, specify READ or WRITE.

The options for the open method are:

READ: Opens the stream for input only.
WRITE: Opens the stream for output only.
BOTH: Opens the stream for both input and output. (This is the default.) The stream maintains separate read and write pointers.
APPEND: Positions the write pointer at the end of the stream. (This is the default.) The write pointer cannot be moved anywhere within the extent of the file as it existed when the file was opened.
REPLACE: Sets the write pointer to the beginning of the stream and truncates the file. In other words, this option deletes all data that was in the stream when opened.
SHARED: Enables another process to work with the stream in a shared mode. (This is the default.) This mode must be compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by the process that opened the stream.
SHAREREAD: Enables another process to read the stream in a shared mode.
SHAREWRITE: Enables another process to write the stream in a shared mode.
NOBUFFER: Turns off buffering of the stream. All data written to the stream is flushed immediately to the operating system for writing. This option can have a severe impact on output performance. Use it only when data integrity is a concern, or to force interleaved output to a stream to appear in the exact order in which it was written.
BINARY: Opens the stream in binary mode. This means that line-end characters are ignored; they are treated like any other byte of data. This is for processing binary record data using the line operations.
Note: Specifying the BINARY option for a stream that does not exist but is opened for writing also requires the RECLENGTH option to be specified. Omitting the RECLENGTH option in this case raises an error condition.
RECLENGTH length: Allows the specification of an exact length for each line in a stream. This allows line operations on binary-mode streams to operate on individual fixed-length records. Without this option, line operations on binary-mode files operate on the entire file (for example, as if you specified the RECLENGTH option with a length equal to that of the file). The length must be 1 or greater.

Examples:

stream_name~open
stream_name~open("write")
stream_name~open("read")

position

             +- = -+                  +-CHAR-+
>>-position(-+-----+-offset-+-READ--+-+------+-)---------------><
             +- < -+        +-WRITE-+ +-LINE-+
             +- + -+
             +- - -+

position is a synonym for seek. (See seek .)

qualify

>>-qualify-----------------------------------------------------><

Returns the stream's fully qualified name. The stream need not be open.

query

>>-query(--+-DATETIME--------------------------+--)------------><
           +-EXISTS----------------------------+
           +-HANDLE----------------------------+
           |                       +-CHAR-+    |
           +-+-SEEK-----+--+-READ--+------+--+-+
           | +-POSITION-+  |       +-LINE-+  | |
           |               |        +-CHAR-+ | |
           |               +-WRITE--+------+-+ |
           |               |        +-LINE-+ | |
           |               +-SYS-------------+ |
           +-SIZE------------------------------+
           +-STREAMTYPE------------------------+
           +-TIMESTAMP-------------------------+

Used with these options, the query method returns specific information about a stream. Except for query HANDLE and query POSITION, the stream returns the query information even if the stream is not open. A null string is returned for nonexistent streams.

DATETIME

returns the date and time stamps of a persistent stream in US format. For example:

stream_name~query("datetime")

A sample output might be:

11-12-98 03:29:12

EXISTS

returns the full path specification of the stream, if it exists, or a null string. For example:

stream_name~query("exists")

A sample output might be:

c:\data\file.txt

HANDLE

returns the handle associated with the open stream. For example:

stream_name~query("handle")

A sample output might be:

POSITION

returns the current read or write position for the stream, as qualified by the following options:

READ

returns the current read position.

WRITE

returns the current write position.

Note: If the stream is open for both reading and writing, this returns the read position by default. Otherwise, this returns the specified position.

CHAR

returns the position in terms of characters. This is the default.

LINE

returns the position in terms of lines. For non-binary streams, this operation can take a long time to complete. This is because the language processor starts tracking the current line number if not already doing so, and, thus, might require a scan of the stream from the top to count the line-end characters. See Line versus Character Positioning for a detailed discussion of this issue. For example:

stream_name~query("position write")

A sample output might be:

SYS

returns the operating system stream position in terms of characters.

SIZE

returns the size, in bytes, of a persistent stream. For example:

stream_name~query("size")

A sample output might be:

STREAMTYPE

returns a string indicating whether the stream object is PERSISTENT, TRANSIENT, or UNKNOWN.

TIMESTAMP

returns the date and time stamps of a persistent stream in an international format. This is the preferred method of getting the date and time because it provides the full 4-digit year. For example:

stream_name~query("timestamp")

A sample output might be:

1998-11-12 03:29:12

say

>>-say--+----------------+-------------------------------------><
        +-(-+--------+-)-+
            +-string-+

Returns 0 if successful in writing string to the output stream or 1 if an error occurs while writing the line.

seek

         +- = -+                  +-CHAR-+
>>-seek(-+-----+-offset-+-------+-+------+-)-------------------><
         +- < -+        +-READ--+ +-LINE-+
         +- + -+        +-WRITE-+
         +- - -+

Sets the read or write position to a given number (offset) within a persistent stream. If the stream is open for both reading and writing and you do not specify READ or WRITE, both the read and write positions are set.

Note: See Input and Output Streams for a discussion of read and write positions in a persistent stream.

To use this method, you must first open the stream object (with the OPEN method described previously or implicitly with an input or output operation). One of the following characters can precede the offset number:

=: Explicitly specifies the offset from the beginning of the stream. This is the default if you supply no prefix. For example, an offset of 1 means the beginning of the stream.
<: Specifies offset from the end of the stream.
+: Specifies offset forward from the current read or write position.
-: Specifies offset backward from the current read or write position.

The seek method returns the new position in the stream if the read or write position is successfully located, or an appropriate error message.

The following is a description of the options for seek:

READ: specifies that the read position be set.
WRITE: specifies that the write position be set.
CHAR: specifies that positioning be done in terms of characters. This is the default.
LINE: specifies that the positioning be done in terms of lines. For non-binary streams, this is potentially an operation that can take a long time to complete because, in most cases, the file must be scanned from the top to count the line-end characters. However, for binary streams with a specified record length, the new resulting line number is simply multiplied by the record length before character positioning. See Line versus Character Positioning for a detailed discussion of this issue.
Note: If you do line positioning in a file open only for writing, you receive an error message.

Examples:

stream_name~seek("=2 read")
stream_name~seek("+15 read")
stream_name~seek("-7 write line")
fromend  = 125
stream_name~seek("<"fromend read)

state

>>-state-------------------------------------------------------><

Returns a string indicating the current stream state.

The returned strings are as follows:

ERROR: The stream has been subject to an erroneous operation (possibly during input, output, or through the STREAM function). See Errors during Input and Output. You might be able to obtain additional information about the error with the description method or by calling the STREAM function with a request for the description.
NOTREADY: The stream is known to be in such a state that the usual input or output operations attempted upon would raise the NOTREADY condition. (See Errors during Input and Output.) For example, a simple input stream can have a defined length. An attempt to read that stream (with CHARIN or LINEIN, perhaps) beyond that limit can make the stream unavailable until the stream has been closed (for example, with LINEOUT(name)) and then reopened.
READY: The stream is known to be in such a state that the usual input or output operations might be attempted. This is the usual state for a stream, although it does not guarantee that any particular operation will succeed.
UNKNOWN: The state of the stream is unknown. This generally means that the stream is closed or has not yet been opened.

string

>>-string------------------------------------------------------><

Returns a string that indicates the name of the object the stream represents i.e. the name of the file.

supplier

>>-supplier----------------------------------------------------><

Returns a StreamSupplier object for the stream containing the remaining stream lines and linenumber positions for the stream.

uninit

>>-uninit------------------------------------------------------><

This method cleans up the object when it is garbage collected. It should not be invoked directly except via an uninit method of a subclass of the Stream class.

If the Stream class is subclassed and the subclass provides an uninit method then that method must invoke the superclass uninit method. For example:

::class CustomStream subclass Stream

...

::method uninit
/* the subclass instance cleanup code should be placed here */
super~uninit  -- this should be the last action in the method
return