Heading:qk40(635)
Mesa FTP Functional Specificationy756qk40\b33B
Page Numbers: Yes  X: 527  Y: 10.5"  First Page: 56qk40
Appendix G:  Client Communication Primitivesx4e24k792\f5b44B
G.1.  Description of the Optionx4e12k54\b31B
An FTP User, Server, or Listener manipulates its local communication system by means of a family of procedures called communication primitives.  This family includes, for example, procedures for opening and closing network connections, for activating and deactivating network ports (well-known sockets), and for sending and receiving data.  The FTP implementation includes a set of primitives for manipulating the standard Pup communication system.x4e12jk54\118i27I194i2I
Rather than use the communication system offered by FTP, the client may, if it wishes, provide its own communication primitives to a particular FTP User or Listener.  By so doing, a client can use FTP to, for example:x4e12jk54
1. interface to another local communication system.l4269d3740x4e12k54
2. transform host names (for example, convert abstract host names to concrete ones).l4269d3740x4e6k54
3. control access to particular functions on a per-host basis.l4269d3740x4e6k54
4. maintain a log of communication system activity.l4269d3740x4e6k54
The client can also implement certain communication primitives while relying on FTP for others, or use the FTP implementations as building blocks for its own implementations.  For example, a client could log incoming requests for connection by supplying an implementation of the ActivatePort procedure (described in Section G.5) that calls FTP's ActivatePort procedure to actually activate the port.x4e12jk54\279f6b12f0B55f6b12f0B
G.2.  Exercising the Optionx4e12k54\b27B
The client exercises the option described above by means of the communicationPrimitives parameter required by both the FTPCreateUser and FTPCreateListener procedures.  This parameter is a POINTER to a RECORD containing the PROCEDUREs by which the newly created FTP User or Listener (and any Servers it may create) are to access the local communication system.  The client may supply its own version of this record, rather than rely upon either of the standard versions offered by FTP.  In constructing the record and/or implementing the procedures it contains, the client may draw upon any of the communication primitives it finds in the FTP-provided records.  Since FTP will not copy the record presented to it, the client must preserve it intact until FTPDestroyUser or FTPDestroyListener is called: x4e12jk54\64f6b23f0B32f6b13f0B5f6b17f0B34f1 7f0 6f1 6f0 16f1 11f0 520f6b14f0B4f6b18f0B
CommunicationPrimitives: TYPE = POINTER TO CommunicationPrimitivesObject;l4269d3740e12\f6b25f1 4f6 3f1 10f6
CommunicationPrimitivesObject: TYPE = RECORD [l4269d3740\f6b31f1 4f6 3f1 6f6
    -- program management primitivesl4269d3740e12\i
  CreateCommunicationSystem: PROCEDURE RETURNS [communicationSystem: CommunicationSystem],l4269d3740\f6b29f1 9f6 1f1 7f6
  DestroyCommunicationSystem: PROCEDURE [communicationSystem: CommunicationSystem],l4269d3740\f6b30f1 9f6
    -- connection management primitivesl4269d3740e12k792\i
  OpenConnection: PROCEDURE [communicationSystem: CommunicationSystem, remoteHost: STRING, remoteSocket: LONG CARDINAL, receiveSeconds: CARDINAL] RETURNS [connection: Connection],l4269d3740\f6b18f1 9f6 56f1 6f6 16f1 13f6 18f1 8f6 2f1 7f6
  CloseConnection: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection],l4269d3740\f6b19f1 9f6
  ActivatePort: PROCEDURE [communicationSystem: CommunicationSystem, localSocket: LONG CARDINAL,
serviceConnection: PROCEDURE [UNSPECIFIED, Connection, STRING],
serviceConnectionData: UNSPECIFIED, receiveSeconds: CARDINAL] RETURNS [port: Port],l4269d3740\f6b16f1 9f6 57f1 13f6 21f1 9f6 2f1 11f6 14f1 6f6 26f1 11f6 18f1 8f6 2f1 7f6
  DeactivatePort: PROCEDURE [communicationSystem: CommunicationSystem, port: Port],l4269d3740\f6b18f1 9f6
    -- data transmission and receipt primitivesl4269d3740e12\i
  SendBytes: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, bytePointer: BytePointer],l4269d3740\f6b13f1 9f6
  ReceiveBytes: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, bytePointer: BytePointer, settleForLess: BOOLEAN],l4269d3740\f6b16f1 9f6 109f1 7f6
  SendByte: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, byte: Byte],l4269d3740\f6b12f1 9f6
  ReceiveByte: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, settleForNone: BOOLEAN] RETURNS [byte: Byte, settledForNone: BOOLEAN],l4269d3740\f6b15f1 9f6 83f1 7f6 2f1 7f6 30f1 7f6
  ProduceDiscontinuity,l4269d3740\f6b
  ConsumeDiscontinuity,l4269d3740\f6b
  ForceOutput: PROCEDURE [communicationSystem: CommunicationSystem,  connection: Connection]];l4269d3740\f6b15f1 9f6
