Page Numbers:  Yes X: 527  Y: 10.2"  First Page: 32
Margins:   Top: 1.5"   Bottom: 1" 
Heading:q(635)
Mesa Pup Package Functional Specificationy734q\b
Appendix A:  Stream Packagee24jk80\b
The Pup Package uses a stream interface different from the standard Alto/Mesa one.  Pup's version includes, among other things, subsequences (a generalization of mark bytes) and an attention (break) facility.  Note that this appendix describes the stream interface in a general (device and implementation independent) way; see the previous section on the Byte Stream Interface for Pup specifics.e18jk40
The stream package defined by the interface Stream provides a device and format independent interface for sequential access to a stream of data.  In particular,e18jk40\44f6b6f0B
It provides a vehicle by which processes or subsystems can communicate with each other, whether they reside on the same machine or on different machines.l4269e6jk40
It permits processes or subsystems to transmit arbitrary data to or from storage media in a device-independent way.l4269e6jk40
It defines a standard way for transforming the detailed interface for a device into a uniform, high level interface which can be used by other client software.l4269e6jk40
It provides an environment for implementing simple transformations to be performed on the data as it is being transmitted.l4269e6jk40
It provides optional access to and control over the mapping of data onto the physical format of the storage or transmission medium being used. l4269e6jk40
The stream package provides several facilities, not all of which may be important to an individual client.  First, there is the stream interface, the set of procedures and data types by which a client actually controls the transmission of a stream of information.  Each of the operations of the stream interface takes as a parameter a Stream.Handle which identifies the particular stream being accessed.  Second, the stream package defines the concepts of transducer and filter.  A transducer is a software entity (e.g. module or configuration) which implements a stream connected to a specific device or medium.  A filter also implements a stream, but only for the purpose of transforming, buffering, or otherwise manipulating the data before passing it on to another stream.  Transducers and filters may be provided either by the system or by clients.  Third, the stream package provides a standard way of concatenating a sequence of filters (usually terminated with a transducer) to form a compound stream called a pipeline.  A pipeline is accessed by means of the normal stream operations, and causes a sequence of separate transformations to be applied to data flowing between the client program at one end and the physical storage (or transmission) medium at the other.e12jk40\128i16I191f7b7f6 6f0B108i10I5i6I541i8I
The use of pipelines permits clients to interpose new stream manipulation programs (filters and transducers) between clients (producers and consumers of data) without modifying the interfaces seen by the clients.  For example, a data format conversion program can obtain its data either from a tape or from a disk, using the same stream interface, and hence the same program logic for both.  Similarly, filters performing such functions as code conversion, buffering, data conversion, encryption, etc. may be inserted into a pipeline without affecting the way the client sends and receives data through the stream interface.e12jk40
The stream facility transmits arbitrary data, regardless of format and without prejudice to its type or characteristics.  The data may comprise a sequence of bytes, words, or arbitrary Mesa data structures.  The stream facility does not presume or require the encoding of information according to any particular protocol or convention.  Instead, it permits clients to define their own protocols and standards according to their own needs.e12jk40
In this appendix, sections A.1, A.2, and A.3 will be of interest to all clients.  Section A.4 will be of interest only to those clients wishing to control the physical record characteristics of a particular stream.  Section A.5 will be of interest only to those clients wishing to implement their own filters or transducers.  In addition, the clients of a particular stream type (e.g. disk, tape, etc.) will normally have to consult separate documentation regarding the details of that kind of stream.e12jk40\27i3I2i3I6i3I46i3I131i3I
A.1 Semantics of Streamse24jk80\i
The stream facility supports transmission of a sequence of eight-bit bytes.  This sequence may be divided into identifiable subsequences, each of which has its own subsequence type.e12jk40\124i12I28i16I
Stream.Byte: TYPE = [0..255];l5248d4268x4e12k40(988)\f7b7f6 6f7 7f6 8f7 1f6
Stream.SubSequenceType: TYPE = [0..255];l5248d4268x4e12k40\f7b7f6 17f7 7f6 8f7 1f6
A subsequence may be null; i.e., it may be of zero length and contain no bytes but still contain the SubSequenceType information.  This information allows all subsequences to be easily identified and separated from each other while shielding clients from the bothersome problems of control-codes (i.e. embedding control-codes into the stream, making them transparent, and building a parser to implement such transparency).e12jk40(635)\101f6b15f0B
Additionally, an attention flag may be inserted into a stream sequence.  This is neither a byte nor a SubSequenceType, but simply an indication of an extraordinary situation.  Attention flags are transmitted through the stream as quickly as possible, possibly bypassing bytes and changes in SubSequenceType which were transmitted earlier but which are still in transit.  This provides a simple mechanism for implementing breaks (similar to the "attention-key" of many time-sharing systems).e12jk40\17i9I76f6b15f0B174f6b15f0B
Streams per se have no notion of a byte number (i.e. an array index); they deal only with the sequential order of successive bytes comprising the arbitrary binary data being transmitted.  The stream interface is thus unsuitable for applications requiring random access.e12jk40\8i7I
Streams have no intrinsic notion of the bytes passing through them being grouped into physical records.  The client program can completely ignore physical record structure and is thus relieved of the burden of dealing with the associated packing and unpacking problems.  If, however, it becomes necessary to control or determine the underlying physical record structure, as determined by the particular storage (or transmission) medium, the interface provides extended facilities which allow this.e12jk40
All of the procedures described here are synchronous and none returns until the indicated operation is complete.  That is, an input operation does not return until the data is actually available to the client, and an output operation does not return until the data has been accepted by the stream and client buffers may be reused.  Note, however, that a stream component may do internal buffering and that the acceptance of data means only that the stream component itself has a correct copy and is in a position to proceed asynchronously to write or send it.e12jk40\371i3I
Streams are inherently full-duplex -- i. e., separate processes may be transmitting and receiving simultaneously.  The stream interface does not guarantee mutual exclusion among different processes attempting to access the same stream.  However, individual transducers or filters may restrict themselves to half-duplex operation and/or may implement such mutual exclusion or more elaborate forms of synchronization as are appropriate.  Documentation for such filters and transducers should be consulted on a case-by-case basis for details.e12jk40\141i3I
A.2 Operations on Streamse24jk80\i
The stream interface provides the following information transmission operations: GetBlock, GetByte, GetChar, GetWord, PutBlock, PutByte, PutChar, PutWord, SendNow, SetSST, SendAttention, and WaitForAttention.e12jk40\81f6b8f0B2f6b7f0B1f6b8f0B2f6b7f0B2f6b8f0B2f6b7f0B2f6b7f0B2f6b7f0B2f6b7f0B2f6b6f0B2f6b13f0B6f6b16f0B
A client program identifies a particular instance of the stream interface by means of a Stream.Handle.e12jk40\88f7b7f6 6f0B
Stream.Handle: TYPE = . . . ;l5248d4268x4e12k40(988)\f7b7f6 8f7 14f6
A Handle identifies an object (see :A.5.1) which embodies all of the information concerning the transfer of data to and/or from the client program via stream operations.  It is passed as a parameter to each of the data transmission operations of the following sections to specify the stream to which the operations apply.e12jk40(635)\2f6b6f0B27f3 1f0i5I
A.2.1 GetBlock and PutBlocke24jk80\i6f6bI8f0Bi5f6bI8f0Bi
The principal operations for transferring blocks of data are Stream.GetBlock and Stream.PutBlock.  Each of these takes a parameter specifying the block of virtual memory to or from which bytes are to be transmitted.e12jk40\61f7b7f6 8f0B5f7b7f6 8f0B
Stream.Block: TYPE = RECORD [
blockPointer: LONG POINTER, 
startIndex, stopIndexPlusOne: CARDINAL];l5248d4268x4e12k40(988)\f7b7f6 7f7 14f6 16f7 15f6 10f7 2f6 18f7 8f6
A Block describes a section of memory which will be the source and/or sink of the bytes transmitted; the section of memory described is a sequence of bytes (not necessarily word aligned).  The blockPointer may be regarded as a base of a packed array of bytes; it selects a word such that a startIndex of zero would select the left byte of that word (i.e., bits 0 - 7).  The selected block consists of the bytes blockPointer^[i] for i in [startIndex..stopIndexPlusOne).  Notice that a Block cannot describe more than 216-1 bytes or 215-1 words.e12jk40(635)\2f6b5f0B186f6b12f0B85f6b10f0B111f6b14f0Bi1f6bI1f0B5i1I4f6b30f0B17f6b5f0B28f1o4 2f0o0 13f1o4 2f0o0
Note:	Some of the operations of this section and the next may cause signals to be generated.  If such a signal is RESUMEd, transmission continues where it left off -- i.e., any changes made by the catch phrase to the Block record and/or to the input options (see below) are ignored.  If, however, such a signal is RETRY'ed, the next byte of the stream sequence is transmitted to or from the byte specified by the current value of the Block record and/or input options, either of which might have been updated by the catch phrase.  In no case is the stream sequence itself "backed up."  That is, bytes previously received from input are not re-received, and bytes previously transmitted on output are not withdrawn.l4621d2999e12jk80(0,4608)\b5B109f7b6f0B97f6b5f0B92f7b5f0B115f6b5f0B275b
The primary input operation is Stream.GetBlock.e12jk40(635)\31f7b7f6 8f0B
Stream.GetBlock: PROCEDURE [sH: Stream.Handle, block: Stream.Block]
RETURNS [bytesTransferred: CARDINAL, why: Stream.CompletionCode,
sst: Stream.SubSequenceType];l5248d4268x4e12k40(988)\f7b7f6 10f7 10f6 5f7 7f6 15f7 7f6 7f7 8f6 19f7 8f6 7f7 7f6 21f7 7f6
Stream.CompletionCode: TYPE = {normal, endRecord, sstChange, endOfStream};l5248d4268x4e12k40\f7b7f6 16f7 4f6
The parameter block describes the memory area into which the bytes will be placed.  GetBlock does not return until the input is terminated.  Its exact behavior, however, is controlled by a set of input options which may be set by the client using the following operation:e12jk40(635)\14f6b5f0B65f6b8f0B
Stream.SetInputOptions: PROCEDURE [sH: Stream.Handle, options: Stream.InputOptions];l5248d4268x4e12k40(988)\f7b7f6 17f7 10f6 5f7 7f6 17f7 7f6 14f7
Stream.InputOptions: TYPE = RECORD [
terminateOnEndPhysicalRecord, signalLongBlock, signalShortBlock, signalSSTChange, signalEndOfStream: BOOLEAN];l5248d4268x4e12k40\f7b7f6 14f7 4f6 3f7 7f6 103f7 7f6
Stream.defaultInputOptions: Stream.InputOptions = [FALSE, FALSE, FALSE, FALSE, FALSE];l5248d4268x4e12k40\f7b7f6 21f7 7f6 16f7 5f6 2f7 5f6 2f7 5f6 2f7 5f6 2f7 5f6
SetInputOptions controls exactly how GetBlock terminates and what signals it generates.  Ordinarily (i.e., with the parameter options set to defaultInputOptions) the transmission will not terminate until the entire block of bytes is filled.  However, under exceptional conditions described in :A.4, the transmission may terminate before the block is filled and may also result in a signal.  In all cases the procedure will return the actual number of bytes transferred, a CompletionCode indicating the reason for termination, and the latest SubSequenceType encountered.  The input operation may conveniently be restarted where it left off by first adding the result bytesTransferred to block.startIndex to update the record describing the block of bytes.e12jk40(635)\f6b15f0B22f6b8f0B81f6b7f0B8f6b19f0B133f3 1f0i3I44f6b5f0B126f6b14f0B55f6b15f0B110f6b16f0B4f6b16f0B
Two circumstances which always suspend the transmission of data before the block is filled are (a) the detection of a change in SubSequenceType and (b) the endOfStream.  If the input option signalSSTChange is FALSE (the default case), then the procedure GetBlock terminates immediately and returns the number of bytes transferred, with why = sstChange, and sst set to the new value of the SubSequenceType.  If the input option signalSSTChange is TRUE, then the signale12jk40\24i6I45f6b5f0B48f6b16f0B12f6b11f0B23f6b15f0B4f7b5f0B40f6b8f0B74f6b3f0B3f6b9f0B6f6b3f0B29f6b15f0B23f6b15f0B4f7b4f0B
Stream.SSTChange: SIGNAL [sst: Stream.SubSequenceType, nextIndex: CARDINAL];l5248d4268x4e12k40(988)\f7b7f6 11f7 7f6 6f7 7f6 28f7 8f6
is generated.  The parameter sst specifies the new SubSequenceType, and the parameter nextIndex specifies the byte index within the block where the first byte of the new subsequence will be placed.  This signal may be resumed, and the effect is to continue the data transmission as though the change in SubSequenceType had not occurred (i.e., in the same block of bytes).e12jk40(635)\29f6b3f0B19f6b15f0B20f6b9f0B37f6b5f0B166f6b15f0B
Caution:	A catch phrase for this signal must not attempt any other stream operations using the same Stream.Handle, for this will corrupt the internal state information maintained for the stream.l4621d2999e12jk80(0,4608)\b8B92f7b7f6 6f0B
Implementation of the end-of-stream feature is strictly transducer and filter specific, and optional.  All transducers and filters need not implement this feature.  Transducer and filter implementors may implement an end-of-stream mechansim using any protocol they desire.  Typically, this feature would be implemented by exchanging subsequence types in some specific order.  If implementors use this mechansim, then they must document the subsequence types reserved for this, so that clients do not inadvertantly use the same ones for their own protocol.  When putting together a pipeline from  a transducer and filters, great care needs to be taken to preserve the end-of-stream feature through all the stream components.  If the input option signalEndOfStream is TRUE and the stream component detects that the end-of-stream has occured, then the signale12jk40(635)\131i8I606f6b17f0B4f7b4f0B
Stream.EndOfStream: SIGNAL [nextIndex: CARDINAL];l5248d4268x4e12k40(988)\f7b7f6 13f7 7f6 12f7 8f6
is generated.  The parameter nextIndex specifies the byte index immediately following the last byte of the stream sequence filled into a client's block.l3008d2999e12jk80(0,4608)\29f6b9f0B
Note:	Stream component implementors may provide special procudure calls in order to actively cause a stream to be terminated.l4621d2999e12jk80\b5B
The principal output operation is Stream.PutBlock.e12jk40(635)\34f7b7f6 8f0B
Stream.PutBlock: PROCEDURE [sH: Stream.Handle, block: Stream.Block, endPhysicalRecord: BOOLEAN];l5248d4268x4e12k40(988)\f7b7f6 10f7 10f6 5f7 7f6 15f7 7f6 26f7 7f6
This operation is analogous to Stream.GetBlock.  The parameter block describes the area of memory from which information is transmitted.  This procedure returns only after the data has been accepted by the stream, at which time the client may reuse the block.  If the client is ignoring physical record boundaries (the default case) then parameter endPhysicalRecord should be set to FALSE.  Otherwise, see :A.4.e12jk40(635)\31f7b7f6 8f0B17f6b5f0B185f6b5f0B90f6b17f0B18f7b5f0B18f3 1f0i3I
Note:	Stream operations have the right to discard empty blocks, hence a PutBlock operation specifying a block of length zero may be a no-op.l4621d2999e12jk80(0,4608)\b5B67f6b8f0B24f6b5f0B
A.2.2 Additional Data Transmission Operationse24jk80(635)\i
In addition to GetBlock and PutBlock, the following operations are provided:e12jk40\15f6b8f0B5f6b8f0B
Stream.GetByte: PROCEDURE [sH: Stream.Handle] RETURNS [byte: Stream.Byte];l5248d4268x4e12k40(988)\f7b7f6 9f7 10f6 5f7 7f6 8f7 8f6 7f7 7f6
Stream.GetChar: PROCEDURE [sH: Stream.Handle] RETURNS [char: CHARACTER];l5248d4268x4e12k40\f7b7f6 9f7 10f6 5f7 7f6 8f7 8f6 7f7 9f6
Stream.GetWord: PROCEDURE [sH: Stream.Handle]
RETURNS [word: Stream.Word];l5248d4268x4e12k40\f7b7f6 9f7 10f6 5f7 7f6 7f7 9f6 7f7 7f6
Stream.Word: TYPE = [0..65535];l5248d4268x4e12k40\f7b7f6 6f7 5f6
GetByte and GetChar operations get the next Byte or CHARACTER from the stream sequence and return it.  They are equivalent to a call upon Stream.GetBlock, specifying a Block containing one byte.  The GetWord operation gets the next Word from the stream sequence and returns it.  It is equivalent to a call upon Stream.GetBlock, specifying a Block containing AltoDefs.BytesPerWord bytes.    Input options are assumed to be signalShortBlock, signalLongBlock, and endPhysicalRecord = FALSE, and signalEndOfStream and signalSSTChange = TRUE.  Thus, these operations may result in signal SSTChange or EndOfStream.e12jk40(635)\f6b7f0B5f6b7f0B25f6b5f0B2f6b1f7 9f0B77f7b7f6 8f0B15f6b5f0B27f6b8f0B24f6b4f0B75f7b7f6 8f0B15f6b5f0B12f7b9f6 12f0B43f6b16f0B2f6b15f0B6f6b17f0B3f7b5f0B6f6b18f0B3f6b16f0B3f7b4f0B47f6b10f0B2f6b12f0B
Note:	When the SIGNALs SSTChange or EndOfStream are generated, nextIndex should be equal to 0.  In the case of GetWord if nextIndex = 1, the caller is responsible for processing the "half-word".l4621d2999e12jk80(0,4608)\b5B10f7b6f0B2f6b10f0B2f6b12f0B16f6b9f0B39f6b7f0B4f6b9f0B
Stream.PutByte: PROCEDURE [sH: Stream.Handle, byte: Stream.Byte];l5248d4268x4e12k40(988)\f7b7f6 9f7 10f6 5f7 7f6 14f7 7f6
Stream.PutChar: PROCEDURE [sH: Stream.Handle, char: CHARACTER];l5248d4268x4e12k40\f7b7f6 9f7 10f6 5f7 7f6 14f7 9f6
Stream.PutWord: PROCEDURE [sH: Stream.Handle, word: Stream.Word];l5248d4268x4e12k40\f7b7f6 9f7 10f6 5f7 7f6 14f7 7f6
The PutByte and PutChar operations transmit the next Byte or CHARACTER to the medium.  They are equivalent to a call on Stream.PutBlock, specifying a Block containing one byte.  The PutWord operation transmits the next Word to the medium.  This procedure is equivalent to call on Stream.PutBlock, specifying a Block containing AltoDefs.BytesPerWord bytes. These output operations specify endPhysicalRecord = FALSE.e12jk40(635)\4f6b7f0B5f6b7f0B30f6b5f0B2f6b1f7 9f0B50f7b7f6 8f0B15f6b5f0B27f6b7f0B30f6b4f0B57f7b7f6 8f0B15f6b5f0B12f7b9f6 12f0B40f6b17f0B3f7b5f0B
Stream.SendNow: PROCEDURE [sH: Stream.Handle];l5248d4268x4e12k40(988)\f7b7f6 9f7 10f6 5f7 7f6
This operation flushes the stream sequence; it guarantees that all information previously output (by means of PutBlock, PutByte, PutChar,  PutWord or SetSST) will actually be transmitted to the medium (perhaps asynchronously).  This procedure is equivalent to a call on Stream.PutBlock, specifying a Block containing no bytes and endPhysicalRecord = TRUE (see :A.4).  Client programs which are not concerned with physical record boundaries should nevertheless call SendNow at appropriate times to ensure that the bytes and changes in SubSequenceType have actually been sent and are not buffered internally within the stream, awaiting additional output operations.e12jk40(635)\110f6b8f0B2f6b7f0B1f6b9f0B2f6b7f0B4f6b6f0B114f7b7f6 8f0B15f6b5f0B25f6b17f0B3f7b4f0B6f3 1f0i3I101f6b7f0B62f6b15f0B
Stream.SetSST: PROCEDURE [
sH: Stream.Handle, sst: Stream.SubSequenceType];l5248d4268x4e12k40(988)\f7b7f6 8f7 10f6 6f7 7f6 13f7 7f6
This operation causes all subsequent bytes to have the indicated SubSequenceType.  Even if the subsequent sequence of bytes is null (i.e., a call on SetSST is immediately followed by another), the SubSequenceType change demanded by this call will still be available to the receiver of the stream sequence.e12jk40(635)\65f6b15f0B69f6b6f0B42f6b15f0B
Note:	SubSequenceTypes are intended to be used to delineate different kinds of information flowing over the same stream (e.g. to identify control information, indicate end-of-file, etc.)  The interpretation of a SubSequenceType value is a function of the particular stream.l4621d2999e12jk80(0,4608)\b5B1f6b15f0B191f6b15f0B
Note:	A SetSST operation specifying a SubSequenceType identical to the previous SubSequenceType is a no-op.  Otherwise, SetSST always has the side effect of completing the current physical record, as explained in :A.4.l4621d2999e12jk80\b5B3f6b6f0B24f6b15f0B27f6b15f0B25f6b6f0B1i6I80f3 1f0i3I
A.2.3  Attention Flagse24(635)\i
The following operation causes an attention flag and an associated byte of data to be transmitted via the stream facility.e12j
Stream.SendAttention: PROCEDURE [sH: Stream.Handle, byte:Stream.Byte];l5248d4268x4e12(988)\f7b6f6 16f7 10f6 5f7 6f6 14f7 7f6
Note that neither the attention flag nor the data byte occupy a byte in the stream sequence.  They are out of band signals.  Note also that an attention is not necessarily transmitted in sequence, but may bypass bytes and changes in SubSequenceType which were transmitted before it.e12j(635)\233f6b15f0B
Note:	This operation may have the side effect of completing the current physical record, as explained in :A.4.  A client process will typically follow the SendAttention by a change in SubSequenceType or some recognizable pattern of bytes.  This permits the recipient to identify where the SendAttention occurred.l4621d2999e12j(0,4608)\b5B100f3 1f0i3I46f6b13f0B16f6b15f0B90f6b13f0B
Note:	byte may be used by the client protocol to transmit other information regarding this attention.l4621d2999e12j\b5B1f6b4f0B
The following operation awaits the arrival of an attention flag.e12j(635)
Stream.WaitForAttention: PROCEDURE [sH: Stream.Handle] RETURNS [Stream.Byte];l5248d4268x4e12(988)\f7b6f6 19f7 10f6 5f7 6f6 9f7 8f6 1f7 6f6
When an attention is received on the stream sH, this procedure returns the byte of data associated with the attention.  It is the responsibility of the client program to determine the appropriate action to take.  If more than one attention flag has been sent, these will be queued by the stream.  Each return from a call on WaitForAttention corresponds to precisely one attention sent by SendAttention.e12j(635)\44f6b2f0B278f6b16f0B48f6b13f0 1B
Note:	This operation is usually executed by a different process from that operating upon the stream.  It returns as soon as the attention is received, whether or not all of the bytes preceding it in the stream have been transferred.l4621d2999e12j(0,4608)\b5B
A.2.4 Timeoutse24jk80(635)\i
Any of the operations of this section (except SendAttention and WaitForAttention) may fail to complete within a reasonable amount of time due to external conditions.  For example, a stream operation on a Pup stream may fail because the process at the other end has terminated, aborted, or ceased to pay attention.  In such a case the following signal is generated:e12jk40\46f6b13f0B5f6b16f0B
Stream.TimeOut: SIGNAL [nextIndex: CARDINAL];l5248d4268x4e12k40(988)\f7b7f6 9f7 7f6 12f7 8f6
The parameter of this signal indicates the position within the block of bytes where the next byte would be placed.  This signal may be resumed.e12jk40(635)
Note:	If this signal is RETRY'ed all previously received data may be lost.  This is because it is likely that a stream component is performing internal bufferring (transferring data from its buffer into the client's block), and the action of RETRYing the SIGNAL may not tell the component that it must refill the client's block.  Even if the component was informed of this fact, it may have discarded data already transferred into the client's block from its internal bufferl4621d2999e12jk80(0,4608)\b5B19f7b5f0B213f7b5f0B8f7b6f0B
Caution:	A catch phrase for this signal must not attempt any other stream operations using the same Stream.Handle, for this will corrupt the internal state information maintained for the stream.l4621d2999e12jk80\b8B92f7b7f6 6f0B
A.3 Creating and Deleting Streamse24jk80(635)\i
There are no general operations for creating streams.  The reason for this is that the components of a stream -- i.e., pipelines, transducers, and filters -- must be able to take arbitrary parameters at the time they are created.  It is not possible for the system to specify a general interface for their creation without either compromising the basic typesafeness of Mesa or constraining the flexibility and power of client-provided streams.  Thus, the create function is implemented on a case-by-case basis, and clients must therefore refer to documentation for individual stream components for the correct interface for this operation.  In this section, the general style is illustrated by means of a hypothetical example.e12jk40
For example, if a utility package implements a transducer to a particular device, it is obligated to provide a means by which other clients can create instances of that transducer, use them, and later delete them.  Suppose the name of the interface module providing this function is DeviceStream.  Then it would provide the following operation:e12jk40\283f6b12f0B
DeviceStream.Create: PROCEDURE [ --optional parameters-- ]
RETURNS [Stream.Handle, --optional other results--];l5248d4268x4e12k40(988)\f6b21f7 10f6 28f7 8f6 1f7 7f6 36f7
A client wishing to use the stream interface to access this device would thus call DeviceStream.Create, then use the Stream.Handle returned from it as a parameter to the stream operations of this chapter.e12jk40(635)\83f6b19f0B15f7b7f6 6f0B
Similarly, a security package providing, say, an encryption facility might implement this by means of a filter for a stream.  In this case, the interface might be called EncryptionFilter, and it would provide the following operation:e12jk40\170f6b16f0B
EncryptionFilter.Create: PROCEDURE [Stream.Handle, --optional other parameters-- ] RETURNS [Stream.Handle, --optional other results--];l5248d4268x4e12k40(988)\f6b25f7 10f6 1f7 7f6 40f7 8f6 1f7 7f6 36f7
The client could easily couple an instance of this filter with the transducer above.  This is done by calling EncryptionFilter.Create, passing as a parameter the Stream.Handle returned from DeviceStream.Create.  Then the Stream.Handle returned from EncryptionFilter.Create would be the one used in GetBlock, PutBlock, and the other operations of :A.2.  The net effect would be stream components which, on input, read bytes from the device, decrypt them, and pass them to the client and which, on output, encrypt the bytes supplied by the client and write them on the device.e12jk40(635)\110f6b23f0B29f7b7f6 6f0B15f6b19f0B12f7b7f6 6f0B15f6b23f0B26f6b8f0B2f6b8f0B30f3 1f0i3I
In general, creating a filter accepts one Stream.Handle as a parameter and returns another as its result.  Thus, several filters, each implementing a simple transformation, may be concatenated together to implement a more interesting transformation on the stream.  The parameter passed to each one is the result returned from the adjacent one.  Such a concatenation, called a pipeline, is illustrated in Figure A.1.e12jk40\42f7b7f6 6f0B321i8I
<==<PupStreamsFig1.Press<e24jk216
Figure A.1e72ck40\f6b10f0B
This diagram illustrates how each Stream.Handle returned from a transducer or filter is passed as parameter to the next adjacent filter, and how the last one is used directly by the client.  In particular, h1 is returned from the procedure which creates Transducer; it is passed to the procedure which creates Filter B, returning h2.  This is passed, in turn, to the next filter, and so on, until hn is returned and passed to Filter A.  Filter A is the last one in the pipeline, and its Stream.Handle, h, is returned to the client.e12jk40\34f7b7f6 6f0B159f6b2f0B46f6b10f0B46f6b8f0B12f6b2f0B65f6b2f0B27f6b8f0B3f6b8f0B42f7b7f6 6f0B2f6b1f0B
Figure A.2 shows the flow of data through the pipeline and the use of the various Stream.Handles as a result of a client call on Stream.GetBlock (calls on other data transmission operations are analogous).e12jk40\82f7b7f6 6f0B34f7b7f6 8f0B
<==<PupStreamsFig2.Press<e24jk216
Figure A.2e72ck40\f6b10f0B
Here, the client calls Stream.GetBlock[h, . . . ], which is transformed by the stream interface into an appropriate call on Filter A.  Filter A, in turn, calls Stream.GetBlock[hn, . . . ], which is passed to the next filter in the pipeline, and so on, until eventually a call is made on Stream.GetBlock[h2, . . . ].  This is transformed into a call on Filter B, which then calls Stream.GetBlock[h1, . . . ], to invoke Transducer, which actually operates the device.e12jk40\23f7b7f6 19f0B75f6b8f0B3f6b8f0B17f7b7f6 20f0B100f7b7f6 20f0B38f6b8f0B19f7b7f6 20f0B12f6b10f0B
Note that the only difference between a transducer and a filter is that a transducer interfaces to some device, while a filter interfaces to another stream -- i.e., indirectly to another filter or transducer.e12jk40
Note also that the client can construct a pipeline "manually," by tediously assembling the various components, instantiating each of them, and binding them together.  However, a pipeline can also be presented as an integrated package, already assembled.  For example, the two components described above may have been assembled into a pipeline called EncryptingDeviceStream.  This pipeline might then provide the following two operations, which clients can call to create and delete an instance of this pipeline:e12jk40\350f6b22f0B
EncryptingDeviceStream.Create: PROCEDURE [ --optional parameters-- ]
RETURNS [Stream.Handle, --optional other results--];l5248d4268x4e12k40(988)\f6b31f7 10f6 28f7 8f6 1f7 7f6 36f7
EncryptingDeviceStream.Delete: PROCEDURE [Stream.Handle, --optional other parameters-- ] RETURNS [ --optional results-- ];l5248d4268x4e12k40\f6b31f7 10f6 1f7 7f6 40f7 8f6 25f7
The client of such a stream would merely invoke these procedures to create and destroy the stream without having to bother about finding and putting together the individual components.e12jk40(635)
A.4 Control over Physical Record Characteristicse24jk80\i
Most of the time, the client will not wish to know about how the data comprising a stream sequence is divided into physical records for recording or transmission.  For some applications, however, this is of vital importance.  The stream facility has been designed so that the details of the physical encoding can be ignored when desired, or completely known and controlled when that is necessary.  On output, complete control of the placement of bytes in physical records can be achieved for most media.  On input, complete information is available about how the bytes were arranged in physical records.e12jk40
Note:	These facilities to control the placement of bytes on physical records are not meant to be used as a means of transmitting information.  In particular, a transducer might suppress or generate empty physical records and will necessarily partition oversize "physical" records into smaller ones.  Any filter may rearrange (or completely obliterate) physical record boundaries.  Documentation for the individual transducer or filter and for the individual transmission or storage medium should be consulted for full details.l4621d2999e12jk80(0,4608)\b5B76i3I
The output and input cases will be treated separately.  On output, bytes will be placed in turn into the same physical record until one of the following events occurs:e12jk40(635)
1)  The SendNow procedure is called; it has the side effect of causing the current record to be sent.  The next byte output will begin a new physical record.  Thus, this is the main mechanism for controlling physical record size on output.l4269e12jk40\7b1f6 7f0B
2)  A PutBlock procedure is called with an endPhysicalRecord parameter of TRUE.  After the transmission of this block of bytes, the current physical record is ended.  If, at this point, the physical record is at its maximum size (see (4) below), an empty record will not be transferred.l4269e12jk40\6f6b8f0B29f6b17f0 1B12b1f7 4f0B189i3I
3)  A SetSST procedure has been called.  The first byte of a new subsequence always begins a new record and has the new SubSequenceType.  This may cause the previous record to be sent.l4269e12jk40\6f6b6f0B108f6b15f0B
4)  Enough bytes have been output to fill the physically maximal record.  At this point the record will be written and a new record started.  This maximum number is a function of the medium being written, hence documentation concerning the medium must be consulted to determine this value.l4269e12jk40
5) Some other device-dependent event, such as a timeout, occurs.  In this case, a buffer may be flushed automatically.  Details are documented with individual transducers.l4269e12jk40
On input, bytes will be placed in turn into the record until one of the following events occurs:e12jk40
1) The end of the physical record is reached, the block of bytes described in the Block record is not exhausted, and either of the input options endPhysicalRecord  or signalLongBlock is TRUE.l4269e12jk40\82f6b5f0B58f6b18f0B4f6b15f0B4f7b4f0 1B
If signalLongBlock is TRUE, the following signal is generated:l4269e12jk40\3f6b15f0B4f7b4f0B
Stream.LongBlock: SIGNAL [nextIndex: CARDINAL];l6518d5538x4e6k40(988)\f7b7f6 11f7 7f6 12f7 8f6
This signal indicates in nextIndex the position within the block of bytes where the next byte will be placed.  If it is resumed, transmission continues as if it had not been generated.l4269e12jk40(635)\25f6b9f0B
Caution:	A catch phrase for this signal must not attempt any other stream operations using the same Stream.Handle, for this will corrupt the internal state information maintained for the stream.l5891d4269e12jk80(0,5888)\b8B92f7b7f6 6f0B
If endPhysicalRecord is TRUE, the input is terminated, indicating the number of bytes transferred and why = endPhysicalRecord.  This applies whether or not a signal was generated.l4269e12jk40(635)\3f6b17f0B4f7b4f0B74f6b3f0 3f6 17f0B
2)  The end of the physical record is reached at the same time that the block of bytes is exhausted.  In this case, no signal is generated.  If the input option endPhysicalRecord is TRUE, then why is set to endPhysicalRecord; otherwise, it is set to normal.l4269e12jk40\161f6b17f0B4f7b4f0B7f6b3f0B11f6b17f0B26f6b6f0B
3)  The block of bytes is exhausted, the end of the physical record has not been reached, and the input option signalShortBlock has the value TRUE.  At this time the input is terminated (without losing the subsequent bytes of the physical record, which are still available for reading by subsequent GetBlock), and the signal Stream.ShortBlock is generated.l4269e12jk40\111f6b16f0B15f7b4f0B153f6b8f0B18f7b7f6 10f0B
Stream.ShortBlock: ERROR;l6518d5538x4e6k40(988)\f7b7f6 12f7 5f6
This signal may not be resumed.l4269e12jk40(635)
The easiest approach is usually to establish a Block longer than the longest expected physical record and specify input options signalLongBlock = FALSE, signalShortBlock = TRUE and endPhysicalRecord = TRUE.  At this point the transmission will cease with the  entire contents of the physical record in the block of bytes, and the number of bytes transmitted will be returned as the result of the GetBlock procedure.  In this way a signal will be generated only under unusual circumstances.e12jk40\47f6b5f0B76f6b15f0 3f7 5f0B2f6b16f0B1b2f7 4f0 1B3b1f6 17f0B3f7b4f0 1B190f6b8f0B
A.5 Transducers, Filters, and Pipelinese24jk80\i
The stream package is designed so that clients can implement their own stream components -- i.e., their own transducers, filters, and pipelines.  The implementor of one of these has three different obligations to fulfill.  First, he must design an interface (i.e., Mesa DEFINITIONS module) in the style described in :A.3, by which his clients create instances of that stream component.  Such an interface (together with its accompanying implementation modules) is called a stream component manager.  Second, he must provide a functional specification describing this interface and the detailed behavior of the stream component, including any specific signals, errors, parameters, etc., which it defines.  Third, he must implement the actual component, if it is a filter or transducer.  (Pipelines are assumed to be composed of previously implemented components which already have their own component managers and documentation.)e12jk40\270f7b11f0B35f3 1f0i3I153i24I
This section describes the standards, data types, and operations to be used in defining a new stream component.  In :A.5.1, the precise interface which each instance of each filter or transducer must provide is specified.  In :A.5.2, a typical method for implementing a filter or transducer manager is outlined.e12jk40\116f3 1f0i5I104f3 1f0i5I
A.5.1 Representing Filters and Transducerse24jk80\i
At run time, a filter or transducer is represented by six procedures which execute in a common context to provide the data transmission operations of the that filter or transducer.  Descriptors for these procedures are stored in a record defined by the stream package, pointed to by a Stream.Handle.e12jk40\285f7b7f6 6f0B
Stream.Handle: TYPE = POINTER TO Stream.Object;l5248d4268x4e12k40(988)\f7b7f6 8f7 4f6 3f7 18f6 6f7 1f6
Stream.Object: TYPE = RECORD [
options: Stream.InputOptions,
get: Stream.GetProcedure,
put: Stream.PutProcedure,
setSST: Stream.SetSSTProcedure,
sendAttention: Stream.SendAttentionProcedure,
waitAttention: Stream.WaitAttentionProcedure,
delete: Stream.DeleteProcedure];l5248d4268x4e12k40\f7b7f6 8f7 4f6 3f7 7f6 11f7 7f6 19f7 7f6 19f7 7f6 22f7 7f6 32f7 7f6 39f7 7f6 32f7 7f6
A client call on a stream operation is normally converted by the stream package into a call on the appropriate procedure named in the Stream.Object pointed to by the Stream.Handle parameter of that operation.  Thus, it is the responsibility of the implementor of each filter and transducer to exactly satisfy the specifications of the stream package.  The stream package assists in this task by utilizing the Mesa typechecking machinery and by defining the uniform interface encapsulated by Stream.Object.e12jk40(635)\134f7b7f6 6f0B19f7b7f6 6f0B312f7b7f6 6f0B
In this section, the meanings of the fields of Stream.Object are enumerated.e12jk40\47f7b7f6 6f0B
The options field specifies the currently valid input options for the stream.e12jk40\4f6b7f0B
options: Stream.InputOptions,l5248d4268x4e12k40(988)\f6b9f7 7f6
This field is set by Stream.SetInputOptions and its current value is passed as a parameter to the get procedure described below.  Implementors of filters and transducers need not be concerned with maintaining or inspecting this field.e12jk40(635)\21f7b7f6 15f0B55f6b3f0B
The get field specifies the input procedure of the transducer or filter.e12jk40\4f6b3f0B
get: Stream.GetProcedure,l5248d4268x4e12k40(988)\f6b5f7 7f6
Stream.GetProcedure: TYPE = PROCEDURE [
sH: Stream.Handle, block: Stream.Block, options: Stream.InputOptions]
RETURNS [bytesTransferred: CARDINAL,
why: Stream.CompletionCode, sst: Stream.SubSequenceType];l5248d4268x4e12k40\f7b7f6 14f7 4f6 3f7 10f6 6f7 7f6 15f7 7f6 16f7 7f6 14f7 8f6 19f7 8f6 7f7 7f6 21f7 7f6
This procedure is called by GetBlock, GetByte, GetChar, and GetWord.  It must implement the semantics of GetBlock as described in :A.2.1 and  :A.4.  In particular, it must terminate according to the specifications of that section and must generate the signals SSTChange, LongBlock, ShortBlock, EndOfStream, and TimeOut (:A.2.4) as required.e12jk40(635)\28f6b27f0B5f6b7f0B38f6b8f0B17f3 1f0i5I6f3 1f0i3I114f6b9f0B2f6b9f0B2f6b10f0B2f6b11f0B6f6b7f0B2f3 1f0i5I
Note:	In a filter, the body of a GetProcedure will typically contain one or more calls on GetBlock, GetByte, GetChar, or GetWord with a Stream.Handle parameter pointing to the next stream component in the pipeline (i.e., the parameter passed at the time this filter was created).  In a transducer, the body of a GetProcedure will typically have calls on input operations for the specific device being supported.l4621d2999e12jk80(0,4608)\b5B28f6b12f0B45f6b27f0B4f6b7f0B8f7b7f6 6f0B163f6b12f0B
The put field specifies the output procedure provided by the filter or transducer.e12jk40(635)\4f6b3f0B
put: Stream.PutProcedure,l5248d4268x4e12k40(988)\f6b5f7 7f6
Stream.PutProcedure: TYPE = PROCEDURE [
sH: Stream.Handle, block: Stream.Block, endPhysicalRecord: BOOLEAN];l5248d4268x4e12k40\f7b7f6 14f7 4f6 3f7 10f6 6f7 7f6 15f7 7f6 26f7 7f6
This procedure is called by PutBlock, PutByte, PutChar, PutWord, and SendNow.  It must implement the semantics of PutBlock as described in :A.2.1 and  :A.4.  In particular, it must regard the parameter endPhysicalRecord = TRUE as an indication to flush any output buffers and actually initiate the physical transmission of information.  It may suppress output requests specifying a block of no bytes provided that there is no previous output, change in SubSequenceType, or attention flag still waiting to be sent.  This procedure may generate the signal TimeOut if necessary.e12jk40(635)\28f6b8f0B2f6b7f0B2f6b7f0B2f6b7f0B6f6b7f0B38f6b8f0B17f3 1f0i5I6f3 1f0i3I47f6b20f7 4f0B227f6b15f0B86f6b7f0B
Note:	In a filter, the body of a PutProcedure will typically contain one or more calls on PutBlock, PutByte, PutChar, PutWord, or SendNow with a Stream.Handle parameter pointing to the next stream component in the pipeline (i.e., the parameter passed at the time this filter was created).  In a transducer, the body of a PutProcedure will typically have calls on output operations for the specific device being supported.l4621d2999e12jk80(0,4608)\b5B28f6b12f0B45f6b8f0B2f6b7f0B2f6b7f0B2f6b7f0B5f6b7f0B8f7b7f6 6f0B163f6b12f0B
The setSST field specifies the procedure to change the current SubSequenceType of the output side of the filter or transducer.e12jk40(635)\4f6b6f0B53f6b15f0B
setSST: Stream.SetSSTProcedure,l5248d4268x4e12k40(988)\f6b8f7 7f6
Stream.SetSSTProcedure: TYPE = PROCEDURE [
sH: Stream.Handle, sst: Stream.SubSequenceType];l5248d4268x4e12k40\f7b7f6 17f7 4f6 3f7 10f6 6f7 7f6 13f7 7f6
This procedure is called by Stream.SetSST and must conform to the semantics of that operation as described in :A.2.2.  In particular, it should be a no-op if the new SubSequenceType is the same as the old one.  Otherwise, it should have the effect of completing the current physical record (as if a call on Stream.SendNow had been made immediately before).e12jk40(635)\28f7b7f6 6f0B69f3 1f0i5I50f6b15f0B126f7b7f6 7f0B
Note:	A call on setSST may have the effect of changing the internal state of the stream component, or in the case of a filter, it may result in a call to SetSST to the next stream component in the pipeline, or both.l4621d2999e12jk80(0,4608)\b5B11f6b6f0B132f6b6f0B
The sendAttention and waitAttention fields specify the two procedures implementing the sending of and waiting for attention flags in the transducer or filter.e12jk40(635)\4f6b13f0B5f6b13f0B
sendAttention: Stream.SendAttentionProcedure,
waitAttention: Stream.WaitAttentionProcedure,l4256d4268x4e12k40(988)\f6b15f7 7f6 39f7 7f6
Stream.SendAttentionProcedure: TYPE = PROCEDURE [
sH: Stream.Handle, byte: Stream.Byte];l5248d4268x4e12k40\f7b7f6 24f7 4f6 3f7 9f6 7f7 7f6 14f7 7f6
Stream.WaitAttentionProcedure: TYPE = PROCEDURE [sH: Stream.Handle]
RETURNS [Byte: Stream.Byte];l5248d4268x4e12k40\f7b7f6 24f7 4f6 3f7 9f6 6f7 7f6 8f7 7f6 8f7 7f6
These two procedures will be called by Stream.SendAttention and Stream.WaitForAttention, respectively, and they must conform to the semantics of those operations as specified in :A.2.3.e12jk40(635)\39f7b7f6 13f0B5f7b7f6 16f0B91f3 1f0i5I
Note:	In a filter, it is not always necessary to implement these two procedures (or any others of this section) if all they do is call the corresponding operation in the next stream component in the pipeline.  Instead, it is satisfactory to copy the procedure descriptor from one Stream.Object to the other.  This has the effect of making the call pass "straight through" the filter with no overhead.l4621d2999e12jk80(0,4608)\b5B275f7b7f6 6f0B
The delete field specifies a procedure to be used during deletion of a filter or transducer.e12jk40(635)\4f6b6f0B
delete: Stream.DeleteProcedure,l5248d4268x4e12k40(988)\f6b8f7 7f6
Stream.DeleteProcedure: TYPE = PROCEDURE [sH: Stream.Handle];l5248d4268x4e12k40\f7b7f6 17f7 4f6 3f7 10f6 5f7 7f6
This procedure provides a convenient way of deleting an instance of a transducer or filter once it is no longer needed; an example of its use is given in the next section.  The parameter sH is provided for convenience and may be used for whatever purpose is useful.e12jk40(635)\187f6b2f0B
A.5.2 Stream Component Managerse24jk80\i
Implementors of stream components may create instances of them by whatever means is most appropriate to their requirements.  A particular filter or transducer may, for example, consist of one module, a collection of modules, a local frame used in conjuction with the Mesa PORT facility, or some other construct.  Moreover, it may exist on a given machine in only one or a limited number of copies which are regarded as "serially reusable" resources (for example, a transducer to a particular device, of which there is only one or a limited number on a machine), or it may exist in as many copies as appropriate.  It is the responsibility of the stream component manager to create (or control access to) instances of that stream component, as appropriate.  When access is granted, the component manager must also provide a pointer to a Stream.Object containing procedure descriptors for that component.e12jk40\272f7b4f0B559f7b7f6 6f0B
The typical way of implementing a component is as a single module which is instantiated at run-time by the Mesa NEW statement.  Declared within this module would be the procedures of the component plus a Stream.Object containing their procedure descriptors.  The component manager executes NEW to create a new instance of the stream, followed by START to initialize it (possibly passing parameters) and to obtain a pointer to its Stream.Object.e12jk40\112f7b3f0B89f7b7f6 6f0B73f7b3f0B53f7b5f0B79f7b7f6 6f0B
The component manager deletes instances of stream components by calling FrameDefs.UnNew or FrameDefs.SelfDestruct.e12jk40\72f7b10f6 5f0B4f7b10f6 12f0B
FrameDefs.UnNew (the inverse of NEW) takes a GlobalFrameHandle as its parameter.  Component managers can determine the value of this parameter by calling FrameDefs.GlobalFrame, which takes a procedure descriptor of a procedure residing in the component to be deleted as a parameter, and returns a pointer to its global frame.  FrameDefs.UnNew frees space occupied by the component's global frame.e12jk40\f7b10f6 5f0B17f7b3f0B10f6b17f0B92f7b10f6 11f0B152f7b10f6 5f0B
Caution:	The client must ensure that there are no outstanding references to the component module being deleted -- i.e., no procedure descriptors or pointers which might be used.  In addition, any process waiting for attentions (i. e., a process which has called but not returned from WaitForAttention) must be aborted and allowed to exit from the module.  Failure to observe this caution will result in unpredictable effects.  In particular, FrameDefs.UnNew must be called from outside the module being deleted.l4621d2999e12jk80(0,4608)\b8B276f6b16f0B142f7b10f6 5f0B1i27I
FrameDefs.SelfDestruct sets the internal state of the process so that the module in which the calling procedure is declared will be unnewed after the calling procedure returns to its caller.e12jk40(635)\f7b10f6 12f0B118i5I
This operation has the effect of placing a "self-destruct" mechanism in the module which will take effect after the calling process exits from it.  Thus, it is a means of deleting the stream component from within that component.e12jk40\206i6I
Caution:	As above, the client must ensure that there are no references to the module currently in use by any process.l4621d2999e12jk80(0,4608)\b8B
The typical use of FrameDefs.SelfDestruct will be from a procedure named in the delete entry of the Stream.Object.  The component manager will call h.delete[h] (where h is a Stream.Handle).  This procedure will perform the necessary finalization, such as flushing buffers, closing files or connections, releasing storage and resources, etc.  It will then call FrameDefs.SelfDestruct and finally return to the component manager.  After this return, the module representing this instance of the stream component will be deleted and space occupied by the stream's global frame will be freed.e12jk40(635)\19f7b10f6 12f0B39f6b6f0B14f7b7f6 6f0B35f6b11f0B8f6b1f0B6f7b7f6 6f0B173f7b10f6 12f0B