[ Stream I/O | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# set_stream(+StreamId, +Stream)

The symbolic stream name StreamId is associated with the stream Stream.

StreamId
  Atom.
Stream
  Integer (stream number) or Atom (reserved or user-defined symbolic stream name).

## Description

This predicate is used to create new symbolic alias names for physical streams, or to redirect existing symbolic stream names to other physical streams.

If StreamId is a new user-defined stream name, then that new name is associated with the physical stream denoted by the Stream. Stream can be in the form of a physical stream number, a name of a physical stream (stdin, stdout, stderr, null), or any existing symbolic stream name.

If StreamId is an already existing stream name (including one of the symbolic system stream names like input, output, error, warning_output, log_output), then that stream is redirected to Stream. Any previously existing association of the name StreamId is forgotten. Note that other alias names for the same physical stream are not affected by redirection.

When a user-defined symbolic stream is closed, the associated physical stream is closed and the association forgotten. Note that it is not enough to close the physical stream alone because the association of symbolic an physical stream remains (even though the physical stream is closed) until the symbolic stream is closed as well. A system-defined symbolic stream will be redirected to its default when the associated physical stream is closed.

The physical stream associated with a symbolic stream name can be queried using get_stream/2.

### Modes and Determinism

- set_stream(+, +) is det

### Exceptions

(4) instantiation fault
  Either StreamId or Stream is uninstantiated.
(5) type error
  Either StreamId is not an atom or Stream is not a stream number or symbolic stream name.
(193) illegal stream specification
  Stream is an illegal stream specification.
(194) too many symbolic names of a stream
  A physical stream has more than 255 logical stream names assigned to it.

## Examples

            % suppress standard output temporarily:
    	[eclipse]: set_stream(output, null).
    	Yes (0.00s cpu)
    	[eclipse]: writeln(hello).
    	Yes (0.00s cpu)

            % set standard output back to default:
    	[eclipse]: set_stream(output, stdout).
    	Yes (0.00s cpu)
    	[eclipse]: writeln(hello).
    	hello
    	Yes (0.00s cpu)

            % alias the names s and output:
            [eclipse]: open(file1,update,s), set_stream(output,s),
    		   writeln(output,hi), flush(output).
    	yes.
    	[eclipse]: seek(s,0), read(s,X).
    	X = hi
    	yes.

    Error:
            set_stream(a, S).        (Error 4).
            set_stream(1.0, S).      (Error 5).
            set_stream(a, nonex).    (Error 193).

## See Also

open / 4, get_stream / 2