Heading:

Mesa FTP Functional Specification

Page Numbers: Yes X: 527 Y: 10.5" First Page: 20

Appendix A: Error Summary

A.1. Introduction

Exceptional conditions encountered by FTP are reported to the client by means of a single signal, FTPError. FTPError has two parameters that pinpoint the error: an enumerated type, ftpError, to be interpreted by the client; and a STRING, message, to be interpreted by the human user. Listed alphabetically below are the values that ftpError can assume, along with descriptions of the causes of these errors and, where appropriate, their possible remedies.

A.2. Errors

communicationPrimitivesNotSpecified

A client error signalled by FTPCreateUser or FTPCreateListener. The communicationPrimitives parameter supplied to one of these procedures is NIL. Provided the corresponding program module has been bound into the client’s configuration (see Appendix I), an acceptable value for this parameter is the one returned by the FTP procedure PupCommunicationPrimitives.

connectionAlreadyEstablished

A client error signalled by FTPOpenConnection. The specified ftpuser already supports an open connection. A local FTP User can simultaneously support at most one connection to a remote FTP Server. The client should either close the existing connection via FTPCloseConnection or create another FTP User via FTPCreateUser.

connectionClosed

A communication error signalled by many primitives. The connection to the remote FTP Server (or User) has been closed. It was either deliberately closed by the Server (User), or it was closed by the Server’s (User’s) communication system when the Server (User) crashed. The client should clear the local FTP User of the connection-closed condition via FTPCloseConnection, and then try to reestablish communication with (a new FTP Server at) the remote host by recalling FTPOpenConnection. A typical FTP Server will break off communication with a remote FTP User that allows its connection to the Server to remain idle for more than a few minutes. The client should, therefore, either punctuate such idle periods with calls to FTPRenewConnection or be prepared to reestablish the connection whenever it discovers it closed.

connectionNotOpenedForFiles

A client error signalled by most file primitives. A file operation has been attempted using a connection that was opened for mail operations only. The client should close the existing connection via FTPCloseConnection and reopen it via a call to FTPOpenConnection with purpose specified as either files or filesAndMail.

connectionNotOpenedForMail

A client error signalled by most mail primitives. A mail operation has been attempted using a connection that was opened for file operations only. The client should close the existing connection via FTPCloseConnection and reopen it via a call to FTPOpenConnection with purpose specified as either mail or filesAndMail.

connectionRejected

A communication error signalled by FTPOpenConnection. Either no FTP Listener is resident in the remote host, or that Listener is rejecting requests for new connections for lack of resources. At a later time, the client should reattempt connection via FTPOpenConnection.

connectionTimedOut

A communication error signalled by many primitives. Either the remote FTP Server (or User) has crashed, or its communication hardware has broken and effectively cut it off from the local FTP User (Server). The client should clear the local FTP User of the connection-timed-out condition via FTPCloseConnection, and at a later time try to reestablish communication with (a new FTP Server at) the remote host by recalling FTPOpenConnection.

credentialsMissing

A credentials-related client or user error signalled by many primitives. Before it can carry out the requested operation, the remote FTP Server requires the local user’s credentials. The client should supply them via FTPSetCredentials and then reattempt the operation.

dumpFileBlockTooLong

A dump file format error signalled by FTPInventoryDumpFile or FTPRetrieveFile. One or more of the blocks within the dump file is declared by its header to contain more than 256 bytes of data. The program that created the dump file is in error, and the dump file cannot be read by FTP.

dumpFileCheckSumInError

A dump file format error signalled by FTPInventoryDumpFile or FTPRetrieveFile. One or more of the blocks within the dump file contains in its header a checksum that is inconsistent with the data in the block. The contents of the file have been altered as a result of faulty storage or transmission, and the dump file cannot be read by FTP.

duplicateMailboxException

A File Transfer Protocol (FTP) violation signalled by FTPIdentifyNextRejectedRecipient. The remote FTP Server transmitted to the local FTP User, two or more mailbox exceptions for a single recipient. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

duplicateProtocolParameter

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server transmitted to the local FTP User, two or more instances of a single parameter type in a single parameter list. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

errorBlockInDumpFile

A dump file error signalled by FTPInventoryDumpFile or FTPRetrieveFile. The program that (partially) created the dump file failed to complete it successfully. The fact that an error occurred while writing the file is explicitly and permanently recorded within it, and the dump file cannot be read by FTP.

fileAlreadyExists

A file error reported by FTPStoreFile. A remote file with the specified name already exists within the remote file system and cannot be overwritten. The client should either first delete the existing file via FTPDeleteFile and then reattempt the store operation via FTPStoreFile, or select another name or version for the remoteFile.

fileBusy

