Make your own free website on Tripod.com
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