Product SiteDocumentation Site

7.4.60. STREAM


>>-STREAM(name--+-----------------------------------+--)-------><
                |    +-State----------------------+ |
                +-,--+----------------------------+-+
                     +-Command--,--stream_command-+
                     +-Description----------------+
Returns a string describing the state of, or the result of an operation upon, the character stream name. The result may depend on characteristics of the stream that you have specified in other uses of the STREAM function. (To understand the input and output functions, see Chapter 14, Input and Output Streams.) This function requests information on the state of an input or output stream or carries out some specific operation on the stream.
The first argument, name, specifies the stream to be accessed. The second argument can be one of the following strings that describe the action to be carried out. (Only the capitalized letter is needed; all characters following it are ignored.)
Command
an operation (specified by the stream_command given as the third argument) is applied to the selected input or output stream. The string that is returned depends on the command performed and can be a null string. The possible input strings for the stream_command argument are described later.
Description
returns any descriptive string associated with the current state of the specified stream. It is identical to the State operation, except that the returned string is followed by a colon and, if available, additional information about the ERROR or NOTREADY states.
State
returns a string that indicates the current state of the specified stream. This is the default operation.
The returned strings are as described in Section 5.2.4.23, “state”.

Note

The state (and operation) of an input or output stream is global to a Rexx program; it is not saved and restored across internal function and subroutine calls (including those calls that a CALL ON condition trap causes).

7.4.60.1. Stream Commands

The following stream commands are used to:
  • Open a stream for reading, writing, or both.
  • Close a stream at the end of an operation.
  • Position the read or write position within a persistent stream (for example, a file).
  • Get information about a stream (its existence, size, and last edit date).
The streamcommand argument must be used when--and only when--you select the operation C (command). The syntax is: 
>>-STREAM(name,"C",streamcommand)------------------------------><
In this form, the STREAM function itself returns a string corresponding to the given streamcommand if the command is successful. If the command is unsuccessful, STREAM returns an error message string in the same form as the D (Description) operation supplies.
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.
7.4.60.1.1. Command Strings
The argument streamcommand 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--| Write Options |-+                  |
   +-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 named stream. The default for OPEN is to open the stream for both reading and writing data, for example, "OPEN BOTH".
The STREAM function itself returns a description string similar to the one that the D option provides, for example, "READY:" if the named stream is successfully opened, or "ERROR:2" if the named stream is not found.
The following is a description of the options for OPEN:
READ
opens the stream for reading only.
WRITE
opens the stream for writing only.
BOTH
opens the stream for both reading and writing. (This is the default.) Separate read and write pointers are maintained.
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. Thus, all data written to the stream is flushed immediately to the operating system for writing. This option can severely affect output performance. Therefore, 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
causes the stream to be opened in binary mode. This means that line end characters are ignored and treated as another 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 the RECLENGTH option were specified with a length equal to that of the file). length must be 1 or greater.
Examples:

Example 7.74. Builtin function STREAM

stream(strout,"c","open")
stream(strout,"c","open write")
stream(strinp,"c","open read")
stream(strinp,"c","open read shared")

CLOSE
closes the named stream. The STREAM function itself returns READY: if the named stream is successfully closed, or an appropriate error message. If an attempt is made to close an unopened file, STREAM returns a null string ("").

Example 7.75. Builtin function STREAM on unopened file

stream("STRM.TXT","c","close")

FLUSH
forces any data currently buffered for writing to be written to this stream.
SEEK offset
sets the read or write position within a persistent stream. If the stream is opened for both reading and writing and no SEEK option is specified, both the read and write positions are set.

Note

See Chapter 14, Input and Output Streams for a discussion of read and write positions in a persistent stream.
To use this command, the named stream must first be opened with the OPEN stream command 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 no prefix is supplied. Line Offset=1 means the beginning of 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 STREAM function itself returns the new position in the stream if the read or write position is successfully located or an appropriate error message otherwise.
The following is a description of the options for SEEK:
READ
specifies that the read position is to be set by this command.
WRITE
specifies that the write position is to be set by this command.
CHAR
specifies that the positioning is to be done in terms of characters. This is the default.
LINE
specifies that the positioning is to be done in terms of lines. For non-binary streams, this is an operation that can take a long time to complete, because, in most cases, the file must be scanned from the top to count line-end characters. However, for binary streams with a specified record length, this results in a simple multiplication of the new resulting line number by the record length, and then a simple character positioning. See Section 14.1.5, “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.

Example 7.76. Builtin function STREAM examples

stream(name,"c","seek =2 read")
stream(name,"c","seek +15 read")
stream(name,"c","seek -7 write line")
fromend  = 125
stream(name,"c","seek <"fromend read)

POSITION
is a synonym for SEEK.
7.4.60.1.2. QUERY Stream Commands
Used with these stream commands, the STREAM function 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 UNKNOWN for QUERY STREAMTYPE and the null string for nonexistent streams.
Note that technically although a directory is persistent, it is not a stream. If the directory exists, the date / time queries return the time stamp of the directory, QUERY SIZE returns 0, and QUERY STREAMTYPE returns UNKNOWN. The other commands return the null string.
QUERY DATETIME
returns the date and time stamps of a stream in US format. This is included for compatibility with OS/2®.

Example 7.77. Builtin function STREAM QUERY examples

stream("..\file.txt","c","query datetime")

A sample output might be: 
11-12-98 03:29:12
QUERY EXISTS
returns the full path specification of the named stream, if it exists, or a null string.

Example 7.78. Builtin function STREAM QUERY EXISTS examples

stream("..\file.txt","c","query exists")

A sample output might be: 
c:\data\file.txt
QUERY HANDLE
returns the handle associated with the open stream.

Example 7.79. Builtin function STREAM QUERY HANDLE examples

stream("..\file.txt","c","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, the default is to return the read position. Otherwise, it 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, because the language processor starts tracking the current line number if not already doing so. Thus, it might require a scan of the stream from the top to count line-end characters. See Section 14.1.5, “Line versus Character Positioning” for a detailed discussion of this issue.

Example 7.80. Builtin function STREAM QUERY POSITION examples

stream("myfile","c","query position write")

A sample output might be: 
247
SYS
returns the operating-system stream position in terms of characters.
QUERY SIZE
returns the size, in bytes, of a persistent stream.

Example 7.81. Builtin function STREAM QUERY SIZE examples

stream("..\file.txt","c","query size")

A sample output might be: 
1305
QUERY STREAMTYPE
returns a string indicating whether the stream is PERSISTENT, TRANSIENT, or UNKNOWN.
QUERY TIMESTAMP
returns the date and time stamps of a stream in an international format. This is the preferred method of getting the date and time because it provides the full 4-digit year.

Example 7.82. Builtin function STREAM QUERY TIMESTAMP examples

stream("..\file.txt","c","query timestamp")

A sample output might be: 
1998-11-12 03:29:12