A file error reported by several primitives. Because the specified remote file is currently being manipulated by another (either local or remote) client, the file operation requested by the local client cannot now be carried out. The client should reattempt the operation at another time.

fileDataError

A file error reported by several primitives. A permanent error was encountered by the remote (or local) file system while reading or writing the remote (local) file. The client may wish to reattempt the operation, although the file may well be permanently damaged.

fileGroupDesignatorUnexpected

A client error signalled by FTPRetrievelFile or FTPDeleteFile. The specified remoteFile designates a group of remote files, rather than a single remote file. To retrieve or delete all files in the group, the client should enumerate the files via FTPEnumerateFiles and retrieve or delete each file in turn via FTPRetrieveFile or FTPDeleteFile.

filenameUnexpected

A client error signalled by FTPRetrieveFile, FTPDeleteFile, or FTPRenameFile. A file enumeration operation is in progress, and the specified remoteFile is not that most recently identified to the client by FTPEnumerateFiles. During the course of an enumeration, the client may manipulate the remote file system in no way other than that implied by FTPEnumerateFiles’ intent parameter. Specifying an intent of unspecified grants the client unconstrained access to the remote file system.

filePrimitivesNotSpecified

A client error signalled by FTPCreateUser or FTPCreateListener. The filePrimitives parameter supplied to one of these procedures is NIL.

filesModuleNotLoaded

A client error signalled by FTPOpenConnection or FTPCreateListener. The client specified a purpose of files or filesAndMail, yet the FTPUserFiles or FTPServerFiles module is absent from the client’s configuration. The client should either obtain a more appropriate standard configuration or, if none is currently provided, request one from his support group.

functionNotImplemented

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server failed to recognize a valid operation code sent to it by the local FTP User. This occurrence should be reported to your support group; it represents a bug or omission in the remote FTP implementation.

illegalBooleanParameter

A File Transfer Protocol (FTP) violation signalled by several primitives. The remote FTP Server transmitted to the local FTP User, a boolean parameter whose value was neither TRUE nor FALSE. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

illegalFileAttribute

A File Transfer Protocol (FTP) violation signalled by several primitives. The remote FTP Server reported that it received an illegal file attribute parameter from the local FTP User. This occurrence should be reported to your support group; it represents a bug in the local FTP implementation.

illegalFilename

A file error signalled by many primitives. The specified local or remote filename violates the syntax conventions of the local or remote file system. The client should correct the filename and reattempt the operation.

illegalFileType

A File Transfer Protocol (FTP) violation signalled by several primitives. The remote FTP Server (or User) transmitted to the local FTP User (or Server) a file type parameter the value of which was neither TEXT nor BINARY. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

illegalProcedureCallSequence

A client error signalled by several primitives. A composite operation (for example, the creation of a dump file) involving the successive invocation of several FTP primitives is in progress. The requested operation cannot be carried out until that composite operation is completed.

illegalProtocolParameterList

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server (or User) transmitted an ill-formed parameter list to the local FTP User (or Server). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

illegalProtocolSequence

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server (or User) transmitted to the local FTP User (or Server) a command or reply that was out of place in the protocol sequence. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

incorrectPrimaryPassword

A credentials-related client or user error signalled by many primitives. The primary password supplied to the remote FTP Server via FTPSetCredentials is incorrect. The client should supply a valid user name and its associated password via FTPSetCredentials and then reattempt the operation.

incorrectSecondaryPassword

A credentials-related client or user error signalled by many primitives. The secondary password supplied to the remote FTP Server via FTPSetCredentials is incorrect. The client should supply a valid user name and its associated password via FTPSetCredentials and then reattempt the operation.

inputDiscontinuityUnexpected

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server (or User) transmitted a truncated command to the local FTP User (or Server). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

mailModuleNotLoaded

A client error signalled by FTPCreateListener. The client specified a purpose of mail or filesAndMail, yet the FTPUserMail or FTPServerMail module is absent from the client’s configuration. The client should either obtain a more appropriate standard configuration or, if none is currently provided, request one from his support group.

mailPrimitivesNotSpecified

A client error signalled by FTPCreateListener. The mailPrimitives parameter supplied to this procedure is NIL. Provided the corresponding program module has been bound into the client’s configuration (see Appendix I), acceptable values for this parameter include those returned by the FTP procedures SysMailPrimitives and SomeMailPrimitives.

messageLongerThanAdvertised

A File Transfer Protocol (FTP) violation signalled by FTPRetrieveBlockOfMessage, FTPIdentifyNextMessage, or FTPEndRetrievalOfMessages. The remote FTP Server transmitted to the local FTP User a message that was longer than indicated by the byte count that preceded the message. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

messageShorterThanAdvertised

