3.2.49. STREAM(streamid[,option[,command]])
This function was added to REXX in language level 4.00. It
provides a general mechanism for doing operations on streams.
However, very little is specified about how the internal of this
function should work, so you should consult the implementation
specific documentation for more information.
The streamid identifies a stream. The actual contents and format
of this string is implementation dependent.
The option selects one of several operations which STREAM() is to
perform. The possible operations are:
[C]
(Command) If this option is selected, a third parameter must
be present, command, which is the command to be performed on
the stream. The contents of command is implementation
dependent. For Regina, the valid commands follow. Commands
consist of one or more space separated words.
[D]
(Description) Returns a description of the state of streamid.
The return value is implementation dependent.
[S]
(Status) Returns a state which describes the state of
streamid. The standard requires that it is one of the
following: ERROR, NOTREADY, READY and UNKNOWN. The meaning of
these are described in the chapter; Stream Input and Output.
Note that the options Description and Status really have the same
function, but that Status in general is implementation
independent, while Description is implementation dependent.
The command specifies the command to be performed on streamid. The
possible operations are:
[READ]
Open for read access. The file pointer will be positioned at
the start of the file, and only read operations are allowed.
This command is Regina-specific; use OPEN READ in its place.
[WRITE]
Open for write access and position the current write position
at the end of the file. An error is returned if it was not
possible to get appropriate access. This command is Regina-
specific; use OPEN WRITE in its place.
[APPEND]
Open for append access and position the current write
position at the end of the file. An error is returned if it
was not possible to get appropriate access. This command is
Regina-specific; use OPEN WRITE APPEND in its place.
[UPDATE]
Open for append access and position the current write
position at the end of the file. An error is returned if it
was not possible to get appropriate access. This command is
Regina-specific; use OPEN BOTH in its place.
[CREATE]
Open for write access and position the current write position
at the start of the file. An error is returned if it was not
possible to get appropriate access. This command is Regina-
specific; use OPEN WRITE REPLACE in its place.
[CLOSE]
Close the stream, flushing any pending writes. An error is
returned if it was not possible to get appropriate access.
[FLUSH]
Flush any pending write to the stream. An error is returned
if it was not possible to get appropriate access.
[STATUS]
Returns status information about the stream in human readable
form that Regina stores about the stream.
[FSTAT]
Returns status information from the operating system about
the stream.
[RESET]
Resets the stream after an error. Only streams that are
resettable can be reset.
[READABLE]
Returns 1 if the stream is readable by the user or 0
otherwise.
[WRITABLE]
Returns 1 if the stream is writeable by the user or 0
otherwise.
[EXECUTABLE]
Returns 1 if the stream is executable by the user or 0
otherwise.
[QUERY]
Returns information about the named stream. If the named
stream does not exists, then the empty string is returned.
This command is further broken down into the following sub-
commands:
DATETIME returns the date and time of last
modification of the stream in Rexx US
Date format; MM-DD-YY HH:MM:SS.
EXISTS returns the fully-qualified file name of
the specified stream.
HANDLE returns the internal file handle of the
stream. This will only return a valid
value if the stream was opened explicitly
or implicitly by Regina.
POSITION READ returns the current read position of the
open stream. This is expressed in
characters, so returns the same value as
POSITION CHAR.
POSITION WRITE returns the current write position of the
open stream. This is expressed in
characters.
POSITION CHAR returns the current read position of the
open stream. This is expressed in
characters.
POSITION LINE returns the current read position of the
open stream. This is expressed in lines.
POSITION SYS returns the current read position of the
open stream as the operating reports it.
This is expressed in characters.
SIZE returns the size, expressed in
characters, of the persistent stream.
STREAMTYPE returns the type of the stream. One of
TRANSIENT, PERSISTENT or UNKNOWN is
returned.
TIMESTAMP returns the date and time of last
modifcation of the stream. The format of
the string returned is YYYY-MM-DD
HH:MM:SS.
[OPEN]
Opens the stream in the optional mode specified. If no
optional mode is specified, the default is OPEN BOTH.
READ The file pointer will be positioned at
the start of the file, and only read
operations are allowed.
WRITE Open for write access and position the
current write pointer at the end of the
file. On platforms where it is not
possible to open a file for write without
also allowing reads, the read pointer
will be positioned at the start of the
file. An error is returned if it was not
possible to get appropriate access.
BOTH Open for read and write access. Position
the current read pointer at the start of
the file, and the current write pointer
at the end of the file. An error is
returned if it was not possible to get
appropriate access.
WRITE APPEND Open for write access and position the
write pointer at the end of the file. On
platforms where it is not possible to
open a file for write without also
allowing reads, the read pointer will be
positioned at the start of the file.
WRITE REPLACE Open for write access and position the
current write position at the start of
the file. On platforms where it is not
possible to open a file for write without
also allowing reads, the read pointer
will be positioned at the start of the
file. This operation will clear the
contents of the file. An error is
returned if it was not possible to get
appropriate access.
BOTH APPEND Open for read and write access. Position
the current read position at the start of
the file, and the current write position
at the end of the file. An error is
returned if it was not possible to get
appropriate access.
BOTH REPLACE Open for read and write access. Position
both the current read and write pointers
at the start of the file. An error is
returned if it was not possible to get
appropriate access.
PREV NEXT