stream()

Function

Returns the state of the stream or the result of the command.

Parameters

name

The stream name for the operation. This argument is case-sensitive.

operation

The operation that is to be performed. Only the first character is significant.

S

Returns the current state of the stream. This is the default operation. The following values can be returned:

ready

The stream is available for normal input or output operations.

error

The stream encountered an error on an input or output operation. After this call, the error condition is reset, and normal input or output operations can be attempted once again.

unknown

The specified stream is not open.

D

This operation is almost the same as S, with one exception. When error is returned, it is followed by text describing the error. This text usually contains the error number and reason code if the failure is due to a system call failure.

C

Executes a command for the specified stream. The command is specified as the third argument.

command

The stream command that is to be executed. This argument is valid only when the operation is C. The following commands are supported:

clearfile

Truncates a file to zero bytes for a stream that is opened for write. clearfile should only be used on a persistent stream.

This example empties the file:

call stream name,'c','clearfile'  

close

Closes a stream. On success, the function returns the string ready. If the stream is not known, it returns the string UNKNOWN.

This example closes the stream:

call stream file,'c','close' 

infileno

Returns the file descriptor number of the input side of a stream. The file descriptor can be used on lower-level system calls, using, for example, ADDRESS SYSCALL. This example gets the file descriptor for the read side of the stream:

fd=stream(name,'c','infileno')  

nosignal

Disables Halt Interruption for stream errors. See signal. This example disables the halt signal for the standard input/output stream:

call stream ,'c','nosignal'     

open <open-type>

Opens a stream. open-type specifies either read or write. If <open-type> is not specified, read is assumed. The function returns a string that is the name to be used for the stream on subsequent I/O functions. This string is the only name by which this stream will be known. Streams do not have to be explicitly opened. A path name that is used as a stream name on the other I/O functions will cause the stream to be opened, and the name of the stream will be that path name. Optional arguments can be specified with write, optionally followed by octal permission bits. Write always opens the file with O_CREAT, creating the file if it does not exist. The additional arguments are:

replace

Opens the file with O_TRUNC, setting the file size to 0.

append

Opens the file with O_APPEND, causing all writes to be appended to the file.

This example opens a stream for the file mydata.txt:

file=stream('mydata.txt','c','open write')

This example opens a stream for the file mydata.txt, but replaces the file if it exists:

file=stream('mydata.txt','c','open write replace') 

outfileno

Returns the file descriptor number of the output side of a stream. The file descriptor can be used on lower-level system calls, using, for example, ADDRESS SYSCALL. This example gets the file descriptor for the write side of the stream:

fd=stream(name,'c','outfileno')   

pclose

Closes a process stream. On success, the function returns the completion code for the process that is run via the popen command.

pid

Returns the process ID number for the shell process opened with popen. This example gets the PID for a stream opened with popen:

pid=stream(name,'c','pid')

popen <open-type>

Opens a pipe to a shell command that is specified by the stream name.<open-type> must specify read or write. If read is specified, the input functions can be used to read the standard output from the command. If write is specified, the output functions can be used to pipe data to the standard input of the shell command. In either case, the shell command inherits the standard error file for the calling process.

The command that is run is always /bin/sh -c followed by the specified shell command. This means that the completion code is the one returned by the shell. It usually returns the command's completion code. You can obtain the completion code by using the pclose command.

The function returns a string that is the name to be used for the stream on subsequent I/O functions. This string is the only name by which this stream will be known.

This example opens a pipe stream to the output from the shell command ls | wc:

   file=stream('ls | wc','c','popen read') 

query <attribute>

Queries a stream attribute and returns the result:

exists

Returns the full path name of the stream name. This is equivalent to the exists() function, but is more portable. This command does not cause a stream to be opened.

size

Returns the size of the stream. This is equivalent to the size stream command, but is more portable.

This example prints the path name of the stream:

say stream('myfile','c','query exists') 

readpos [location]

Returns the position in the file where the next read will begin. If location is specified, the position is also set to the byte specified by location. location is specified as a number optionally preceded by one of the following characters:

=

An absolute byte location. This is the default.

<

An offset from the end of the stream.

+

An offset forward from the current location.

-

An offset backward from the current location.

This example gets the read location in the file, and then sets the read location to the sixth 80-byte record:

pos=stream(name,'c','readpos')     /* get read location */  
call stream name,'c','readpos' 5*80+1  /* set read location*/

signal

Enables Halt Interruption for stream errors. The NOTREADY REXX signal is not supported. This example enables the halt signal for the standard input/output stream:

call stream ,'c','signal'

size

Returns the size of the file that is associated with the stream. This example prints the size of the file:

say stream(name,'c','size')   

writepos <location>

Returns the position in the file where the next write will begin. If location is specified, the position is also set to the byte specified by location. location is specified as a number optionally preceded by one of the following characters:

=

An absolute byte location. This is the default.

<

An offset from the end of the stream.

+

An offset forward from the current location.

-

An offset backward from the current location.

This example sets the position to the end of the file:

call stream name,'c','writepos <0' 

This example sets the position to the start of the file:

call stream name,'c','writepos 1'