A File Transfer Protocol (FTP) violation signalled by FTPRetrieveBlockOfMessage, FTPIdentifyNextMessage, or FTPEndRetrievalOfMessages. The remote FTP Server transmitted to the local FTP User a message that was shorter than indicated by the byte count that preceded the message. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

missingMessageLength

A File Transfer Protocol (FTP) violation signalled by FTPIdentifyNextMessage or FTPEndRetrievalOfMessages. The remote FTP Server failed to transmit to the local FTP User the length of the message that was to follow. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

missingProtocolParameter

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP User (or Server) failed to transmit a required parameter to the local FTP Server (or User). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

noConnectionEstablished

A client error signalled by many primitives. The client has attempted to manipulate remote files or mail without first having opened a connection to a remote FTP Server. The client should open a connection via FTPOpenConnection and then reattempt the operation.

noNameLookupResponse

A communication error signalled by FTPOpenConnection. The specified host name cannot be decoded because all of the name lookup servers on all of the directly connected networks (normally just one Ethernet) are broken or are inaccessible. The client should reattempt connection via FTPOpenConnection at a later time.

noRoomForFile

A file error reported by FTPStoreFile. The specified remote file cannot be written because the remote disk allocation has been (or would be) exceeded. The client should delete one or more unwanted files via FTPDeleteFile and then reattempt the store operation via FTPStoreFile.

noRouteToNetwork

A communication error signalled by many primitives. The internetwork has been partitioned in such a way that the remote host is (no longer) accessible. The client should clear the no-route-to-network condition via FTPCloseConnection and reattempt connection via FTPOpenConnection at a later time.

noSuchFile

A file error signalled by many primitives. The specified local or remote file does not exist. The client should respecify the local or remote filename and reattempt the operation.

noSuchHost

A communication error signalled by FTPOpenConnection. The specified host name is unrecognized by the local name lookup server. The client should respecify the host name and reattempt the operation via FTPOpenConnection.

noSuchMailbox

A mail error signalled by FTPBeginRetrievalOfMessages. The specified mailboxName is unrecognized by the remote FTP Server. The client should respecify the mailbox name and reattempt the operation via FTPBeginRetrievalOfMessages.

noSuchPrimaryUser

A credentials-related client or user error signalled by many primitives. The primary user name supplied to the remote FTP Server via FTPSetCredentials is unrecognized by the Server (that is, the name is invalid). The client should supply a valid user name and its associated password via FTPSetCredentials and then reattempt the operation.

noSuchRecipientNumber

A File Transfer Protocol (FTP) violation signalled by FTPIdentifyNextRejectedRecipient. The remote FTP Server transmitted to the local FTP User, a mailbox exception, the identifying number of which was out of range. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

noSuchSecondaryUser

A credentials-related client or user error signalled by many primitives. The secondary user name supplied to the remote FTP Server via FTPSetCredentials is unrecognized by the Server (that is, the name is invalid). The client should supply a valid user name and its associated password via FTPSetCredentials and then reattempt the operation.

noValidRecipients

A mail error reported by FTPIdentifyNextRejectedRecipient. None of the recipients was accepted by the remote FTP Server; all were rejected. The client should clear the error condition via FTPEndDeliveryOfMessage, correct the distribution list, and reattempt the mail delivery operation via FTPBeginDeliveryOfMessage.

outputDiscontinuityUnexpected

A File Transfer Protocol (FTP) violation signalled by many primitives. The local FTP User (or Server) transmitted a truncated command to the remote FTP Server (or User). This occurrence should be reported to your support group; it represents a bug in the local FTP implementation.

protocolParameterListMissing

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP User (or Server) failed to transmit the required parameter list to the local FTP Server (or User). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation.

protocolVersionMismatch

A File Transfer Protocol (FTP) problem signalled by FTPOpenConnection or FTPRenewConnection. The local FTP User and remote FTP Server disagree on the version (that is, vintage) of the Protocol to be used. This occurrence should be reported to your support group; it represents an incompatibility between the local and remote FTP implementations.

queueInconsistent

An error internal to the local FTP implementation signalled by several primitives. One of the queues maintained by FTP (for example, the queue of FTP Servers created by a particular FTP Listener) is not valid. This occurrence should be reported to your support group; it represents a bug in the local FTP implementation.

requestedAccessDenied

A credentials error signalled by many primitives. The access privileges associated with the previously specified primary or secondary credentials are insufficient to allow the remote FTP Server to carry out the requested operation. The client may wish to supply the name and password of a more privileged user via FTPSetCredentials and then reattempt the operation.

stringTooLong

An error internal to the local FTP implementation signalled by many primitives. An attempt has been made to write more characters into a Mesa STRING than are permitted by its maximum length. This occurrence should be reported to your support group; it may represent a bug in the local FTP implementation.

