| THE META-HTML LANGUAGE REFERENCE MANUAL

File Operators | [TOC] | Session Operators

## Section Intro: Stream Operators

Synopsis:

A stream is a data object upon which various input and output operations may be performed.

Meta-HTML provides commands for creating, opening, reading from, and writing to, stream objects. The referenced underlying object may either be a file or a network connection.

Commands:

stream-get stream-get-contents stream-put | stream-put-contents stream-readable stream-shutdown | stream-writable with-open-stream

More Information:

There are three special names which can be used with `with-open-stream`, these are `*standard-input*`, `*standard-output*`, and `*standard-error*`.

`*standard-input*` always names the stream that from which input was being read at the time the engine, server, or `mhc` invoked. `*standard-output*` always names the stream to which output is being written by the engine, server or `mhc`.

`*standard-error*` always names the stream where error output will appear -- this stream could be the same as the one named by `*standard-output*`, but this does not have to be the case.

### Function Documentation

`<stream-get STREAM [STOP-AT=CHARACTER]>` | Simple

Reads a chunk of data from STREAM and returns it. STREAM is read until the character value specified by CHARACTER (defaulting to a newline) is reached, and that data upto and including the final CHARACTER is returned. One way to read all of the available data is to supply the empty string as the value of STOP-AT:

      <with-open-stream stream www.ua.com:80 type=tcp mode=read-write>
        <stream-put stream "GET /welcome.mhtml HTTP/1.0\n\n">
        <set-var the-page=<stream-get stream stop-at="">>
      </with-open-stream>

`<stream-get-contents STREAM VAR>` | Simple

Reads the contents of the stream STREAM into the binary variable VAR. You had better understand binary variables before you use this. However, you can easily use this in conjunction with `stream-put-contents`, and `coerce-var`.

`<stream-put STREAM STRING>` | Simple

Writes STRING to STREAM.

`<stream-put-contents STREAM VAR>` | Simple

Writes the contents of the binary variable VAR to STREAM. You had better understand binary variables before you use this. However, you can easily use this in conjunction with `stream-get-contents`.

`<stream-readable STREAM>` | Simple

Returns `"true"` if STREAM is an open stream which was opened with a mode of `read` or `read-write`, or nothing otherwise.

`<stream-shutdown STREAM>` | Simple

Only for use with network streams, this tells the underlying operating system (and the other end of the network connection) that no additional input or output will be done using this object. In effect, it immediately closes the stream.

When used in conjunction with `*standard-output*`, this can be used to close the HTTP connection to the client, and yet continue processing data.

`<stream-writable STREAM>` | Simple

Returns `"true"` if STREAM is an open stream which was opened with a mode of `write`, `append`, `write-create` or `read-write`, or nothing otherwise.

`<with-open-stream VAR NAME [TYPE=(FILE|TCP)] [MODE=OPEN-MODE]> body </with-open-stream>` | Complex

Create an environment in which VAR is bound to the indicator of an open stream, named by NAME.

The stream is either of type `FILE`, or `TCP`, in which case it is an open network connection. When TYPE is `TCP`, NAME specifies the host and port to connect to, in the form `Hostname:Port-Number`. PORT-NUMBER can either be a symbolic name which is widely recognized (e.g., `SMTP`), or the digits which make up the port number, (e.g., `25`). The possible values for MODE are:

- `READ`:
  The stream is opened for reading only. The underlying object must already exist.

- `WRITE`:
  The stream is opened for writing only. The underlying object must already exist.

- `READ-WRITE`:
  The stream is opened for both reading and writing. The underlying object must already exist.

- `APPEND`:
  The stream is opened for writing only. If the underlying object did not already exist, it is created. Information written to this stream appears after any information that was already present in the underlying object.

- `WRITE-CREATE`:
  The stream is opened for writing only. The underlying object is created fresh, even if it had already existed.

Edit Section
Function Index
Variable Index

The META-HTML Reference Manual V1.4 Copyright © 1995, 1996, Brian J. Fox, 1996, 1997 Universal Access Inc.
Found a bug? Send mail to bug-manual@metahtml.com