CommunicationSystem: TYPE = POINTER TO CommunicationSystemObject;l4269d3740e12\f6b21f1 4f6 3f1 10f6
CommunicationSystemObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740\f6b27f1 4f6 3f1 6f6 9f1 11f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740\f6b18f1 4f6 3f1 6f6 9f1 11f6
Port: TYPE = POINTER TO PortObject;l4269d3740\f6b6f1 4f6 3f1 10f6
PortObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740\f6b12f1 4f6 3f1 6f6 9f1 11f6
BytePointer: TYPE = POINTER TO BytePointerObject;l4269d3740\f6b13f1 4f6 3f1 10f6
BytePointerObject: TYPE = RECORD [address: POINTER, offset: BOOLEAN, count: CARDINAL];l4269d3740\f6b19f1 4f6 3f1 6f6 11f1 7f6 10f1 7f6 9f1 8f6
Byte: TYPE = [0..377B];l4269d3740\f6b6f1 4f6
G.3.  General Characteristicsx4e12k54\b29B
The communication primitives employed by FTP and suppliable by the client are described below.  Statements that apply to all valid implementations of a primitive (that is, one or both of FTP's implementations and any a client might supply) are rendered in the standard font.  Statements which apply only to one or both of the standard implementations supplied by FTP are rendered in a smaller font.x4e12jk54\276f1 121f0
In accordance with standard Mesa exception handling conventions, communication primitives report errors by signalling.  FTP catches any signal that reaches it and aborts the current transaction (with the help of the remote FTP User, Listener, or Server, as necessary).  Wherever possible, client communication primitives should use the standard FTP signal, FTPError (described in Section 1.4), to report errors.  Doing so enables the FTP User or Server to communicate the error to the remote FTP Server or User in a meaningful way.  The description of each procedure below includes a list of the FtpError values that seem, to the author, most appropriate for that primitive.  Requests by communication primitive implementors for new FtpError values will be gladly entertained. x4e12jk54\357f6b8f0B231f6b8f0B129f6b8f0B
The communication system provides stream-like connections that are used by FTP to interconnect FTP Users with FTP Servers.  Over such connections flow streams of data partitioned into logical records by discontinuities in the streams.  The communication system provides primitives for producing and consuming discontinuities, as well as for sending and receiving data.  In general, data transmitted by the client (that is, FTP) are buffered by the communication system until an amount consistent with efficient use of the transmission medium has been accumulated.  Before waiting for a response from the remote FTP User or Server to previously transmitted data, therefore, FTP must insure that it has actually been sent, by invoking the ForceOutput primitive, described in Section G.6.x4e12jk54\46i11I146i15I519f6b11f0B
Some of the data transmission and receipt primitives require among their parameters a byte pointer that defines the block of storage to be emptied or filled.  A byte pointer is a POINTER to a RECORD containing the address of a storage block, the offset from that address to the first byte of data, and a count of the number of bytes to be read or written:x4e12jk54\86i12I81f1 7f0 6f1 6f0 16f6b7f0B25f6b6f0B52f6b5f0B
BytePointer: TYPE = POINTER TO BytePointerObject;l4269d3740x4e12k54\f6b13f1 4f6 3f1 10f6
BytePointerObject: TYPE = RECORD [address: POINTER, offset: BOOLEAN, count: CARDINAL];l4269d3740x4k54\f6b19f1 4f6 3f1 6f6 11f1 7f6 10f1 7f6 9f1 8f6
If offset is FALSE, the first byte of data is the left most (that is, high order) byte of the addressed word; if offset is TRUE, the first byte of data is the right most (that is, low order) byte of that word.  In practice, the vast majority of calls on the primitives requiring byte pointers will specify an offset of FALSE.  However, the generality of the communication protocols employed by FTP requires this same generality at the interface to the communication system.x4e12jk54\3f6b6f0B4f1 5f0 95f6b6f0B4f1 4f0 81f1 264f0i
Each primitive that accepts a byte pointer among its arguments has the side effect of updating that byte pointer to address the first byte of data beyond the last byte actually transmitted or received.  Since the SendBytes procedure described in Section G.6 always transmits the entire contents of the storage block, it returns with the byte pointer updated to address the first byte beyond that block.  Since the ReceiveBytes primitive described in Section G.7 may receive less than the requested number of bytes, it may return with the byte pointer updated to a place somewhere within the specified storage block.x4e12jk54\i200I13f6b9f0B192f6b12f0B
G.4.  Program Management Primitivesx4e12k54\b35B
FTP or its client provides two procedures for creating and destroying instances of the local communication system.  The first, CreateCommunicationSystem, used by both FTP User and Listener, creates a new instance of the local communication system.  The procedure returns a handle, communicationSystem, to the newly created communication system instance, which the caller must retain and later present to any of the other communication primitives it invokes.  The communicationSystem is a pointer to a private record containing all of the state information the communication system instance requires to function properly.  The Alto implementation of this procedure turns on the Pup Package:     x4e12jk54\127f6b25f0B129f6b19f0B163f6b19f0B138f1 69f0
CreateCommunicationSystem: PROCEDURE RETURNS [communicationSystem: CommunicationSystem];l4269d3740x4e12k54\f6b27f1 9f6 1f1 7f6
CommunicationSystem: TYPE = POINTER TO CommunicationSystemObject;l4269d3740x4e12k54\f6b21f1 4f6 3f1 10f6
CommunicationSystemObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b27f1 4f6 3f1 6f6 9f1 11f6
The second procedure, DestroyCommunicationSystem, used by both FTP User and Listener, destroys a previously created instance of the local communication system, reclaiming any local resources allocated to it.  Before invoking this procedure, the caller must close all open connections and deactivate all active ports.  The Alto implementation of this procedure destroys the Pup Package:     x4e12jk54\22f6b26f0B268f1 69f0
DestroyCommunicationSystem: PROCEDURE [communicationSystem: CommunicationSystem];l4269d3740x4e12k54\f6b28f1 9f6
CommunicationSystem: TYPE = POINTER TO CommunicationSystemObject;l4269d3740x4e12k54\f6b21f1 4f6 3f1 10f6
CommunicationSystemObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b27f1 4f6 3f1 6f6 9f1 11f6
G.5.  Connection Management Primitivesx4e12k54\b38B
FTP or its client provides four procedures for creating and destroying network connections.  The first, OpenConnection, used only by FTP User, establishes a connection to the specified remoteHost and remoteSocket and returns a handle to it.  The caller specifies the interval in seconds, receiveSeconds, after which subsequently unfulfilled calls to the ReceiveBytes or ReceiveByte procedure described in Section G.7 are to be timed out and aborted.  The distinguished value LAST[CARDINAL] requests the maximum allowed timeout interval, which may be infinite.  The Alto implementation of this procedure interprets remoteHost as either a host name or Ethernet address, and creates a network stream to the specified socket at that host:     x4e12jk54\104f6b14f0B39f6b10f0B18f6b10f0B5f6b12f0B76f6b14f0B52f6b12f0B4f6b11f0B94f1 14f0 72f1 53b10B109f0
OpenConnection: PROCEDURE [communicationSystem: CommunicationSystem, remoteHost: STRING, remoteSocket: LONG CARDINAL, receiveSeconds: CARDINAL] RETURNS [connection: Connection];l4269d3740x4e12k54\f6b16f1 9f6 56f1 6f6 16f1 13f6 18f1 8f6 2f1 7f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Exceptions:  noSuchHost, connectionRejected, noRouteToNetwork, noNameLookupResponse.l4269d3740x4e12k54\f1u10f7U
The second procedure, CloseConnection, used only by FTP User, closes the previously opened connection with the specified handle.  The Alto implementation of this procedure simply deletes the network stream:     x4e12jk54\22f6b15f0B54f6b10f0B27f1 77f0
CloseConnection: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection];l4269d3740x4e12k792\f6b17f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
The third procedure, ActivatePort, used only by FTP Listener, causes the local host to become responsive to incoming requests for connection to the specified localSocket, and returns a handle to the newly established local communication port.  The caller specifies the interval in seconds, receiveSeconds, after which subsequently unfulfilled calls to the ReceiveBytes or ReceiveByte procedure described in Section G.7 are to be timed out and aborted.  The distinguished value LAST[CARDINAL] requests the maximum allowed timeout interval, which may be infinite.  As long as the port is active, the communication system will automatically create a connection for each incoming request, and invoke the caller-supplied serviceConnection procedure to service that connection.  This procedure receives as arguments the serviceConnectionData  supplied to ActivatePort, a handle for the newly established connection, and the host name (possibly expressed as a network address, depending upon the implementation) of the host that initiated the connection request.  When serviceConnection returns, its caller (within the communication system) will close the connection.  The Alto implementation of this procedure simply creates a Pup listener for the indicated socket:     x4e12jk54\21f6b12f0B125f6b11f0B68f6b4f0B49f6b14f0B52f6b12f0B4f6b11f0B94f1 14f0 225f6b17f0B81f6b21f0B14f6b12f0B201f6b17f0B83f1 96f0
ActivatePort: PROCEDURE [communicationSystem: CommunicationSystem, localSocket: LONG CARDINAL,
serviceConnection: PROCEDURE [UNSPECIFIED, Connection, STRING],
serviceConnectionData: UNSPECIFIED, receiveSeconds: CARDINAL] RETURNS [port: Port];l4269d3740x4e12k54\f6b14f1 9f6 57f1 13f6 21f1 9f6 2f1 11f6 14f1 6f6 26f1 11f6 18f1 8f6 2f1 7f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Port: TYPE = POINTER TO PortObject;l4269d3740x4k54\f6b6f1 4f6 3f1 10f6
PortObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b12f1 4f6 3f1 6f6 9f1 11f6
The fourth procedure, DeactivatePort, used only by FTP Listener, deactivates the previously activated port with the specified handle.  Existing connections remain unaffected and will continue to be serviced by the client, but no new incoming requests for connection to the affected socket will be honored  The Alto implementation of this procedure sets a flag, pokes the listening process, and waits for it to destroy itself:     x4e12jk54\22f6b14f0B66f6b4f0B200f1 118f0
DeactivatePort: PROCEDURE [communicationSystem: CommunicationSystem, port: Port];l4269d3740x4e12k54\f6b16f1 9f6
Port: TYPE = POINTER TO PortObject;l4269d3740x4e12k54\f6b6f1 4f6 3f1 10f6
PortObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b12f1 4f6 3f1 6f6 9f1 11f6
G.6.  Data Transmission Primitivesx4e12k792\b34B
FTP or its client provides four procedures for transmitting data via a previously opened connection.  The first, SendBytes, used by both FTP User and Server, enqueues for transmission via the specified connection, the contents of the block of storage denoted by the specified bytePointer.  As a side effect, the procedure updates the byte pointer to address the first byte beyond the storage block.  The procedure returns after the caller's storage block has been emptied but, in general, before the data has actually been transmitted to the remote host.  Data are transmitted only when an amount consistent with efficient use of the transmission medium has been accumulated by the communication system, or when the ForceOutput procedure described below is invoked, whichever occurs first.  The Alto implementation of this procedure simply outputs the block of data on the network stream and advances the byte pointer:x4e12jk54\113f6b9f0B80f6b10f0B64f6b11f0B111f1 2f0 316f6b11f0B64f1 126f0
SendBytes: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, bytePointer: BytePointer];l4269d3740e12\f6b11f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
BytePointer: TYPE = POINTER TO BytePointerObject;l4269d3740x4k54\f6b13f1 4f6 3f1 10f6
BytePointerObject: TYPE = RECORD [address: POINTER, offset: BOOLEAN, count: CARDINAL];l4269d3740x4k54\f6b19f1 4f6 3f1 6f6 11f1 7f6 10f1 7f6 9f1 8f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
The second procedure, SendByte, used by both FTP User and Server, enqueues for transmission via the specified connection, the indicated byte of data.  In general, the procedure returns before the data has actually been transmitted to the remote host.  Data are transmitted only when an amount consistent with efficient use of the transmission medium has been accumulated by the communication system, or when the ForceOutput procedure described below is invoked, whichever occurs first.  The Alto implementations of this procedure simply outputs the byte of data on the network stream, unless it is the first byte following a discontinuity, in which case it transmits the byte in the form of a change in subsequence type:x4e12jk54\22f6b8f0B80f6b10f0B16f6b4f0B272f6b11f0B62f1 234f0
SendByte: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, byte: Byte];l4269d3740e12\f6b10f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Byte: TYPE = [0..377B];l4269d3740x4k54\f6b6f1 4f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
The third procedure, ProduceDiscontinuity, used by both FTP User and Server, creates a discontinuity in the stream being transmitted via the specified connection, at a point immediately following the last byte of data sent.  Multiple calls upon this procedure without intervening data are treated as no operations.  The Alto implementation of this procedure simply makes note of the requested discontinuity so that the next byte of data sent via SendByte will be transmitted in the form of a change in subsequence type:x4e12jk54\21f6b20f0B110f6b10f0B153f1 132b8B64f0
ProduceDiscontinuity: PROCEDURE [communicationSystem: CommunicationSystem,  connection: Connection];l4269d3740e12\f6b22f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
The fourth procedure, ForceOutput, used by both FTP User and Server, causes all data previously sent via the specified connection actually to be transmitted to the remote host.  In the absence of calls upon this procedure, data are transmitted only when an amount consistent with efficient use of the transmission medium has been accumulated by the communication system.  Multiple calls upon this procedure without intervening data are treated as no operations.  The Alto implementation of this procedure simply invokes the network stream's SendNow primitive:x4e12jk54\22f6b11f0B86f6b10f0B332f1 80b7B10f0
ForceOutput: PROCEDURE [communicationSystem: CommunicationSystem,  connection: Connection];l4269d3740e12\f6b13f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
G.7.  Data Receipt Primitivesx4e12k54\b29B
FTP or its client provides three procedures for receiving data transmitted via a previously opened connection.  The first, ReceiveBytes, used by both FTP User and Server, accepts from the specified connection, some or all of the data required to fill the block of storage denoted by the specified bytePointer.  If settleForLess is FALSE, the procedure completely fills the block of storage, blocking the client as long as is required to obtain the requested amount of data.  If settleForLess is TRUE, the procedure returns whatever data the communication system may have already received, up to the capacity of the storage block, blocking the client if necessary to obtain at least one byte of data.  Regardless of the value of settleForLess, a discontinuity in the input stream will terminate the receive operation at that point.  As a side effect, the procedure updates the byte pointer to address the byte just beyond the last byte read, thereby informing the client of the quantity of data actually returned by the procedure.  The Alto implementation of this procedure simply invoke the network stream's GetBlock procedure, terminating on end of physical record (if settleForLess is TRUE) or a change in subsequence type:x4e12jk54\123f6b12f0B63f6b10f0B89f6b11f0B6f6b13f0B4f1 5f0 142f6b13f0B4f1 4f0 229f6b13f0B288f1 79b8B54b13B41f0
ReceiveBytes: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, bytePointer: BytePointer, settleForLess: BOOLEAN];l4269d3740e12\f6b14f1 9f6 109f1 7f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
BytePointer: TYPE = POINTER TO BytePointerObject;l4269d3740x4k54\f6b13f1 4f6 3f1 10f6
BytePointerObject: TYPE = RECORD [address: POINTER, offset: BOOLEAN, count: CARDINAL];l4269d3740x4k54\f6b19f1 4f6 3f1 6f6 11f1 7f6 10f1 7f6 9f1 8f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
The second procedure, ReceiveByte, used by both FTP User and Server, returns to the caller the next byte of data transmited via the specified connection.  A discontinuity in the input stream either aborts the procedure, if settleForNone if FALSE, or causes the procedure to return empty-handed, if settleForNone is TRUE.  In either case, the procedure returns an indication of whether it settledForNone.  The Alto implementation of this procedure simply invoke the network stream's GetByte procedure, noting and acting upon a change in subsequence type:x4e12jk54\22f6b11f0B67f6b4f0B38f6b10f0B71f6b13f0B4f1 5f0 53f6b13f0B4f1 4f0 69f6b14f0B1f1 79b7B63f0
ReceiveByte: PROCEDURE [communicationSystem: CommunicationSystem, connection: Connection, settleForNone: BOOLEAN] RETURNS [byte: Byte, settledForNone: BOOLEAN];l4269d3740e12\f6b13f1 9f6 83f1 7f6 2f1 7f6 30f1 7f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Byte: TYPE = [0..377B];l4269d3740x4k54\f6b6f1 4f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
The third procedure, ConsumeDiscontinuity, used by both FTP User and Server, consumes any discontinuity that might exist at the current point in the input stream being received via the specified connection.  Unnecessary calls upon this procedure are treated as no operations.  The Alto implementation of this procedure simply clears the discontinuity-pending condition, if it exists:x4e12jk54\21f6b20f0B154f6b10f0B70f1 107f0
ConsumeDiscontinuity: PROCEDURE [communicationSystem: CommunicationSystem,  connection: Connection];l4269d3740e12\f6b22f1 9f6
Connection: TYPE = POINTER TO ConnectionObject;l4269d3740x4e12k54\f6b12f1 4f6 3f1 10f6
ConnectionObject: TYPE = RECORD [dummy: UNSPECIFIED];l4269d3740x4k54\f6b18f1 4f6 3f1 6f6 9f1 11f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork.l4269d3740x4e12k54\f1u10f7U
Appendix H:  Sample Configuration and Programx4e24k792\f5b45B
H.1.  Introductionx4e12k54\b18B
The sample configuration and stand-alone program presented below, which store a single file on a remote file system, illustrate FTP's use on the Alto.  The reader is referred to Appendix I for the location of the necessary object files. x4e12jk54
H.2.  Sample Configurationx4e12k54\b26B
The programmer must include in his configuration:  FTP; file, mail, and communication primitives, as appropriate; and (on the Alto) the Pup Package.  In the sample configuration below, just the FTP User code is included, since the sample program creates no FTP Listener:x4e12jk54
FTPCSample: CONFIGURATION
  -- import list
    IMPORTS DiskKDDefs, FrameDefs, ImageDefs, IODefs, ProcessDefs,
      SegmentDefs, StreamDefs, StringDefs, SystemDefs, TimeDefs
  -- control module
    CONTROL FTPSample
  = BEGIN

