OS/2 Procedures Language 2/REXX


Inf-HTML [About][Toc][Index] 0.9b (c) 1995 Peter Childs


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