unexpectedEndOfFile

An error internal to the local FTP implementation signalled by several primitives. An attempt has been made to read more characters from a system or scratch file (for example, that used to buffer the results of a file enumeration) than were previously written into that file. This occurrence should be reported to your support group; it represents a bug in the local FTP implementation.

unidentifiedError

An unidentified error signalled by many primitives. The requested operation was aborted due to an unidentified error. It is unknown whether the error is likely to recur. The client may wish, therefore, to treat the error as a transient one and reattempt the operation.

unidentifiedPermanentError

An unidentified error signalled by many primitives. The requested operation was aborted due to an unidentified error that is believed likely to recur if the operation is reattempted.

unidentifiedTransientError

An unidentified error signalled by many primitives. The requested operation was aborted due to an unidentified error that is believed unlikely to recur. The client may wish, therefore, to reattempt the operation.

unrecognizedDumpFileBlock

A dump file format error signalled by FTPInventoryDumpFile or FTPRetrieveFile. One or more of the blocks within the dump file is of unknown type. The program that created the dump file is in error, and the dump file cannot be read by FTP.

unrecognizedMailboxExceptionErrorCode

A File Transfer Protocol (FTP) violation signalled by FTPIdentifyNextRejectedRecipient. The remote FTP Server transmitted an unrecognized mailbox exception error code to the local FTP User. This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation or an incompatibility between the local and remote implementations.

unrecognizedProtocolErrorCode

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP Server (or User) transmitted an unrecognized error code to the local FTP User (or Server). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation or an incompatibility between the local and remote implementations.

unrecognizedProtocolParameter

A File Transfer Protocol (FTP) violation signalled by many primitives. The remote FTP User (or Server) transmitted an unrecognized parameter to the local FTP Server (or User). This occurrence should be reported to your support group; it represents a bug in the remote FTP implementation or an incompatibility between the local and remote implementations.

Appendix B: Dump Primitives

B.1. Introduction

Besides its more general file-manipulation primitives, FTP supplies a family of procedures for composing and decomposing remote dump files, as described below. A dump file is a single physical file that contains one or more logical files.

B.2. Inventory Primitives

FTP provides one procedure, FTPInventoryDumpFile, for enumerating the members of a remote dump file. For each logical file in the physical file whose name, remoteDumpFile, is specified, the procedure supplies to a client-provided procedure, processFile, the client’s processFileData and the logical file’s (absolute) filename. The order in which filenames are presented to the client is that in which the corresponding files were written into the dump file:

FTPInventoryDumpFile: PROCEDURE [ftpuser: FTPUser, remoteDumpFile: STRING, intent: DumpFileIntent,
processFile: PROCEDURE [UNSPECIFIED, STRING, FileInfo],
processFileData: UNSPECIFIED];

DumpFileIntent: TYPE = Intent[enumeration..retrieval];

Intent: TYPE = {enumeration, retrieval, deletion, renaming, unspecified};

FileInfo: TYPE = POINTER TO FileInfoObject;

FileInfoObject: TYPE = RECORD [
fileType: FileType, byteSize: CARDINAL, byteCount: LONG CARDINAL, creationDate, writeDate, readDate, author: STRING];

FileType: TYPE = {text, binary, unknown};

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, illegalFilename, noSuchFile, fileBusy, fileDataError, errorBlockInDumpFile, unrecognizedDumpFileBlock, dumpFileBlockTooLong, dumpFileCheckSumInError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence, fileGroupDesignatorUnexpected.

Notice that the TYPE of processFile is the same as that required by FTPEnumerateFiles. However, when processFile is called, the only interesting portion of the FileInfo is the creationDate.

The intent parameter supplied by the client declares the manner in which the client expects to manipulate the files the names of which are presented to it. This information enables the FTP User to intelligently select from among several possible protocol strategies for effecting the inventory. Since most such strategies occupy the remote FTP Server until the inventory is complete, FTP prohibits processFile from calling local FTP User procedures, other than those implied by intent, that communicate with the remote Server. The client may specify any of the following intents:

1. An intent of enumeration declares that the client seeks the names of the members of the designated dump file (for presentation to a human user, for example) and intends to manipulate the files in no other way during the course of the enumeration. More specifically, the client declares (and FTP insures) that processFile will make no calls to local FTP User procedures that communicate with the remote FTP Server.

