# Section 8.10.3.9:
PIPE

###### class PIPE < $FILES

#### Formal Types

types
SAME = BIN_FILE ;

This class implements a model of a virtual binary file to and from which data may be read either within one program (with more than one thread, say) or between programs.

#### External specifications

The following routines are required to be implemented for this class in accordance with the specifications given in the abstract class $FILES :-

- open_for_read(name : STR) : SAME
- open_for_write(name : STR) : SAME
- open_at_end(name : STR) : SAME
- open_for_update(name : STR) : SAME
- open_at_end_for_update(name : STR) : SAME
- create_for_write(name : STR) : SAME
- create_for_update(name : STR) : SAMEE
- create_temp : SAME
- is_open : BOOL
- readable : BOOL
- writable : BOOL
- append : BOOL
- update : BOOL
- close
- error : BOOL
- error_message : STR
- clear

#### plus

This is the first of two features which are provided to send binary data to a file, extending the length of the file as needed.

plus | (
| entity : BINSTR
| ) : SAME

##### Formal Signature

plus1(self : SAME, entity : BINSTR) res : [SAME]

##### Pre-condition

pre writable(self)
and (len entity > 0)

##### Post-condition

post res = nil
or (res = self~ ^ entity)

This feature either inserts (if update is true) or appends the given item to the file channel to which self is a connection, returning self if successful, otherwise returning void.

#### plus

This is the variant of plus which places the value of the single octet item at the current position in the file, extending the file size if needed.

plus | (
| item : OCTET
| ) : SAME

##### Formal Signature

plus2(self : SAME, item : OCTET) res : [SAME]

##### Pre-condition

pre writable(self)

##### Post-condition

post res = nil
or (res = self~ ^ [entity])

This feature appends the given octet to the file channel to which self is a connection, returning self if successful, otherwise returning void.

#### get

This is the first of a pair of 'reading' operations provided on a pipe since, being virtual the concept of total contents does not exist. This version merely attempts to retrieve a single octet.

get | : OCTET

##### Formal Signature

get(self : SAME) res : [OCTET]

##### Pre-condition

pre is_open(self)

##### Post-condition

post (error(self)
and (res = nil))
or res ^ self = self~

This routine retrieves a single octet from the pipe. If reading failed then error will be true and the result is undefined.

#### get

This retrieval operation only retrieves as much as the pipe contains or the given count, whichever is the lesser. This routine only returns a void if reading errors have occurred.

get | (
| cnt : CARD
| ) : BINSTR

##### Formal Signature

get2(self : SAME, count : CARD) res : [BINSTR]

##### Pre-condition

pre is_open(self)
and (count > 0)

##### Post-condition

post ((res = nil) and error(self))
or ((len res > 0)
and (len res <= count)
and (res ^ self = self~))

This routine retrieves a sequence of octets from the pipe which are returned as a binary string if successful. The length of the string retrieved will always be greater than zero and less than or equal to count. If not successful then error will be true and the result void!

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Friday, 17 November 2000. |