-- sample program
  FTPSample;

-- ftp
  FTPUser;

-- communication
  TinyPup;

  END. -- of FTPCSamplee12\f6b12f1 13f6 22f1 7f6 144f1 7f6 15f1 5f6 84f1 3f6
H.3.  Sample Programx4e12k792\b20B
The sample program first initializes FTP; creates an FTP User using the file and communication primitives supplied by FTP; extracts the login user name and password from the Alto operating system and uses them as its credentials; opens a connection to IRIS; stores a copy of the local file, FTPCSample.Bcd, in the remote file system; closes the connection to IRIS; destroys the FTP User; and finalizes FTP:x4e12jk54\291f6b14f0B
DIRECTORY
  FTPDefs:		FROM "FTPDefs"			USING [
      FTPCloseConnection, FTPCreateUser, FTPDestroyUser, FTPError, FTPFinalize,
      FTPInitialize, FTPOpenConnection, FTPSetCredentials, FTPStoreFile, FTPUser,
      PupCommunicationPrimitives, AltoFilePrimitives],
  ImageDefs:		FROM "ImageDefs"		USING [StopMesa],
  IODefs:			FROM "IODefs"			USING [WriteLine],
  OsStaticDefs:	FROM "OsStaticDefs"	USING [OsStatics],
  StringDefs:		FROM "StringDefs"		USING [BcplToMesaString];
  