2. An intent of retrieval declares that the client seeks to retrieve some or all (but possibly none) of the member files and to manipulate them in no other way during the course of the enumeration. The client’s processFile procedure may retrieve the member file the name of which is presented to it by supplying that name to the FTPRetrieveFile procedure described elsewhere. The byteCount returned by FTPRetrieveFile will reflect only the (original) contents of the member file; it will not reflect the additional bytes of formatting information contained in the dump file, which are stripped away by FTP. More specifically, then, the client declares (and FTP insures) that processFile will make no calls to local FTP User procedures (other than FTPRetrieveFile) that communicate with the remote FTP Server.

Once the dump file has been inventoried, the client may invoke the FTPNoteFilenameUsed primitive described in Appendix D to determine the fully qualified absolute and/or virtual filename used by the remote FTP Server.

B.3. Construction Primitives

FTP provides two procedures for constructing remote dump files. The first, FTPBeginDumpFile, initializes (to empty) a new remoteDumpFile and prepares it to receive member files via the FTPStoreFile procedure described in Section 3.5. In the presence of an open dump file, FTPStoreFile’s invocation is interpreted as a request to add the specified localFile to the open dump file as a new member. FTPStoreFile’s remoteFile parameter is interpreted as the name by which the file is to be known within the remote dump file. The byteCount returned by FTPStoreFile will reflect only the (original) contents of the member file; it will not reflect the additional bytes of formatting information contained in the dump file, which are supplied by FTP. Since the construction of a remote dump file occupies the remote FTP Server until the process is complete, FTP prohibits the client from calling local FTP User procedures (other than FTPStoreFile) that communicate with the remote FTP Server until the dump file is complete (that is, until the FTPEndDumpFile procedure described below has been invoked):

FTPBeginDumpFile: PROCEDURE [ftpuser: FTPUser, remoteDumpFile: STRING];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, illegalFilename, fileAlreadyExists, fileBusy, noRoomForFile, fileDataError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence.

The second procedure, FTPEndDumpFile, finalizes a newly created remote dump file after all member files have been added to it. Only by calling this procedure can the client leave the dump file construction mode entered via successful invocation of FTPBeginDumpFile:

FTPEndDumpFile: PROCEDURE [ftpuser: FTPUser];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noRoomForFile, fileDataError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence.

Appendix C: Mail Primitives

C.1. Introduction

Besides its file-related primitives, FTP supplies a family of procedures for delivering mail to and retrieving mail from remote mailboxes, as described below.

C.2. Delivery Primitives

FTP provides five procedures for delivering mail directly to remote mailboxes and/or for forwarding it to its ultimate destination via a third party. The first procedure, FTPBeginDeliveryOfMessage, initiates the delivery and/or forwarding of a single message to one or more remote recipients. Successful invocation of this first mail delivery procedure conditions the local FTP User to accept calls to the other four. Since the mail delivery process occupies the remote FTP Server until delivery is complete, FTP prohibits the client from calling other local FTP User procedures that communicate with the remote Server until FTPEndDeliveryOfMessage procedure described below has been invoked:

FTPBeginDeliveryOfMessage: PROCEDURE [ftpuser: FTPUser];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The second procedure, FTPSendRecipientOfMessage, identifies one of the message’s recipients. After FTPBeginDeliveryOfMessage has been invoked, this procedure is called repetitively until all of the recipients of the message have been specified. mailboxHostName and dmsName are leftover from Mesa 4 and some old ideas about how to forward mail. They will be deleted from the interface when FTP is converted to Mesa 6.

FTPSendRecipientOfMessage: PROCEDURE [ftpuser: FTPUser, mailboxName: STRING,
mailboxHostName: STRING ← NIL, dmsName: STRING ← NIL];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The third procedure, FTPIdentifyNextRejectedRecipient, reports to the client the rejection by the remote FTP Server of one of the intended recipients of the message. Delivery of the message succeeds or fails for each of its intended recipients independently. The procedure returns the number, recipientNumber, of the rejected recipient (the numbering starting at one) and two additional results that pinpoint the reason for the rejection: an enumerated type, recipientError, to be interpreted by the client; and a STRING, errorMessage (supplied by the client and filled in by the procedure), to be interpreted by the human user. The recipient errors reported by a local FTP User are actually detected by the remote FTP Server, and hence the User normally relays to the client the message supplied by the Server. If the Server provides no message, the User supplies an appropriate message in its place. All error messages issued by FTP are centralized in a single FTPAccessories module (see Appendix I). To avoid incurring the space overhead associated with these strings, some configurations omit this module, causing FTP to supply a zero-length string whenever it would otherwise obtain an errorMessage from FTPAccessories. Once, after FTPSendRecipientOfMessage has been invoked repetitively to specify the recipients of the message, and, once again, after the text of the message has been specified (as described later), FTPIdentifyNextRejectedRecipient must be called repetitively until a recipientNumber of zero is returned, indicating the end of the list. Most recipient errors (for example, noSuchMailbox) are detected and reported in the first round of calls to this procedure, but others (for example, unspecifiedTransientError) may not occur until the remote FTP Server actually attempts to append the message to the recipient’s mailbox:

