STREAM

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

  ┴╓: 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.

    ┴╓: 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')
    

    ---

    [Back: SPACE]
    [Next: STRIP]