FTPSample: PROGRAM
  -- import list
    IMPORTS FTPDefs, ImageDefs, IODefs, StringDefs
  = BEGIN OPEN FTPDefs, ImageDefs, IODefs, OsStaticDefs, StringDefs;

-- variables
ftpInitialized: BOOLEAN _ FALSE;
ftpuser, copy: FTPUser _ NIL;
user: STRING _ [40];
password: STRING _ [40];

-- intercept errors
BEGIN ENABLE
  BEGIN
  FTPError =>
    BEGIN
    IF message # NIL THEN WriteLine[message];
    CONTINUE;
    END;
  UNWIND =>
    BEGIN
    IF ftpuser # NIL THEN FTPDestroyUser[ftpuser];
    IF ftpInitialized THEN FTPFinalize[];
    END;
  END;

-- initialize ftp
FTPInitialize[];  ftpInitialized _ TRUE;

-- create ftp user
ftpuser _ FTPCreateUser[AltoFilePrimitives[], PupCommunicationPrimitives[]];

-- set credentials to login user and password
BcplToMesaString[OsStatics^.UserName, user];
BcplToMesaString[OsStatics^.UserPassword, password];
FTPSetCredentials[ftpuser, primary, user, password];

-- open connection, store self, and close connection
FTPOpenConnection[ftpuser, "Iris"L, files, NIL];
[] _ FTPStoreFile[ftpuser, "FTPCSample.BCD"L, "FTPCSample.BCD"L, binary];
FTPCloseConnection[ftpuser];