FTPIdentifyNextRejectedRecipient: PROCEDURE [ftpuser: FTPUser, errorMessage: STRING] RETURNS [recipientNumber: CARDINAL, recipientError: RecipientError];

RecipientError: TYPE = {noSuchMailbox, noForwardingProvided, unspecifiedTransientError, unspecifiedPermanentError, unspecifiedError};

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noValidRecipients, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

Old Exceptions: noSuchForwardingHost, noSuchDmsName.

The fourth procedure, FTPSendBlockOfMessage, specifies a portion of the text of the message and is called repetitively after the recipients of the message have been specified and the first round of recipient rejections accepted, as described above. Successive calls specify the location in the client’s address space, source, and the length in bytes, byteCount, of successive blocks of text. The text of the message must include a message header conforming to the Arpanet standard detailed in [3]. Throughout the message, end of line is indicated via a carriage return (CR):

FTPSendBlockOfMessage: PROCEDURE [ftpuser: FTPUser, source: POINTER, byteCount: CARDINAL];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The fifth procedure, FTPEndDeliveryOfMessage, finalizes the delivery process. Only by calling this procedure can the client leave the mail delivery mode entered via successful invocation of FTPBeginDeliveryOfMessage:

FTPEndDeliveryOfMessage: PROCEDURE [ftpuser: FTPUser];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

C.3. Retrieval Primitives

FTP provides four procedures for retrieving the contents of (and then resetting to empty) a remote mailbox. The first, FTPBeginRetrievalOfMessages, initiates retrieval of the contents of the remote mailbox the host-specific name of whish is specified by mailboxName. To obtain access to the mailbox, the client must first have supplied the necessary credentials (if any) by calling the FTPSetCredentials procedure described elsewhere. Successful invocation of this first mail retrieval procedure conditions the local FTP User to accept calls to the other three. Since the mail retrieval process occupies the remote FTP Server until it is complete, FTP prohibits the client from calling other local FTP User procedures that communicate with the remote Server until the retrieval is complete (that is, until the FTPEndRetrievalOfMessages procedure described below has been invoked):

FTPBeginRetrievalOfMessages: PROCEDURE [ftpuser: FTPUser, mailboxName: STRING];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, noSuchMailbox, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The second procedure, FTPIdentifyNextMessage, retrieves information about one of the messages in the mailbox identified in a previous call to FTPBeginRetrievalOfMessages. FTPIdentifyNextMessage is called repetitively until a byteCount of zero (signalling no more messages) is returned. Successive calls return information about successive messages stored in the mailbox. The client may elect to leave some or all of the contents of the mailbox unretrieved, in which case whatever remains will be sent by the remote FTP Server but will be discarded by the local FTP User in the final call to the FTPEndRetrievalOfMessages procedure described later. The information returned by the procedure is deposited in a record, messageInfo, supplied by the client, and includes the size of the messsage in bytes, byteCount; the date and time, deliveryDate, at which the message was deposited in the mailbox (the required STRING being supplied by the client); and whether or not the message has been opened (that is, examined) or deleted while in the mailbox (Maxc mailboxes, for example, can be manipulated directly via the Tenex MSG subsystem):

FTPIdentifyNextMessage: PROCEDURE [ftpuser: FTPUser, messageInfo: MessageInfo];

MessageInfo: TYPE = POINTER TO MessageInfoObject;

MessageInfoObject: TYPE = RECORD [byteCount: LONG CARDINAL, deliveryDate: STRING, opened, deleted: BOOLEAN];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The third procedure, FTPRetrieveBlockOfMessage, retrieves a portion of the text of the message identified in a previous call to FTPIdentifyNextMessage. FTPRetrieveBlockOfMessage is called repetitively until an actualByteCount of zero (signalling no more blocks) is returned. Successive calls return successive blocks of the message. The client may elect to leave some or all of the text of the message unretrieved, in which case whatever remains will be sent by the remote FTP Server but will be discarded by the local FTP User in the next call to FTPIdentifyNextMessage. Note that the client can anticipate the end of a message on the basis of the byte count returned by FTPIdentifyNextMessage. The text returned by the procedure is deposited in the buffer whose location in the client’s address space, destination, and whose length in words, maxWordCount, are specified by the client. The procedure returns the length in bytes, actualByteCount, of the block of text actually retrieved (which may be shorter than the block requested). The text of the message includes a message header conforming to the Arpanet standard detailed in [3]. Throughout the message, end of line is indicated via a carriage return (CR):

