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

The Stream Classes

This section describes the ooRexx classes which implement the classic 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. All the methods in this must be overridden or they will throw a syntax error when invoked.

Figure 5-6. The InputStream class and methods

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

arrayIn

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

charIn

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

charOut

This method is a NOP method.

chars

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

close

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

lineIn

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

lineOut

This method is a NOP method.

lines

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

open

This method is a NOP method.

position

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

The OutputStream Class

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

Figure 5-7. The OutputStream class and methods

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

arrayOut

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

charIn

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

charOut

This method is a NOP method.

chars

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

close

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

lineIn

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

lineOut

This method is a NOP method.

lines

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

open

This method is a NOP method.

position

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

The InputOutputStream Class

This class is defined as an abstract mixin class. It must be implemented by subclassing it. All the methods from its mixin classes must be overridden or they will throw a syntax error when invoked.

Figure 5-8. 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)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

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-9. 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 although there are currently no methods defined in that class.

Inherited Methods

Methods inherited from the Object class.

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

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 a stream named name, but does not open the stream. See Initialization for more information. Returns the new stream object

arrayIn

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

This method overrides the arrayIn method from the InputStream class.

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-+

This method overrides the arrayOut method from the OutputStream class.

Returns a stream object that contains the data from array.

charIn

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

This method overrides the charIn method from the InputStream class and the charIn method from the OutputStream class.

Returns a string of up to length characters from the character input stream receiving the message. The language processor advances the read pointer. If you omit length, it defaults to 1. If you specify start, this positions the read pointer before reading. If the stream is not already open, the language processor tries to open the stream for reading and writing. If that fails, the language processor opens the stream for read only. (See CHARIN (Character Input) for information about the CHARIN built-in function.)

charOut

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

This method overrides the charOut method from the InputStream class and the charOut method from the OutputStream class.

Returns the count of characters remaining after trying to write string to the character output stream receiving the message. The language processor 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 language processor closes the stream.

If you specify start, this positions the write pointer before writing. If the stream is not already open, the language processor tries to open the stream for reading and writing. If that fails, the language processor opens the stream for write only. (See CHAROUT (Character Output) for information about the CHAROUT built-in function.)

chars

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

This method overrides the chars method from the InputStream class and the chars method from the OutputStream class.

Returns the total number of characters remaining in the character input stream receiving the message. The default input stream is STDIN. The count includes any line separator characters, if these are defined for the stream. In the case of persistent streams, it 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. (See CHARS (Characters Remaining) for information about the CHARS built-in function.)

close

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

This method overrides the close method from the InputStream class and the close method from the OutputStream class.

Closes the stream that receives the message. 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 the language processor evaluates to a command string that corresponds to the following diagram:

           +-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 receiving the message 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_name receiving the message can be only read or written to, 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 language processor 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 force file operations that are compatible with other Rexx language processors that run on record-based systems, or 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 receiving the message. The COMMAND method with the CLOSE option returns READY: if the receiving stream object 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 receiving stream object (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 language processor returns the query information even if the stream is not open. The language processor 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 receiving the message, 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 that is the receiving stream object. For example:

stream_name~command("query handle")

A sample output might be: 3

QUERY POSITION

Returns the current read or write position for the receiving stream object, 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 that is the receiving stream object. For example:

stream_name~command("query size")

A sample output might be:

QUERY STREAMTYPE

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

QUERY TIMESTAMP

Returns the date and time stamps of the receiving stream object 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. (The state method describes these states.)

flush

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

Returns READY:. It forces any data currently buffered for writing to be written to the stream receiving the message.

init

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

Initializes a stream object defined by name.

lineIn

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

This method overrides the lineIn method from the InputStream class and the lineIn method from the OutputStream class.

Returns the next count lines. The count must be 0 or 1. The language processor 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 language processor tries to open the stream for reading and writing. If that fails, the language processor opens the stream for read-only. (See LINEIN (Line Input) for information about the LINEIN built-in function.)

lineOut

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

This method overrides the lineOut method from the InputStream class and the lineOut method from the OutputStream class.

Returns 0 if successful in writing string to the character output stream receiving the message or 1 if an error occurs while writing the line. The language processor advances the write pointer. If you omit string, the language processor closes the stream. If you specify line, this positions the write pointer before writing. If the stream is not already open, the language processor tries to open the stream for reading and writing. If that fails, the language processor opens the stream for write-only. (See LINEOUT (Line Output) for information about the LINEOUT built-in function.)

lines

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

This method overrides the lines method from the InputStream class and the lines method from the OutputStream class.

Returns the number of completed lines that remain in the character input stream receiving the message. 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. (See LINES (Lines Remaining) for information about the LINES built-in function.)

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 (see chars) or the LINES built-in function for this purpose.

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".

The defaults of the lines method and function are different because of compatibility reasons.

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-+

This method overrides the open method from the InputStream class and the open method from the OutputStream class.

Opens the stream to which you send the message 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 receiving the message can be only read or only written to, specify READ or WRITE.

The options for the open method are:

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 language processor 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 intended to force file operations that are compatible with other Rexx language processors that run on record-based systems, or 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~open
stream_name~open("write")
stream_name~open("read")

position

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

This method overrides the position method from the InputStream class and the position method from the OutputStream class.

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 language processor returns the query information even if the stream is not open. The language processor returns the null string for nonexistent streams.

DATETIME

returns the date and time stamps of the receiving stream object 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 receiving stream object, 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 that is the receiving stream object. For example:

stream_name~query("handle")

A sample output might be:

POSITION

returns the current read or write position for the receiving stream object, 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~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 that is the receiving stream object. For example:

stream_name~query("size")

A sample output might be:

STREAMTYPE

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

TIMESTAMP

returns the date and time stamps of the receiving stream object 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 character output stream receiving the message 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 receiving 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 that indicates the current state of the specified stream.

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 supplier object for the stream. When you send appropriate messages to the supplier object (see The Supplier Class), it enumerates all the lines in the stream object. The supplier enumerates the items in their line order.

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. The following example shows how to accomplish this.

::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

Prev	Home	Next
The Builtin Classes	Up	The Collection Classes