-- destroy ftp user
copy _ ftpuser;  ftpuser _ NIL;  FTPDestroyUser[ftpuser];

-- finalize ftp
ftpInitialized _ FALSE;  FTPFinalize[];
END; -- enable

-- return to exec
StopMesa[];

END. -- of FTPSamplex4e12k54\f1b9f6 13f1 4f6 13f1 5f6 234f1 4f6 14f1 5f6 25f1 4f6 12f1 5f6 30f1 4f6 16f1 5f6 29f1 4f6 15f1 5f6 35f1 7f6 22f1 7f6 44f1 10f6 85f1 7f6 3f1 5f6 27f1 3f6 8f1 6f6 19f1 6f6 30f1 12f6 3f1 5f6 19f1 5f6 5f1 2f6 11f1 3f6 1f1 4f6 25f1 8f6 6f1 3f6 4f1 6f6 8f1 5f6 5f1 2f6 11f1 3f6 1f1 4f6 30f1 2f6 16f1 4f6 20f1 3f6 4f1 3f6 56f1 4f6 394f1 3f6 154f1 3f6 62f1 5f6 18f1 3f6 44f1 3f6
Appendix I:  Production Configurations and File Locationsx4e24k792\f5b57B
I.1.  Introductionx4e12k54\b18B
FTP is offered in a number of configurations, described below.  In theory at least, it is possible to build a configuration that includes only the desired facilities.  Here is a summary of what the various optional pieces do:x4e12jk54
FTPAltoFile implements an interface to the Alto file system as described in Appendix E.l4269d3740x4e12jk54\f6b11f0B
FTPPupComCool and FTPPupComHot implement the Pup version of the communication interface described in Appendix G.  They require either TinyPup or FatPup to be included in your configuration.l4269d3740x4e12jk54\f6b13f0B5f6b12f0B
FTPUserStore implements FTPStoreFile, as described in Section 3.5.l4269d3740x4e12jk54\f6b12f0B12f6b12f0B
FTPUserRetrieve implements FTPRetrieveFile, as described in Section 3.5.l4269d3740x4e12jk54\f6b15f0B12f6b15f0B
FTPUserDump implements the Dump Primitives described in Appendix B.  If it is ommitted, DumpBlock (from FTPUserStore) and/or LoadBlock (from FTPUserRetrieve) will need dummy implementations to satisfy the Binder.l4269d3740x4e12jk54\f6b11f0B77f6b9f0B7f6b12f0B9f6b9f0B7f6b15f0B
FTPUserFiles implements most of the other user file primitives (FTPEnumerateFiles, FTPDeleteFile, FTPRenameFile, and FTPSetFilenameDefaults) described in Section 3.l4269d3740x4e12jk54\f6b12f0B52f6b17f0B2f6b13f0B2f6b13f0B6f6b22f0B
FTPUserXfer implements FTPTransferFile, as described in Appendix D.3.l4269d3740x4e12jk54\f6b11f0B12f6b15f0B
FTPUserMailIn implements the mail retrieval primitives described in Appendix C.3.l4269d3740x4e12jk54\f6b13f0B
FTPUserMailOut implements the mail delivery primitives described in Appendix C.2.l4269d3740x4e12jk54\f6b14f0B
FTPAccessories translates error codes into text.  If the text is not needed, it may be omitted if dummy routines are provided.l4269d3740x4e12jk54\f6b14f0B
FTPTrace implements the trace facilities described in Appendix D, Section D.2.  It may be omitted if dummy routines are provided to satisfy the Binder.l4269d3740x4e12jk54\f6b8f0B
FTPSysMail plus a local file system interface of the client's choosing is used to implement a mail server as described in Appendix F.l4269d3740x4e12jk54\f6b10f0B
Dummy* implement the various routines needed to glue FTP together and/or to satisfy the Binder.l4269d3740x4e12jk54\f6b6f0B
I.2.  Production Configurationsx4e12k54\b31B
The client can determine FTP's version number by means of the following constants defined in FTPDefs:x4e12jk54\93f6b7f0B
ftpMajorVersion: Byte = 6;l4269x4e12k54\f6b
ftpMinorVersion: Byte = 1;l4269x4k54\f6b
Byte: TYPE = [0..377B];l4269x4e12k54\f6b6f1 4f6
FTP 6.0 is written in Mesa 6.0 and FTP proper imports Process, String, and Storage.  The FTP-provided file, mail and, communication interfaces import additional components of Mesa, and/or Pup.x4e12jk54\6f6 1f0 47f6b7f0B2f6b6f0B6f6b7f0B
The following production FTP configurations presently exist; others will be created as need for them is expressed by the user community:x4e12jk54
FTPUser:  FTP User file primitives (that is, the primitives of Sections 2 and 3 and of Appendices B and D).  In calls to FTPOpenConnection, purpose must be files. l4269d3740x4e12jk54\f6b7f0B114f6b17f0B2f6b7f0B9f6b5B1f0
FTPServers:  FTP Listener file and mail primitives only (that is, the primitives of Sections 2 and 4, and of Appendix D, Sections D.2 and D.4). l4269d3740x4e12jk54\f6b10f0B
MTPUser:  FTP User mail primitives only (that is, the primitives of Appendices C.2, C.3, and D.4).  In calls to FTPOpenConnection, purpose must be mail.   This is a minimal system primarily for use by Laurel.  It does not contain FTPAccessories or the trace facilities of Appendix D.2.l4269d3740x4e12jk54\f6b7f0B105f6b17f0B2f6b7f0B9f6b4B1f0 78f6b14f0B
FTPMTPUser:  This configuration contains all of the user facilities for files and/or mail. l4269d3740x4e12jk54\f6b10f0B79f6 1f0
FTPAll:  This configuration contains all of the user and server facilities for files and/or mail. l4269d3740x4e12jk54\f6b6f0B90f6 1f0
PupAndFTP:  This is simply TinyPup, EFTPSend, and FTPMTPUser all packaged into one big lump to eliminate the complexities of including the correct packages.l4269d3740x4e12jk54\f6b9f0B18f6b7f0B2f6b8f0B6f6b10f0B95f6 1f0
Appendix J:  Utilitiesx4e24k792\f5b22B
FTP needs a few routines that may be useful to other programs.  They are packaged separately so that they can be included in you configuration even if you do not need the appropiate parts of FTP.x4e12jk54
J.1.  TimeExtraDefsx4e12k54\b6f6 13f0B
TimeExtraDefs is exported by FTPUser, FTPMTPUser, and PupAndFTP.  If one of them is not needed, TimeExtras can be included directly.x4e12jk54\f6b13f0B16f6b7f0B2f6b10f0B6f6b9f0B33f6b10f0B
If the argument is NIL or its contents cannot be parsed as a reasonable time, it returns 0.  There are probably many strings easily recognizable by a person that PackedTimeFromString won't be able to handle, but it doesn't have any trouble with the output of the existing FTP programs (Maxc, IFS, Alto BCPL, Juniper) and TimeDefs.AppendDayTime.x4e12jk54\19f7b3f0B140f6b20f0B139f6b22f0B
PackedTimeFromString: PROCEDURE [STRING] RETURNS [TimeDefs.PackedTime];l4269x4e12k54\f6b22f1 10f6 1f1 6f6 2f1 7f6
J.2.  DirExtraDefsx4e12k54\b6f6 12f0B
The server half of FTPAltoFile uses DirExtras to do * and # expansion.  It is not exported by any of the standard FTP configurations.x4e12jk54\f6 19b11f0B6f6b9f0B69f6b3f0B
There is only one procedure in DirExtras: EnumerateDirectoryMasked.  It scans the directory, and presents to proc the matching files in directory order.  The trailing "." on Alto file names has already been removed when proc is called.x4e12jk54\31f6b9f0B2f6b24f0B43f6b4f0B107f6b4f0B
EnumerateDirectoryMasked: PROCEDURE [
  files: STRING,
  proc: PROCDURE [fp: POINTER TO FP, file: STRING] RETURNS [BOOLEAN] ];l4269x4e12k54\f6b26f1 10f6 1f1 1f6 7f1 8f6 10f7 8f6 6f7 10f6 11f7 6f6 2f7 7f6 2f7 7f6