![[About]](r:\html\rexxabout.gif)
![[Toc]](r:\html\rexxtoc.gif)
0.9b (c) 1995 Peter Childs
>>---STREAM(name--+--------------------------+-)----><
+--,---+-------------------+
+-C,--streamcommand-+
+-D-----------------+
+-S-----------------+
STREAM returns a string describing the state of, or the result of an operation upon, the character stream name. This function is used to request information on the state of an input or output stream, or to carry 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 (of which only the first letter is needed) which describes the action to be carried out:
Command an operation (specified by the streamcommand given as the
third argument) to be applied to the selected input or
output stream. The string that is returned depends on the
command performed, and can be the null string.
Description Also returns 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 ERROR or NOTREADY states.
State Returns a string that indicates the current state of the
specified stream. This is the default operation.
When used with the State option, STREAM returns one of the following strings:
'ERROR' The stream has been subject to an erroneous
operation (possibly during input, output, or
through the STREAM function. Additional information
about the error may be available by invoking the
STREAM function with a request for the
implementation-dependent description.
'NOTREADY' The stream is known to be in a state such that
normal input or output operations attempted upon it
would raise the NOTREADY condition. For example, a
simple input stream may have a defined length; an
attempt to read that stream (with the CHARIN or
LINEIN built-in functions, perhaps) beyond that
limit may make the stream unavailable until the
stream has been closed, for example, with
LINEIN(name), and then reopened.
'READY' The stream is known to be in a state such that
normal input or output operations can be attempted.
This is the usual state for a stream, though it
does not guarantee that any particular operation
will succeed.
'UNKNOWN' The state of the stream is unknown. In OS/2
implementations, this generally means that the
stream is closed (or has not yet been opened).
However, this response can be used in other
environments to indicate that the state of the
stream cannot be determined.
Note: The state (and operation) of an input or output stream is global
to a REXX program, in that it is not saved and restored across
function and subroutine calls (including those caused by a CALL
ON condition trap).
Stream Commands
The following stream commands are used to:
o Open a stream for reading or writing
o Close a stream at the end of an operation
o Position the read or write position within a persistent stream (for
example, a file)
o Get information about a stream (its existence, size, and last edit
date).
The streamcommand argument must be used 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 that supplied by the D (Description) operation.
Command strings - The argument streamcommand can be any expression that REXX evaluates as one of the following command strings:
'OPEN' Opens the named stream. The default for 'OPEN' is to
open the stream for both reading and writing data. To
specify whether name is only to be read or only to be
written to, add the word READ or WRITE to the command
string.
The STREAM function itself returns 'READY' if the
named stream is successfully opened or an appropriate
error message if unsuccessful.
Examples:
stream(strout,'c','open')
stream(strout,'c','open write')
stream(strinp,'c','open read')
'CLOSE' Closes the named stream. The STREAM function itself
returns 'READY' if the named stream is successfully
closed or an appropriate error message otherwise. If
an attempt is made to close an unopened file, then
STREAM() returns a null string ("").
Example:
stream('STRM.TXT','c','close')
'SEEK' offset Sets the read or write position a given number
(offset) within a persistent stream.
Note: In OS/2, the read and write positions are
the same. To use this command, the named
stream must first be opened (with the 'OPEN'
stream command, described previously).
The offset number can be preceded by one of the
following characters:
= Explicitly specifies the offset from the beginning of the
stream. This is the default if no prefix is supplied.
< 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; an appropriate error message is
displayed otherwise.
Examples:
stream(name,'c','seek =2')
stream(name,'c','seek +15')
stream(name,'c','seek -7')
fromend = 125
stream(name,'c','seek <'fromend)
Used with these stream commands, the STREAM function returns specific
information about a stream
'QUERY EXISTS' Returns the full path specification of the named
stream, if it exists, and a null string otherwise.
stream('..\file.txt','c','query exists')
'QUERY SIZE' Returns the size in bytes of a persistent stream.
stream('..\file.txt','c','query size')
'QUERY DATETIME' Returns the date and time stamps of a stream.
stream('..\file.txt','c','query datetime')
Inf-HTML End Run - Successful