FTPRetrieveBlockOfMessage: PROCEDURE [ftpuser: FTPUser, destination: POINTER, maxWordCount: CARDINAL] RETURNS [actualByteCount: CARDINAL];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

The fourth procedure, FTPEndRetrievalOfMessages, terminates the retrieval operation and resets the mailbox to empty. FTPBeginRetrievalOfMessages and FTPEndRetrievalOfMessages are implemented in such a way that no new messages are lost during the retrieval process, and the contents of the mailbox are discarded only when FTPEndRetrievalOfMessages is invoked. Only by calling this procedure can the client leave the mail retrieval mode entered via successful invocation of FTPBeginRetrievalOfMessages:

FTPEndRetrievalOfMessages: PROCEDURE [ftpuser: FTPUser];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.

Appendix D: Miscellaneous Primitives

D.1. Introduction

In addition to the primitives described in the body of this document and the preceding appendices, FTP supplies a number of less frequently used procedures, as described below.

D.2. Infrequently Used Connection Management Primitives

FTP provides three procedures for controlling communication with remote FTP Servers in a debugging context. The first, FTPSetContactSocket, specifies the remote socket at which, in subsequent calls to FTPOpenConnection, the local FTP User should expect to contact remote FTP Listeners for the purpose of manipulating either remote files, mail, or filesAndMail. Recall that file- and mail-related transactions are supported by distinct FTP Servers created by distinct FTP Listeners monitoring distinct well-known sockets. This procedure permits use of experimental FTP Listeners, which are often assigned to non standard (that is, not-so-well-known) sockets during their checkout phase. A socket number of zero resets the affected socket(s) to its(their) standard, default values (that is, 3 for files and 7 for mail):

FTPSetContactSocket: PROCEDURE [ftpuser: FTPUser, socket: LONG CARDINAL, purpose: Purpose];

Purpose: TYPE = {files, mail, filesAndMail};

The second procedure, FTPEnableTrace, causes a textual representation of all subsequent interactions between the local FTP User and the remote FTP Server to be presented to the client in zero or more calls to a writeString procedure (for example, IODefs.WriteString) it supplies. Successive STRINGs represent successive segments of the character stream describing the dialogue; STRING boundaries are insignificant. Redundant calls to FTPEnableTrace are treated as no operations. Be advised that passwords may appear in the trace:

FTPEnableTrace: PROCEDURE [ftpuser: FTPUser, writeString: PROCEDURE [STRING]];

The third procedure, FTPDisableTrace, prevents the textual representation of User/Server interaction from being reported to the client, and disassociates from the FTP User the writeString procedure supplied by the client in a previous call to FTPEnableTrace. Redundant calls to FTPDisableTrace are treated as no operations:

FTPDisableTrace: PROCEDURE [ftpuser: FTPUser];

D.3. Infrequently Used File Transfer Primitives

FTP provides three procedures that supplement the primary file transfer procedures described elsewhere. The first, FTPTransferFile, retrieves from the remote file system addressed by srcFtpuser and stores (under the name dstFile) in the remote file system addressed by dstFtpuser a copy of the remote file the name of which is specified by srcFile and the type of which is specified by fileType--text or binary. It also returns the size in bytes, byteCount, of the transferred file. In rare cases, the fileType parameter supplied by the client is used by the source FTP Server to disambiguate between two like-named files of different types. The client may (and often does) report the file’s type as unknown, in which case the remote FTP Server must select a file without it. In any case, the destination FTP Server uses the file type reported by the source FTP Server in determining how to store the file in its file system (for example, on Maxc, text files are stored as 7-bit bytes, binary files as 8-bit bytes) Even though data are double buffered as they move from source to destination host, because of input and output interference on the Ether, throughput is currently very low compared to that achieved by using FTPRetrieveFile and FTPStoreFile:

FTPTransferFile: PROCEDURE [srcFtpuser: FTPUser, srcFile: STRING, dstFtpuser: FTPUser, dstFile: STRING, fileType: FileType,
transferFile: POINTER TO TransferFile,
transferFileData: UNSPECIFIED] RETURNS [byteCount: LONG CARDINAL];

FileType: TYPE = {text, binary, unknown};

TransferFile: TYPE = PROCEDURE [transferFileData: UNSPECIFIED,
receiveBlock: PROCEDURE [UNSPECIFIED, POINTER, CARDINAL] RETURNS [CARDINAL],
receiveBlockData: UNSPECIFIED,
sendBlock: PROCEDURE [UNSPECIFIED, POINTER, CARDINAL],
sendBlockData: UNSPECIFIED];

Exceptions: connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, illegalFilename, noSuchFile, fileAlreadyExists, fileBusy, noRoomForFile, fileDataError, errorBlockInDumpFile, unrecognizedDumpFileBlock, dumpFileBlockTooLong, dumpFileCheckSumInError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence, fileGroupDesignatorUnexpected, filenameUnexpected.

