Heading:qk40(635)
Mesa FTP Functional Specificationy756qk40\b33B
Page Numbers: Yes  X: 527  Y: 10.5"  First Page: 20qk40
Appendix A:  Error Summaryx4e24k54\f5b26B
A.1.  Introductionx4e12k54\b18B
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.x4e12jk62\98f6b8f0B3f6b8f0B66f6b8f0B41f1 6f0 2f6b7f0B38f1 2f0 48f6b8f0B
A.2.  Errorsx4e12k54\b12B
communicationPrimitivesNotSpecifiedx4e12jk54\f6b
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.x4e6jk62\28f6b13f0B4f6b17f0B7f6b23f0B243f6b26f0B
connectionAlreadyEstablishedx4e12jk54\f6b
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.x4e6jk62\28f6b17f0B17f6b7f0B190f6b18f0B32f6b13f0B
connectionClosedx4e12jk54\f6b
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.x4e6jk62\355f6b18f0B100f6b17f0B241f6b18f0B
connectionNotOpenedForFilesx4e12jk54\f6b
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.x4e6jk62\201f6b18f0B29f6b17f0B6f6b7f0B21f6b5f0B4f6b12f0B
connectionNotOpenedForMailx4e12jk54\f6b
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.x4e6jk62\201f6b18f0B29f6b17f0B6f6b7f0B21f6b4f0B4f6b12f0B
connectionRejectedx4e12jk54\f6b
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.x4e6jk62\35f6b17f0B201f6b17f0B
connectionTimedOutx4e12jk54\f6b
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.x4e6jk62\293f6b18f0B111f6b17f0B
credentialsMissingx4e12jk54\f6b
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.x4e6jk62\219f6b17f0B
dumpFileBlockTooLongx4e12jk54\f6b
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.x4e6jk62\38f6b20f0B4f6b15f0B
dumpFileCheckSumInErrorx4e12jk54\f6b
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.x4e6jk62\38f6b20f0B4f6b15f0B
duplicateMailboxExceptionx4e12jk54\f6b
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.x4e6jk62\54f6b32f0B
duplicateProtocolParameterx4e12jk100\f6b
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.x4e6jk62
errorBlockInDumpFilex4e12jk54\f6b
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.x4e6jk62\31f6b20f0B4f6b15f0B
fileAlreadyExistsx4e12jk54\f6b
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.x4e6jk62\25f6b12f0B174f6b13f0B44f6b12f0B44f6b10f0B
fileBusyx4e12jk54\f6b
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.x4e6jk62
fileDataErrorx4e12jk54\f6b
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.x4e6jk62
fileGroupDesignatorUnexpectedx4e12jk54\f6b
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.x4e6jk62\28f6b16f0B4f6b13f0B17f6b10f0B160f6b17f0B46f6b15f0B4f6b13f0B
filenameUnexpectedx4e12jk54\f6b
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.x4e6jk62\28f6b15f0B2f6b13f0B5f6b13f0B66f6b10f0B55f6b17f0B126f6b18f0B1f6b6f0B27f6b6f0B4f6b11f0B
filePrimitivesNotSpecifiedx4e12jk54\f6b
A client error signalled by FTPCreateUser or FTPCreateListener.  The filePrimitives parameter supplied to one of these procedures is NIL.x4e6jk62\28f6b13f0B4f6b17f0B7f6b14f0B
filesModuleNotLoadedx4e12jk54\f6b
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.x4e6jk62\28f6b17f0B4f6b17f0B26f6b7f0B4f6b5f0B4f6b12f0B10f6b12f0B4f6b14f0B
functionNotImplementedx4e12jk54\f6b
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.x4e6jk62
illegalBooleanParameterx4e12jk54\f6b
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.x4e6jk62\176f1 4f0 5f1 5f0
illegalFileAttributex4e12jk54\f6b
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.x4e6jk62
illegalFilenamex4e12jk54\f6b
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.x4e6jk62
illegalFileTypex4e12jk54\f6b
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.x4e6jk62\206f1 4f0 5f1 6f0
illegalProcedureCallSequencex4e12jk54\f6b
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.x4e6jk62
illegalProtocolParameterListx4e12jk54\f6b
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.x4e6jk62
illegalProtocolSequencex4e12jk54\f6b
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.x4e6jk62
incorrectPrimaryPasswordx4e12jk54\f6b
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.x4e6jk62\86f6b8f0B39f6b17f0B91f6b17f0B
incorrectSecondaryPasswordx4e12jk54\f6b
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.x4e6jk62\88f6b8f0B39f6b17f0B91f6b17f0B
inputDiscontinuityUnexpectedx4e12jk54\f6b
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.x4e6jk62
mailModuleNotLoadedx4e12jk54\f6b
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.x4e6jk62\28f6b17f0B26f6b7f0B4f6b4f0B4f6b12f0B10f6b11f0B4f6b13f0B
mailPrimitivesNotSpecifiedx4e12jk54\f6b
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.x4e6jk62\28f6b17f0B7f6b14f0B236f6b17f0B5f6b18f0B
messageLongerThanAdvertisedx4e12jk100\f6b
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.x4e6jk62\54f6b25f0B2f6b22f0B5f6b25f0B
messageShorterThanAdvertisedx4e12jk54\f6b
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.x4e6jk62\54f6b25f0B2f6b22f0B5f6b25f0B
missingMessageLengthx4e12jk54\f6b
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.x4e6jk62\54f6b22f0B4f6b25f0B
missingProtocolParameterx4e12jk54\f6b
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.x4e6jk62
noConnectionEstablishedx4e12jk54\f6b
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.x4e6jk62\212f6b17f0B
noNameLookupResponsex4e12jk54\f6b
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.x4e6jk62\35f6b17f0B231f6b17f0B
noRoomForFilex4e12jk54\f6b
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.x4e6jk62\25f6b12f0B172f6b13f0B44f6b12f0B
noRouteToNetworkx4e12jk100\f6b
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.x4e6jk62\216f6b18f0B30f6b17f0B
noSuchFilex4e12jk54\f6b
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.x4e6jk62
noSuchHostx4e12jk54\f6b
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.x4e6jk62\35f6b17f0B17f6b4f0B130f6b17f0B
noSuchMailboxx4e12jk54\f6b
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.x4e6jk62\26f6b27f0B16f6b11f0B121f6b27f0B
noSuchPrimaryUserx4e12jk54\f6b
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.x4e6jk62\86f6b4f0B44f6b17f0B139f6b17f0B
noSuchRecipientNumberx4e12jk54\f6b
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.x4e6jk62\54f6b32f0B
noSuchSecondaryUserx4e12jk54\f6b
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.x4e6jk62\88f6b4f0B44f6b17f0B139f6b17f0B
noValidRecipientsx4e12jk54\f6b
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.x4e6jk62\25f6b32f0B133f6b23f0B79f6b25f0B
outputDiscontinuityUnexpectedx4e12jk54\f6b
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.x4e6jk62
protocolParameterListMissingx4e12jk54\f6b
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.x4e6jk62
protocolVersionMismatchx4e12jk54\f6b
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.x4e6jk62\52f6b17f0B4f6b18f0B
queueInconsistentx4e12jk54\f6b
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.x4e6jk62
requestedAccessDeniedx4e12jk54\f6b
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.x4e6jk62\316f6b17f0B
stringTooLongx4e12jk54\f6b
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.x4e6jk62\143f1 6f0
unexpectedEndOfFilex4e12jk100\f6b
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.x4e6jk62
unidentifiedErrorx4e12jk54\f6b
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.x4e6jk62
unidentifiedPermanentErrorx4e12jk54\f6b
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.x4e6jk62
unidentifiedTransientErrorx4e12jk54\f6b
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.x4e6jk62
unrecognizedDumpFileBlockx4e12jk100\f6b
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.x4e6jk62\38f6b20f0B4f6b15f0B
unrecognizedMailboxExceptionErrorCodex4e12jk54\f6b
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.x4e6jk62\54f6b32f0B
unrecognizedProtocolErrorCodex4e12jk54\f6b
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.x4e6jk62
unrecognizedProtocolParameterx4e12jk54\f6b
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.x4e6jk62
Appendix B:  Dump Primitivesx4e24k792\f5b28B
B.1.  Introductionx4e12k54\b18B
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.x4e12jk54\128i10I47i8I32i7I
B.2.  Inventory Primitivesx4e12k54\b26B
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:x4e12jk54\28f6b20f0B109f6b14f0B71f6b11f0B15f6b15f0B175f1 1f0
FTPInventoryDumpFile: PROCEDURE [ftpuser: FTPUser, remoteDumpFile: STRING, intent: DumpFileIntent,
processFile: PROCEDURE [UNSPECIFIED, STRING, FileInfo],
processFileData: UNSPECIFIED];l4269d3740x4e12k54\f6b22f1 9f6 36f1 6f6 39f1 9f6 2f1 11f6 2f1 6f0 10f6 20f1 11f6
DumpFileIntent: TYPE = Intent[enumeration..retrieval];l4269d3740x4e12k54\f6b16f1 4f6
Intent: TYPE = {enumeration, retrieval, deletion, renaming, unspecified};l4269d3740x4k54\f6b8f1 4f6
FileInfo: TYPE = POINTER TO FileInfoObject;l4269d3740x4k54\f6b10f1 4f6 3f1 10f6
FileInfoObject: TYPE = RECORD [
fileType: FileType, byteSize: CARDINAL, byteCount: LONG CARDINAL, creationDate, writeDate, readDate, author: STRING];l4269d3740x4k54\f6b16f1 4f6 3f1 6f6 33f1 8f6 13f1 13f6 45f1 6f6
FileType: TYPE = {text, binary, unknown};l4269d3740x4k54\f6b10f1 4f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, illegalFilename, noSuchFile, fileBusy, fileDataError, errorBlockInDumpFile, unrecognizedDumpFileBlock, dumpFileBlockTooLong, dumpFileCheckSumInError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence, fileGroupDesignatorUnexpected.l4269d3740x4e12k54\f1u10f7U
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.x4e12jk54\16f7b4f0B4f6b11f0B33f6b17f0B17f6b11f0B48f6b8f0B8f6b12f0B
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:x4e12jk54\4f6b6f0B390f6b11f0B69f6b6f0B
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.l4269d3739x4e12jk54\17f6b11f0B286f6b11f0B
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.l4269d3739x4e12jk54\17f6b9f0B187f6b11f0B107f6b15f0B33f1 4b9B13b15B189f0 70f6b11f0B61f6b15f0B
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.  x4e12jk80\67f6b19f0B
B.3.  Construction Primitivesx4e12k54\b29B
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):  x4e12jk80\76f6b16f0B31f6b14f0B49f6b12f0B76f6b12f0B63f6b9f0B41f6b12f0B3f6b10f0B71i27I3f1 4b9B13b12B184f0 185f6b12f0B98f6b14f0B
FTPBeginDumpFile: PROCEDURE [ftpuser: FTPUser, remoteDumpFile: STRING]; l4269d3740x4e12k54\f6b18f1 9f6 36f1 6f6 3B
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, illegalFilename, fileAlreadyExists, fileBusy, noRoomForFile, fileDataError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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:x4e12jk80\22f6b14f0B213f6b16f0B1b
FTPEndDumpFile: PROCEDURE [ftpuser: FTPUser]; l4269d3740x4e12k54\f6b16f1 9f6 21B
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noRoomForFile, fileDataError, noConnectionEstablished, connectionNotOpenedForFiles, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
Appendix C:  Mail Primitivese24k792(2116)\f5b
C.1.  Introductione12k40\b
Besides its file-related primitives, FTP supplies a family of procedures for delivering mail to and retrieving mail from remote mailboxes, as described below.x4e12jk40\158b
C.2.  Delivery Primitivese12k40\b
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:x4e12jk40\172f6b25f0B431f6b23f0B
FTPBeginDeliveryOfMessage: PROCEDURE [ftpuser: FTPUser];l4269d3740x4e12k54(635)\f6b27f1 9f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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.x4e12jk40(2116)\22f6b25f0B53f6b25f0B122f6b15f0B5f6b7f0B145b
FTPSendRecipientOfMessage: PROCEDURE [ftpuser: FTPUser, mailboxName: STRING,
mailboxHostName: STRING _ NIL, dmsName: STRING _ NIL];l4269d3740x4e12k54(635)\f6b27f1 9f6 33f1 6f6 19f1 12f6 11f1 12f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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:x4e12jk40(2116)\21f6b32f0B242f6b15f0B152f6b14f0B41f1 6f0 2f6b12f0B94f1 567b12B21f0 2i4I8f6b25f0B78i10I73f6b32f0B37f6b15f0B91f6b13f0B100f6b25f0B111b
FTPIdentifyNextRejectedRecipient: PROCEDURE [ftpuser: FTPUser, errorMessage: STRING] RETURNS [recipientNumber: CARDINAL, recipientError: RecipientError];l4269d3740x4e12k54(635)\f6b34f1 9f6 34f1 6f6 2f1 7f6 19f1 8f6
RecipientError: TYPE = {noSuchMailbox, noForwardingProvided, unspecifiedTransientError, unspecifiedPermanentError, unspecifiedError};l4269d3740x4e12k54\f6b16f1 4f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noValidRecipients, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
Old Exceptions:  noSuchForwardingHost, noSuchDmsName.l4269d3740x4e12k54\f1u14f7U
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):  x4e12jk40(2116)\22f6b21f0Bi2I53i1I220f6b6f0Bi1I26f6b9f0Bi1I211f1 2f0 4b
FTPSendBlockOfMessage: PROCEDURE [ftpuser: FTPUser, source: POINTER, byteCount: CARDINAL];l4269d3740x4e12k54(635)\f6b23f1 9f6 28f1 7f6 13f1 8f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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:  x4e12jk40(2116)\21f6b23f0B147f6b25f0B3b
FTPEndDeliveryOfMessage: PROCEDURE [ftpuser: FTPUser];l4269d3740x4e12k54(635)\f6b25f1 9f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
C.3.  Retrieval Primitivese12k40(2116)\b
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):x4e12jk40\120f6b27f0Bi1I107f6b11f0B122f6b17f0B409f6b25f0B45b
FTPBeginRetrievalOfMessages: PROCEDURE [ftpuser: FTPUser, mailboxName: STRING];l4269d3740x4e12k54(635)\f6b29f1 9f6 33f1 6f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, credentialsMissing, noSuchPrimaryUser, noSuchSecondaryUser, incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied, noSuchMailbox, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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):x4e12jk40(2116)\22f6b22f0B98f6b27f0B3f6b22f0B32f6b9f0B38i1I100f1 224b25B27f0 70f6b11f0Bi1I73f6b9f0B21f6b12f0B66f1 6f0 72f6b6f0B24f6b7f0B109b
FTPIdentifyNextMessage: PROCEDURE [ftpuser: FTPUser, messageInfo: MessageInfo];l4269d3740x4e12k54(635)\f6b24f1 9f6
MessageInfo: TYPE = POINTER TO MessageInfoObject;l4269d3740x4e12k54\f6b13f1 4f6 3f1 10f6
MessageInfoObject: TYPE = RECORD [byteCount: LONG CARDINAL, deliveryDate: STRING, opened, deleted: BOOLEAN];l4269d3740x4k54\f6b19f1 4f6 3f1 6f6 13f1 13f6 16f1 6f6 19f1 7f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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):   x4e12jk40(2116)\21f6b25f0Bi2I80f6b22f0Bi3f6bI25f0B33f6b15f0B110f1 215b22B1f0 58i1I43f6b22f0B111f6b11f0B20i8I2f6b12f0B65i8I2f6b15f0B267f1 2f0 5b
FTPRetrieveBlockOfMessage: PROCEDURE [ftpuser: FTPUser, destination: POINTER, maxWordCount: CARDINAL] RETURNS [actualByteCount: CARDINAL];l4269d3740x4e12k54(635)\f6b27f1 9f6 33f1 7f6 16f1 8f6 2f1 7f6 19f1 8f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
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:   x4e12jk40(2116)\22f6b25f0B72f6b27f0B5f6b25f0B147f6b25f0B127f6b27f0B4b
FTPEndRetrievalOfMessages: PROCEDURE [ftpuser: FTPUser];l4269d3740x4e12k54(635)\f6b27f1 9f6
Exceptions:  connectionTimedOut, connectionClosed, noRouteToNetwork, noConnectionEstablished, connectionNotOpenedForMail, illegalProcedureCallSequence.l4269d3740x4e12k54\f1u10f7U
Appendix D:  Miscellaneous Primitivesx4e24k792\f5b37B
D.1.  Introductionx4e12k54\b18B
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.x4e12jk54
D.2.  Infrequently Used Connection Management Primitivesx4e12k54\b56B
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):x4e12jk54\120f6b19f0B23f6b6f0B34f6b17f0B75f6b7f0B31f6b5f0B2f6b4f0B5f6b12f0B1f1 161f0 277f6b5f0B11f6b4f0B
FTPSetContactSocket: PROCEDURE [ftpuser: FTPUser, socket: LONG CARDINAL, purpose: Purpose];l4269d3740x4e12k54\f6b21f1 9f6 28f1 13f6 20B
Purpose: TYPE = {files, mail, filesAndMail};l4269d3740x4e12k54\f6b9f1 4f6
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:x4e12jk54\22f6b14f0B175f6b11f0B25f6 18f0 27f1 7f0 80f1 6f0 48f6b17f0B32f1 49f0
FTPEnableTrace: PROCEDURE [ftpuser: FTPUser, writeString: PROCEDURE [STRING]];l4269d3740x4e12k54\f6b16f1 9f6 33f1 9f6 2f1 6f6
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:x4e12jk54\21f6b15f0B140f6b11f0B56f6b14f0B22f6b15f0B
FTPDisableTrace: PROCEDURE [ftpuser: FTPUser];l4269d3740x4e12k54\f6b17f1 9f6
D.3.  Infrequently Used File Transfer Primitivesx4e12k80\b
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:x4e12jk54\116f6b15f0B53f6b10f0B28f6b7f0B41f6b10f0B61f6b7f0B39f6b8f0B2f6b4f0B4f6b6f0B38f6b9f0B47f6b8f0B191f6b7f0B308f1 208b15B5b12f0B
FTPTransferFile: PROCEDURE [srcFtpuser: FTPUser, srcFile: STRING, dstFtpuser: FTPUser, dstFile: STRING, fileType: FileType,
transferFile: POINTER TO TransferFile,
transferFileData: UNSPECIFIED] RETURNS [byteCount: LONG CARDINAL];l4269d3740x4e12k54\f6b17f1 9f6 32f1 6f6 32f1 8f6 34f1 10f6 33f1 11f6 2f1 7f6 13f1 13f6
FileType: TYPE = {text, binary, unknown};l4269d3740x4e12k54\f6b10f1 4f6
TransferFile: TYPE = PROCEDURE [transferFileData: UNSPECIFIED,
receiveBlock: PROCEDURE [UNSPECIFIED, POINTER, CARDINAL] RETURNS [CARDINAL],
receiveBlockData: UNSPECIFIED,
sendBlock: PROCEDURE [UNSPECIFIED, POINTER, CARDINAL],
sendBlockData: UNSPECIFIED];l4269d3740x4k54\f6b14f1 4f6 3f1 9f6 20f1 11f6 16f1 9f6 2f1 11f6 2f1 7f6 2f1 8f6 2f1 7f6 2f1 8f6 21f1 11f6 13f1 9f6 2f1 11f6 2f1 7f6 2f1 8f6 18f1 11f6
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.l4269d3740x4e12k54\f1u10f7U
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.x4e12jk54\111f6b15f0B262f6b12f0B210f6b12f0B25f6b16f0B60f6b12f0B4f1 3f0
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.x4e12jk54\13f6b12f0B93f6b12f0B23f6b12f0B10f6b16f0B45i8I72f6b12f0B72i9I2f6b12f0B
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.x4e12jk54\13f6b12f0B100f6b9f0B23f6b9f0B10f6b13f0B45i8I23f6b12f0B43f6b9f0B40f6b
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. x4e12jk54\44f6b12f0B5f6b9f0B58f6b12f0B183f6b12f0B41f6b9f0B2f6b
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.x4e12jk54\62f6b19f0B196i5I26f6b15f0B52f6b18f0B25f6b1f0B2f6b22f0B35f6b1f0B65f6b15f0B
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:x4e12jk54\22f6b19f0B122f6b12f0B2f6b15f0B2f6b13f0B2f6b20f0B5f6b15f0B111f6b12f0B98f6b19f0B231f6b19f0B59f6b16f0B28f1 3f0 68f1 6f0 29f6b15f0B28f1 3f0 67f1 6f0
FTPNoteFilenameUsed: PROCEDURE [ftpuser: FTPUser, absoluteFilename: STRING, virtualFilename: VirtualFilename];l4269d3740x4e12k54\f6b21f1 9f6 38f1 6f6
VirtualFilename: TYPE = POINTER TO VirtualFilenameObject;l4269d3740x4e12k54\f6b17f1 4f6 3f1 10f6
VirtualFilenameObject: TYPE = RECORD [device, directory, name, version: STRING];l4269d3740x4k54\f6b23f1 4f6 3f1 6f6 36f1 6f6 2f0B
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:x4e12jk54\21f6b16f0B160f1 16b8B5b9B159b16B61f0 57f6b5f0B
FTPSetBufferSize: PROCEDURE [pages: CARDINAL];l4269d3740x4e12k54\f6b18f1 9f6 9f1 8f6
D.4.  Other Primitivesl3370d2998x4e12k54\b22f6
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):x4e12jk54\28f6b26f0B60f6b17f0B5f6b8f0B63f6b17f0B63f6b7f0B52f1 4f0
FTPCatchUnidentifiedErrors: PROCEDURE [setting: BOOLEAN];l4269d3740x4e12k54\f6b28f1 9f6 11f1 7f6