Rather than use the local file system as a way station between the remote source and destination file systems, FTPTransferFile immediately outputs to the destination FTP Server each successive segment of the file it inputs from the source FTP Server. The task of transferring the contents of the file from source to destination is normally performed by an FTP-provided procedure of type TransferFile. The client can examine and/or modify the contents of the file as it passes from source to destination by supplying its own implementation of this procedure. The client exercises this option by specifying a transferFile procedure and arbitrary transferFileData, to be passed by FTP as an argument to that procedure. If transferFile is NIL, FTP supplies its own implementation, which simply double-buffers the contents of the file as it passes it unexamined and unchanged to the destination.

The client’s transferFile procedure consumes successive segments of the file in turn using an FTP-provided procedure, receiveBlock. The client supplies receiveBlock with the receiveBlockData supplied by FTP and the location and length in words of a buffer into which the next segment is to be placed. In response, receiveBlock returns the segment left-adjusted in the buffer, along with its length in bytes. ReceiveBlock eventually signals end of file by returning a byte count of zero.

The client’s transferFile procedure produces successive segments of the file in turn, using a second FTP-provided procedure, sendBlock. The client supplies sendBlock with the sendBlockData supplied by FTP and the location and length in bytes of the next segment. TransferFile eventually signals end of file by calling sendBlock a final time with a byte count of zero.

The input and output functions performed by receiveBlock and sendBlock, respectively, are completely independent. The client’s transferFile procedure may consume and produce the incoming and outgoing streams in any manner it sees fits. Its only responsibilities are to provoke (eventually) an end-of-file indication from receiveBlock and signal an end-of-file indication to sendBlock.

Once the file has been transferred, the client may invoke the FTPNoteFilenameUsed primitive described below to determine the fully qualified absolute and/or virtual filenames used by the remote source and destination FTP Servers. The client can effect the transfer of a whole group of remote files by using FTPTransferFile (to transfer a single file) in conjunction with the FTPEnumerateFiles described in Section 3.4 or FTPInventoryDumpFile procedure described in Appendix B.2 (to enumerate or inventory the source files to be transferred). FTPTransferFile can also be used to construct remote dump files, as described in Appendix B.

The second procedure, FTPNoteFilenameUsed, returns the fully qualified absolute and/or virtual filename used by the remote FTP Server in the immediately preceding FTPStoreFile, FTPRetrieveFile, FTPDeleteFile, FTPInventoryDumpFile, or FTPTransferFile operation. For example, if the client had defaulted the version number in the remote filename it supplied to FTPStoreFile, and if the remote FTP Server, therefore, had created a new version of an already existing file, FTPNoteFilenameUsed could be employed by the client to determine the version number assigned by the Server. Any manipulation of the FTP User between execution of the target store, retrieve, delete, inventory, or transfer operation and invocation of FTPNoteFilenameUsed may invalidate the information the primitive returns. If absoluteFilename is specified (that is, non-NIL), the primitive returns a fully-qualified absolute filename in the STRING supplied by the client. If virtualFilename is specified (that is, non-NIL), the primitive returns a fully qualified virtual filename in the STRINGs supplied by the client. The reader is referred to Section 1.3 in this document for a discussion of virtual filenames and their use:

FTPNoteFilenameUsed: PROCEDURE [ftpuser: FTPUser, absoluteFilename: STRING, virtualFilename: VirtualFilename];

VirtualFilename: TYPE = POINTER TO VirtualFilenameObject;

VirtualFilenameObject: TYPE = RECORD [device, directory, name, version: STRING];

The third procedure, FTPSetBufferSize, alters the size of the buffers that local FTP Users and Servers use to transfer data between the file and communication systems. The default value is four. Since it is the ReadFile and WriteFile file primitives described in Appendix E that actually make use of this parameter, if the client supplies its own implementation of either or both primitives, FTPSetBufferSize will have no effect upon the corresponding file operation(s). The procedure accepts as its only parameter the size, pages, of the buffers in 256-word pages. The new buffer size takes effect with the next file transfer:

FTPSetBufferSize: PROCEDURE [pages: CARDINAL];

D.4. Other Primitives

FTP provides one procedure, FTPCatchUnidentifiedErrors, for specifying whether FTP should catch, and report as an unidentifiedError via FTPError, signals raised unexpectedly by the Mesa System (for example, StringBoundsFault). The procedure accepts as its only parameter the new switch setting, which takes effect at once. The default value is TRUE (that is, catch such errors):

FTPCatchUnidentifiedErrors: PROCEDURE [setting: BOOLEAN];