MULTICS TECHNICAL BULLETIN MTB-742-03
To: MTB Distribution
From: Michael S. Flegel
Date: September 17, 1987
Subject: MOWSE - Background File Transfer (BFT) Facility
-----------------------------------
This document provides an overview of the Background File
Transfer facility and user interface, which uses the Multics
Online Work Station Environment (MOWSE). There are four MTBs
that describe the design and implementation of MOWSE and some
applications that use MOWSE facilities. The four MTBs are:
MTB-740 MOWSE Overview
MTB-741 MOWSE Design, Commands and Subroutines
MTB-742 MOWSE Background File Transfer (BFT) Facility
MTB-744 MOWSE Terminal Emulator
(rev-00): April 7, 1986. Initial design.
(rev-01): June 3, 1986. General design changes due to forum
discussions about rev-00.
(rev-02): February 17, 1987. Final design revision for MR12.1
(rev-03): September 11, 1987. Implementation of multiple entry |
queues and starname expansion. |
-----------------------------------
Comments on this MTB should be sent to the author -
via Multics mail to:
Flegel.Multics
via telephone to:
ACTC (403)-284-6400
Michael S. Flegel
via forum on System-M to:
>udd>m>jms>mtgs>wwg
_________________________________________________________________
Multics project internal documentation; not to be reproduced or
distributed outside the Multics project.
BFT MTB-742-03
TABLE OF CONTENTS
Section Page Subject
======= ==== =======
1 1 Introduction
2 1 Overview
3 3 Design of Background File Transfer
3.1 3 . . BFT Queueing Strategy
3.1.1 4 . . . . Enqueueing
3.1.2 4 . . . . Dequeueing
3.1.3 4 . . . . Starname Matching
3.2 5 . . BFT MOWSE Minor Capabilities
3.3 7 . . BFT Database Description
3.4 8 . . BFT Minor Capability Protocol
3.4.1 9 . . . . PC to Multics Protocol
3.4.2 10 . . . . Multics to PC Protocol
3.4.3 11 . . . . Recover Protocol
3.5 12 . . Minor Capability Description
3.6 16 . . Differences Between the PC and Multics
Implementations
4 17 User Information
4.1 17 . . Establishing the BFT Environment
4.2 18 . . BFT Subroutine Library
4.2.1 18 . . . . Multics
4.2.2 26 . . . . PC
4.3 33 . . BFT Command Interface
BFT MTB-742-03
1. Introduction
The Background File Transfer facility (BFT) operates in the
Multics Online Work Station Environment (MOWSE). The reader
should be familiar with MOWSE (see MTB 740) before reading this
document.
2. Overview
BFT provides a facility for transferring files between two
computers by means of cooperating processes running on each of
the computers. This facility is intended to operate as a
background process on each computer, to allow the user to run
applications as the transfer is taking place. As a result of
this, BFT will not have access to its computer's user input and
output facilities. As a MOWSE application, BFT makes use of
MOWSE facilities for user I/O and communications.
Functionality for BFT exists on both systems, so transfer |
operations may be initiated from either system. |
|
BFT will maintain the file transfer queue on Multics as to the |
Multics system provides better queue manipulation facilities and, |
most importantly, a considerably higher level of data integrity. |
All transfer requests, irregardless of which system initiated the |
request, will be maintained by the Multics counterpart of BFT. |
The queue size will be restricted only by limitations placed on |
Multics addressing - a total of 1 megabyte - and the actual size |
of each queue entry. |
There is allowed a maximum of two simultaneous file transfers at
any given time due to file constraints on the PC, one in each
direction. This involves some arbitration of which transfers may
occur at any given time. Transfer arbitration will be handled |
completely by the system which maintains the queue - Multics. |
This is because only the system with the queue will know whether |
or not there is a request pending in a specific direction. |
Whenever a transfer operation has been completed in a one |
direction, the queue will be searched for another entry which |
requires the same direction of transfer. Thus transfering |
simultaneously in both directions. |
All external input to the BFT program will occur through a single
MOWSE entrypoint. This MOWSE entrypoint will be called via
entrypoints which formulate the requests to BFT.
MTB-742-03 BFT
Note: Swapping floppies in the middle of a file transfer may
have disasterous results (loss of transfer and possibly
destroying the disk that it was replaced with). Once again it is
up to the user to remain aware of what is going on to ensure a
safe transfer.
Any "background" errors (i.e. errors that cannot be returned
immediately through error codes) will be reported to
ws_$put_backgroud_error_message.
BFT MTB-742-03
3. Design of Background File Transfer
The following sections provide a brief overview of the general
implementation of the BFT minor capabilities. Differences in the
Multics and PC implementations will be discussed later in this
document.
|
|
3.1. BFT Queueing Strategy |
|
|
|
The primary changes to this version of BFT is that multiple |
entries will be allowed to be submitted, from either the PC or |
the Multics end, as requests for transfer. This will be |
accomplished by converting the previous strategy of function to a |
master-slave relationship between the PC and Multics parts with |
Multics BFT being the master. That is, all transfer requests |
must eventually go through the Multics BFT before they can be |
serviced, even if the request originated on the PC end. This is |
because of the higher degree of dataa integrity and queue |
manipulation facilities that Multics has to offer. |
|
The queue will be maintained within the segment: |
|
[hd]>Person_id.bft |
|
The segment will be formatted as follows: |
|
------------ |
| HEADER | |
------------ |
| ELEMENT-1 | |
------------ |
| ELEMENT-2 | |
------------ |
| ... | |
------------ |
| ELEMENT-n | |
------------ |
|
For complete information on the formats of the HEADER and |
ELEMENT, refer to the section on "BFT Database Description". |
|
|
|
3.1.1. Enqueueing |
MTB-742-03 BFT
When an transfer request is made, the request will be chained |
into the appropriate queue and physically placed into the queue |
segment. A free_list is maintained by the header and the ELEMENT |
will be placed at the first entry of the free_list. |
|
|
|
3.1.2. Dequeueing |
|
|
When a transfer direction opens up, a pending ELEMENT in the same |
direction is located in the queue, but the ELEMENT is left in the |
queue until the transfer has completed. This is to facilitate |
handling of transfer interruptions and maintains a place for the |
information while the transfer is proceeding. When the transfer |
completes, the ELEMENT is extracted from the segment and the |
space is placed into the free list. |
|
If the element is at the end of the segment, cleanup is initiated |
on the segment. The segment is scanned from back to front |
looking for the last entry which is allocated. If the total size |
of the contiguous records exceed 1 page (4096 bytes) and is not |
the first page of ELEMENTS in the entire segment, the page is |
removed from the segment and the free_list is rechained. This |
keeps the minimum amount of data space required to handle the |
queues. |
|
|
|
3.1.3. Starname Matching |
|
|
Because BFT is now capable of handling multiple entries in the |
queue, the functionality will be added for star matching on each |
system. Both systems provide a simple interface which will match |
segments within a specified directory, these facilities will be |
used. |
|
Each matching entry will be transmitted separately to the |
ADD_TO_STORE_QUEUE or ADD_TO_FETCH_QUEUE Multics minor |
capabilities for independent handling of each entry. |
BFT MTB-742-03
3.2. BFT MOWSE Minor Capabilities
This category encompasses the BFT minor capabilities. They are
components of the MOWSE major capability "BFT". These
capabilities will reside both on the local and remote machines
due to the parallel nature of BFT. Following is a list of the
minor capabilities used to implement BFT. For a description of
these capabilities, see section 4.5.
BFT will be made up of 28 minor capabilities. Many of these
minor capabilities are not designed to be directly accessed by
the user. The design of BFT, being a MOWSE application, requires
a constant two way communication to assure that action is being
performed on both machines. Four (4) of the minor capabilities
are designed to be directly accessed by the user, and these
correspond to those which have been made available on Multics as
entrypoints (although bft_$load and bft_$unload exist as
entrypoints, they are not actual minor capabilities). The minor
capabilities are listed below:
ADD_TO_FETCH_QUEUE |
ADD_TO_STORE_QUEUE |
BFT_SHUTDOWN |
CHECK_FILE_LENGTH |
INITIATE_FETCH |
INITIATE_STORE |
POSITION_FILE_POINTER |
READ_ERROR |
RECEIVE_DATA |
RECEIVE_EOF |
RECOVER_FETCH |
RECOVER_STORE |
SEND_DATA |
STORE_ACKNOWLEDGE |
WRITE_ERROR |
In addition to these minor capabilities, there will also be
supplied the following minor capabilities as required by MOWSE.
BUFFER_OVERFLOW
CONNECT_RESPONSE
CONNECT_REQUEST
DISCONNECT_RESPONSE
DISCONNECT_REQUEST
EXECUTE_COMMAND_REPLY
FAIL_CAPABILITY
MTB-742-03 BFT
QUERY_REPLY
RESET_APPLICATION
RESUME_APPLICATION
GET_STATUS
SUSPEND_APPLICATION
WAKE_UP
BFT MTB-742-03
3.3. BFT Database Description
*
The queue will be maintained within a segment on Multics located |
at [hd]>PersonId.bft. As is true with the user's |
PersonId.profile, the deletion of the PersonId.bft will cause all |
bft transfers and outstanding requests to be terminated |
abnormally. |
|
There will be no PC queue - all PC initiated requests will |
generate messages to Multics for addition and/or initiation of |
the requested transfer. |
|
On Multics, the segment will contain the following two type of |
structures: |
|
01 header, /* Q control info */ |
02 version char (8), /* Segment ID */ |
02 lockword fixed bin (71), /* Segment lock */ |
02 store_queue (4), /* Multics -> PC */ |
03 last fixed bin (35), /* Last element */ |
03 first fixed bin (35), /* Entry transferring */ |
03 file_pos fixed bin (71), /* Bytes transferred */ |
03 flags, |
04 initiated bit (1) unal, /* Store initiated */ |
04 pad bit (35) unal, |
02 fetch_queue (4), /* PC -> Multics */ |
03 last fixed bin (35), /* Last element */ |
03 first fixed bin (35), /* Entry transferring */ |
03 file_pos fixed bin (71), /* Bytes transferred */ |
03 flags, |
04 initiated bit (1) unal, /* Fetch initiated */ |
04 pad bit (35) unal, |
02 free_list fixed bin (35), /* Free entries in Q */ |
02 segment_size fixed bin (35); /* Records in segment */ |
|
01 queue, /* Queue element */ |
02 next fixed bin (35), /* Next in Q */ |
02 multics_path char (168), /* Path on Multics */ |
02 pc_path char (66), /* Drive:Path on PC */ |
02 time_id fixed bin (71), /* Time stamp id */ |
02 flags, /* Entry switches */ |
03 allocated bit (1) unal, /* Is this an entry? */ |
03 binary_sw bit (1) unal, /* Binary file_type */ |
03 pad bit (30) unal, /* Future expansion */ |
03 mbz bit (4) unal; /* System word adjust */ |
MTB-742-03 BFT
3.4. BFT Minor Capability Protocol
This section describes the flow of control between the minor
capabilities for the store, fetch, and recover sequences. |
BFT MTB-742-03
3.4.1. PC to Multics Protocol
*
*
Multics PC |
------------------------------ ---------------------------- |
|
bft fetch sc_path ds_path |
| |
V |
ADD_TO_FETCH_QUEUE <-- bft store sc_path ds_path |
(sc_path,ds_path) |
- Add to PC -> Multics queue. |
- If no PC -> Multics transfer |
- Open_ds file for transfer --> INITIATE_STORE (sc_path) |
- If error, another entry ... |
|
READ_ERROR (error_msg) <-- - If file does NOT exist |
- Close ds_path, remove entry - Else open sc_path |
- If another entry ... | |
V |
RECEIVE_DATA (data) <+> SEND_DATA () |
- Write data to ds_path -+- - Send portion of data |
|
- If error -+- - If error |
- Close ds_path | - close sc_path |
- If another entry ... | |
| |
RECEIVE_EOF () <-- - If end of file |
- Remove entry from queue | - close sc_path |
- If another entry ... | |
| |
READ_ERROR (error_msg) <+> WRITE_ERROR (error_msg) |
- Close ds_path, remove entry |
- If another entry ... |
|
INITIATE_FETCH () <-- - close sc_path |
- If another entry ... |
MTB-742-03 BFT
3.4.2. Multics to PC Protocol
*
*
Multics PC |
-------------------------- ---------------------------- |
|
bft store sc_path ds_path |
| |
V |
ADD_TO_STORE_QUEUE <-- bft fetch sc_path ds_path |
(sc_path, ds_path) |
- Add to Multics -> PC queue |
- If no Multics -> PC transfer |
- Open sc_path |
- If error, remove from queue |
- Else --> INITIATE_FETCH (ds_path) |
- Open ds_path. |
WRITE_ERROR () <-- - If error |
- Close sc_path, remove entry |
- If another entry ... |
|
STORE_ACKNOWLEDGE <-- - Else open ds_path |
| |
V |
SEND_DATA () <+> RECEIVE_DATA (data) |
- Send portion of data -+- - Write data to ds_path |
|
- If error -+- - If error |
- Close ds_path | - Close ds_path |
| |
- If end of file --> RECEIVE_EOF () |
- Remove entry from queue | - Close ds_path |
| - Prod for next entry ... |
| |
WRITE_ERROR (error_msg) <+> READ_ERROR (error_msg) |
- Close ds_path - Close sc_path |
- If another entry ... |
|
INITIATE_STORE () <-- - Prod for next entry ... |
- If another entry ... |
BFT MTB-742-03
3.4.3. Recover Protocol
*
Multics PC |
----------------------------- ------------------------ |
bft recover |
| |
V |
RECOVER_STORE () <-- bft recover |
- If empty, exit |
- Get amount transferred --> CHECK_FILE_LENGTH (ds_path) |
|
POSITION_FILE_POINTER <-- - Open ds_path and get size |
(file_size,sc_path) |
- Open source file and position |
- If error |
- If another entry ... |
- Else |
| |
V |
SEND_DATA () |
- ... |
|
WRITE_ERROR (error_msg) <-- - If error |
- Close ds_path |
|
---------------------------------------------------------------- |
|
bft recover |
| |
V |
RECOVER_FETCH () <-- bft recover |
- If empty, exit |
| |
V |
CHECK_FILE_LENGTH (ds_path) |
- Open ds_path |
- If error |
- If another entry ... |
- Get size --> POSITION_FILE_POINTER |
(file_size,sc_path) |
- Open source file |
READ_ERROR (error_msg) <-- - If error |
- Close ds_path - Position |
- If another entry ... | |
V |
SEND_DATA () |
- ... |
MTB-742-03 BFT
3.5. Minor Capability Description
Below is a description of each minor capability and what data its |
message contains. Some exits only on the Multics end, some only |
on the PC end, and others are required by MOWSE to be supported. |
|
Note that all data contained within the message is subject to |
format validity. If there is any ewrror in the format of the |
message data, appropriate action will be taken - an error message |
will be generated and recovery procedures will be invoked in |
order that the error will not affect pending requests. Errors |
will occur only to the current transfer in progress. |
MU: ADD_TO_FETCH_QUEUE (multics_path, pc_path, flags) |
MU: ADD_TO_FETCH_QUEUE (char (168), char (66), char (4)) |
|
This is a Multics only minor capability and is called when a |
request has been made by the user to transfer a file from PC |
to Multics. Multics BFT will take the data and enter it into |
the PC->Multics transfer queue for future (or immediate) |
transfer. |
|
If there are no entries for transfer pending in the |
PC->Multics direction, The PC:INITIATE_STORE minor capability |
will be invoked and the transfer procedures for the file will |
begin. |
MU: ADD_TO_STORE_QUEUE (multics_path, pc_path, flags) |
MU: ADD_TO_STORE_QUEUE (char (168), char (66), char (4)) |
|
This is a Multics only minor capability and is called when a |
request has been made by the user to transfer a file from |
Multics to PC. Multics BFT will take the data and enter it |
into the Multics->PC transfer queue for future (or immediate) |
transfer. |
|
If there are no entries for transfer pending in the |
Multics->PC direction, The PC:INITIATE_FETCH minor capability |
will be invoked and the transfer procedures for the file will |
begin. |
MU/PC: BFT_SHUTDOWN () |
MU/PC: BFT_SHUTDOWN () |
|
This is a last resort error minor capability in the event that |
an unrecoverable error has occurred (or that BFT is just |
shutting down due to the "bft unload" command). It will |
remove bft (all parts) from MOWSE. However, the queue will be |
maintained and the current transfer(s) will be interrupted. |
BFT MTB-742-03
MU/PC: CHECK_FILE_LENGTH (destination_filename) |
MU: CHECK_FILE_LENGTH (char (168)) |
PC: CHECK_FILE_LENGTH (char (66)) |
|
This routine checks the length of the destination file. If |
there is an error, on the PC side, MU:WRITE_ERROR is called; |
if an error occurs on the MU side, the queue is searched for |
the next entry. |
|
It then calls POSITION_FILE_POINTER on the appropriate system |
with the length of the file. |
MU/PC: INITIATE_FETCH (destination_filename) |
MU: INITIATE_FETCH () |
PC: INITIATE_FETCH (char (66)) |
|
On Multics, this is used to prompt for another entry from the |
PC->Multics queue that is maintained by Multics. |
|
On the PC, it informs the PC that a Multics->PC transfer is |
starting. The PC attempts to open the destination file. If |
there is an error, MU:WRITE_ERROR is called, otherwise |
MU:STORE_ACKNOWLEDGE is called to proceed with the transfer. |
MU/PC: INITIATE_STORE (source_filename) |
MU: INITIATE_STORE () |
PC: INITIATE_STORE (char (66)) |
|
On the Multics side, This is called by a PC minor capability |
in order to prompt Multics for another Multics->PC transfer |
from the queue. |
|
On the PC side, this is called when a PC->Multics transfer |
transfer is beginning to indicate the filename that is being |
transferred. |
MU/PC: POSITION_FILE_POINTER (file_size, source_filename) |
MU: POSITION_FILE_POINTER (fixed bin (35), char (168)) |
PC: POSITION_FILE_POINTER (long, char (66)) |
|
This positions the file pointer of the source_filename to the |
value indicated by file_size. If an error occurs on the PC |
side, MU:READ_ERROR will be called; if an error occurs on the |
MU side, then the queue is looked at for another entry. |
|
It then calls SEND_DATA locally to initiate the transfer from |
source to destination. |
MU/PC: READ_ERROR (error_string)
MU/PC: READ_ERROR (char (122))
MTB-742-03 BFT
This is called by the remote machine when it encountered an
error while trying to read a file. This tells the local
machine that if it there are any flags showing data transfer
from the remote to the local machine, then that flag will be
cleared, and the file that is locally opened to write to will
be closed.
In the case of MU:READ_ERROR, the appropriate PC->Multics |
queue will be searched for the next entry. |
|
In the case of PC:READ_ERROR, the MU:INITIATE_STORE capability |
will be called to prompt for the next entry to transfer. |
MU/PC: RECEIVE_DATA (input_data) |
MU/PC: RECEIVE_DATA (char (122)) |
|
This routine handles all of the incoming data that is to be |
written into the file. It removes the data from the argument |
list, and writes it to the file that is currently open for |
writing, and then executes SEND_DATA on the remote machine. |
|
MU/PC: RECEIVE_EOF () |
MU/PC: RECEIVE_EOF () |
|
This is executed when the transmission of the file is |
completed. The file that was open for writing to will be |
closed. On Multics, the transferred entry will be removed |
from the queue and the next entry will begin to be |
transferred; on the PC, MU:INITIATE_STORE will be called in |
order to prod Multics for beginning of the next transfer. |
MU: RECOVER_FETCH () |
MU: RECOVER_FETCH () |
|
This routine analyzes the PC->Multics queue and if there |
exists any entries in the queue will recover the appropriate |
transfer that was interrupted by sending MU:CHECK_FILE_LENGTH. |
MU: RECOVER_STORE () |
MU: RECOVER_STORE () |
|
This routine analyzes the Multics->PC queue and if there |
exists any entries in the queue will recover the appropriate |
transfer that was interrupted by sending PC:CHECK_FILE_LENGTH. |
MU/PC: SEND_DATA ()
MU/PC: SEND_DATA ()
BFT MTB-742-03
If the file that was open for reading is not at EOF, then it |
will read the maximum number of bytes, place it in the |
argument list, and call RECEIVE_DATA on the remote machine |
with this argument list. Otherwise if the file is at EOF, |
then RECEIVE_EOF will be executed on the remote machine, the |
file that is open for reading will be closed. |
|
If the Multics end is closing the file, the entry will be |
removed from the queue. |
MU: STORE_ACKNOWLEDGE () |
MU: STORE_ACKNOWLEDGE () |
|
This signifies that an PC:INITIATE_FETCH request was accepted, |
control will be transferred to MU:SEND_DATA and transfer of |
the file Multics->PC will begin. |
MU/PC: WRITE_ERROR (error_string) |
MU/PC: WRITE_ERROR (char (122)) |
This routine is called by the remote when an error was made
while attempting to write to a file. It tells the local
machine to clear any flags that signify that a file was being
transferred from the local machine to the remote, and to close
the file that is currently open for reading.
On the PC end of receiving the message, the MU:INITIATE_FETCH |
minor will be called in order to prod for the next entry in |
the queue. |
|
In the case of MU:WRITE_ERROR, the appropriate Multics->PC |
queue will be searched for the next entry. |
MOWSE Capabilities
The following capabilities are not used by BFT but are
included for sake of completeness:
BUFFER_OVERFLOW
CONNECT_RESPONSE
CONNECT_REQUEST
DISCONNECT_RESPONSE
DISCONNECT_REQUEST
EXECUTE_COMMAND_REPLY
FAIL_CAPABILITY
QUERY_REPLY
RESET_APPLICATION
RESUME_APPLICATION
GET_STATUS
SUSPEND_APPLICATION
WAKE_UP
MTB-742-03 BFT
3.6. Differences Between the PC and Multics Implementations
The primary difference between the implementations of bft on |
Multics and the PC is that they exist in a master/slave |
relationship where Multics is the master and the PC the slave. |
This is because Multics has been made the controller of the |
transfer queues due to the greater queue manipulation and data |
integrity facilities that Multics has to offer. This means that |
all transfer requests must go through Multics before they can |
begin. |
|
A secondary difference is that there is no "load" option to the |
PC "bft" command. Instead to load BFT on the PC the "bft_load" |
command is used.
BFT MTB-742-03
4. User Information
4.1. Establishing the BFT Environment
Before the BFT environment can be established, the MOWSE
environment must be established. BFT may then be enabled by
issuing the "bft load" command to multics MOWSE or executing
bft_load.com on the PC. Once this is done, transfers may be
initiated by user applications calling the BFT entrypoints, or by
the user invoking the BFT command.
MTB-742-03 BFT
4.2. BFT Subroutine Library
4.2.1. Multics
BFT is accessed via the following entrypoints:
bft_$load
bft_$fetch
bft_$store
bft_$cancel |
bft_$recover_fetch
bft_$recover_store
bft_$unload
BFT MTB-742-03
Multics Entry: bft_$load
Function:
Makes the BFT code resident on the PC, loads BFT into the CAT
(Capability Address Table) on both Multics and the PC, and
initializes all necessary variables.
Syntax:
dcl bft_$load entry (fixed bin (35));
call bft_$load (error_code);
Arguments:
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes signify whether or not
an error was encountered, and if so, of what variety.
(Output)
Examples:
call bft_$load (error)
MTB-742-03 BFT
Multics Entry: bft_$fetch
Function:
This entrypoint is the one used when transferring a file from
the remote machine to Multics. As with store, if a file
already exists with the destination name, it will be
overwritten.
Syntax:
dcl bft_$fetch entry (char (*), char (*), bit (36), |
fixed bin (35)); |
call bft_$fetch (source_filename, destination_filename, |
flags, error_code); |
Arguments:
source_filename
The pathname on the remote machine of the file which is to be
sent to Multics. (Input)
destination_filename
The absolute Multics pathname in which the file sent from the
remote machine is to be stored. (Input) |
flags |
A collection of bits signifying transfer characteristics. |
(Input) |
The bits of the argument are broken down as follows: |
|
01 flags, |
02 binary_sw bit (1) unal, /* Binary file_type */ |
02 mbz_1 bit (31) unal, /* Future expansion */ |
02 mbz_2 bit (4) unal; /* System word adjust */ |
|
where: |
|
binary_sw |
is the file_type of the transfer. Set to "0"b if the |
transfer is an ascii file_type and <CR>/<NL> conversions |
are required. See BFT Command Interface - Notes on |
file_types. |
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes will signify whether or
not an error was encountered, and if so, of what variety.
These errors could include such things as: source file not
found, BFT not loaded. (Output)
Examples:
call bft_$fetch ("c:userpetewonk", ">udd>multics>bob>wonk", |
flags, error); |
call bft_$fetch ("b:blat", ">udd>m>Joe>blat", flags, error); |
BFT MTB-742-03
Multics Entry: bft_$store
Function:
This entrypoint is used when a file is to be sent from Multics
and stored on the remote machine. If a file already exists on
the remote machine with the specified destination name, it
will be overwritten if possible.
Syntax:
dcl bft_$store entry (char (*), char (*), bit (36),
fixed bin (35));
call bft_$store (source_filename, destination_filename,
flags, error_code);
Arguments:
source_filename
An absolute Multics pathname of a file to be transferred to
the remote machine. (Input)
destination_filename
An absolute pathname in which the remote machine should store
the file. (Input)
flags |
A collection of bits signifying transfer characteristics. |
(Input) |
The bits of the argument are broken down as follows: |
|
01 flags, |
02 binary_sw bit (1) unal, /* Binary file_type */ |
02 mbz_1 bit (31) unal, /* Future expansion */ |
02 mbz_2 bit (4) unal; /* System word adjust */ |
|
where: |
|
binary_sw |
is the file_type of the transfer. Set to "0"b if the |
transfer is an ascii file_type and <CR>/<NL> conversions |
are required. See BFT Command Interface - Notes on |
file_types. |
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes signify whether or
not an error was encountered, and if so, of what variety.
These errors could include such things as: source file
not found, BFT not loaded. (Output)
Examples:
call bft_$store (">udd>multics>bob>wonk", "c:userbobwonk", |
flags, error); |
call bft_$store (">udd>games>chess", "c:joe", flags, error); |
MTB-742-03 BFT
Multics Entry: bft_$cancel |
|
|
Function: |
Remove the specified entry from the containing queue. |
|
|
Syntax: |
dcl bft_$cancel entry (char (*), fixed bin (35)); |
call bft_$cancel (entry_id, error_code); |
|
Arguments: |
|
entry_id |
is either a path name or the request identifier of the |
element. (Input) |
error_code |
A standard Multics error code signalling the state of the |
attempted operation. The error codes signify whether or not |
an error was encountered, and if so, of what variety. |
(Output) |
|
Examples: |
call bft_$cancel ("foo", code); |
call bft_$cancel (">udd>m>bob>foo", code); |
call bft_$cancel ("bar", code); |
call bft_$cancel ("c:tmpbar", code); |
call bft_$cancel ("173611.1", code); |
BFT MTB-742-03
Multics Entry: bft_$recover_fetch
Function:
This entrypoint is used to continue receiving a file from the
remote system after a previous fetch command was interrupted.
The length of the destination file is checked on the local
machine and the remainder of the file is transferred. *
Syntax:
dcl bft_$recover_fetch entry (fixed bin (35)); |
call bft_$recover_fetch (error_code); |
Arguments: *
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes signify whether or not
an error was encountered, and if so, of what variety. These
errors could include such things as: source file not found,
BFT not loaded. (Output)
Examples:
call bft_$recover_fetch (error) |
MTB-742-03 BFT
Multics Entry: bft_$recover_store
Function:
This entrypoint is used to continue sending a file to the
remote system after a previous store command was interrupted.
The length of the destination file is checked on the remote
system and the remainder of the file is sent. It is up to the
user to ensure the correct filenames are supplied since
undesirable results will otherwise occur.
Syntax:
dcl bft_$recover_store entry (fixed bin (35)); |
call bft_$recover_store (error_code); |
Arguments: *
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes signify whether or not
an error was encountered, and if so, of what variety. These
errors could include such things as: source file not found,
BFT not loaded. (Output)
Examples:
call bft_$recover_store (error); |
BFT MTB-742-03
Multics Entry: bft_$unload
Function:
Removes BFT from the memory of the PC, and performs the
cleanup to both CATs.
Syntax:
dcl bft_$unload entry (fixed bin (35))
call bft_$unload (error_code)
Arguments:
error_code
A standard Multics error code signalling the state of the
attempted operation. The error codes signify whether or not
an error was encountered, and if so, of what variety.
(Output)
Examples:
call bft_$unload (error)
MTB-742-03 BFT
4.2.2. PC
On the PC, BFT is accessed via the following routines:
bftfetch
bftstore
bftcan |
bftrecfe
bftrecst
bftunld
To use these routines on the PC the user must link his routines
to the file SUBRS.OBJ which can be found on Multics as
pc_bft_::SUBRS.OBJ.
BFT MTB-742-03
PC Entry: bftfetch
Function:
This routine transfers a file from Multics to the local
machine. As with store, if a file already exists with the
destination name, it will be overwritten.
Syntax:
bftfetch (source_filename, destination_filename, flags); |
char *source_filename;
char *destination_filename;
long flags; |
Arguments:
source_filename
is the pathname on the remote machine of the file which is to
be sent to the PC. (Input)
destination_filename
is the absolute PC pathname in which the file sent from the
remote machine is to be stored. (Input) |
flags |
is a collection of bits which represent transfer |
characteristics to be associated with the transfer (Input). |
The following definitions should be ORed together to obtain |
the appropriate settings: |
|
BFT_BINARY |
|
where: |
|
BFT_BINARY |
is the file_type of the transfer. Set to "flags | |
BINARY_SW" if the transfer is to be a binary file and |
<CR>/<NL> conversion are to be ignored. See BFT Command |
Interface - Notes on file_types. |
Examples:
bftfetch (">udd>multics>bob>wonk", "c:userpetewonk", 0);
bftfetch ( ">udd>m>Joe>blat", "b:blat", BFT_BINARY);
MTB-742-03 BFT
PC Entry: bftstore
Function:
This routine is used to send a file from the local machine and
store it on the remote machine (Multics). If a file already
exists with the destination name on the remote machine, it
will be overwritten if possible.
Syntax:
bftstore (source_filename, destination_filename, flags);
char *source_filename;
char *destination_filename;
long flags; |
Arguments:
source_filename
is the absolute PC pathname of the file to be transferred to
the remote machine. (Input)
destination_filename
is the absolute pathname in which the remote machine will
store the file. (Input) |
flags |
is a collection of bits which represent transfer |
characteristics to be associated with the transfer (Input). |
The following definitions should be ORed together to obtain |
the appropriate settings: |
|
BFT_BINARY |
|
where: |
|
BFT_BINARY |
is the file_type of the transfer. Set to "flags | |
BINARY_SW" if the transfer is to be a binary file and |
<CR>/<NL> conversion are to be ignored. See BFT Command |
Interface - Notes on file_types. |
Examples:
bftstore ("c:userbobwonk", ">udd>multics>bob>wonk", 0);
bftstore ("c:joe", ">udd>games>chess", BFT_BINARY);
BFT MTB-742-03
PC Entry: bftcan |
|
|
Function: |
Remove the specified entry from the containing queue. |
|
Syntax: |
bftcan (entry_id); |
char *entry_id; |
|
Arguments: |
|
entry_id |
is either a path name or the request identifier of the |
element. (Input) |
|
Examples: |
bftcan ("foo"); |
bftcan (">udd>m>bob>foo"); |
bftcan ("bar"); |
bftcan ("c:tmpbar"); |
bftcan ("173611.1"); |
MTB-742-03 BFT
PC Entry: bftrecfe
Function:
This routine is used to continue receiving a file from the
remote system (Multics) after a previous fetch command was
interrupted. The length of the destination file is checked on
the local machine, and the remainder of the file is
transferred.
Syntax:
bftrecfe ();
*
Examples:
bftrecfe ();
BFT MTB-742-03
PC Entry: bftrecst
Function:
This routine is used to continue sending a file to the remote
system (Multics) after a previous store command was
interrupted. The length of the destination file is checked on
the remote system, and the remainder of the file is sent.
Syntax:
bftrecst ();
*
Examples:
bftrecst ();
MTB-742-03 BFT
PC Entry: bftunld
Function:
This routine removes BFT from the memory of the PC, and
performs the cleanup to both CATs (Capability Address Tables).
Syntax:
bftunld ();
Examples:
bftunld ();
BFT MTB-742-03
4.3. BFT Command Interface
This is a description of how to invoke BFT from the command line.
The following is a list of acceptable BFT commands and the
necessary arguments that must be supplied. If any command is
entered with an insufficient number of arguments, the command is
rejected after an error is produced. If there are too many
arguments supplied, a warning will be printed and the command
will be ignored.
This command interface will be available on both the PC and
Multics.
The command syntax for all commands is :
bft key {name1 {name2}} {-control_args} |
where keys are those listed below, name1 and name2 are names of
files associated with a transfer request, and control_args are |
control arguments to be applied to the entire transfer request. |
keys:
load
This will cause the BFT modules to be loaded on both
machines. Note that this command is available only on
Multics. On the PC the user should issue the bft_load
command.
unload
This is to be used to unload the BFT MOWSE modules from
the PC and remove the BFT entries from the CATs on both
machines. It requires no extra arguments. All |
transfers in progress will be interrupted and the |
queues will remain intact with the current entries. |
store name1 {name2...name1N name2N} {-control_args} |
This is to request a transfer from the host machine to
the remote. This option requires at least one filename
as an argument. Name1 is the filename on the local
machine (source) which is to be transferred to name2N
(destination) on the remote machine. If name2N is not
given it will default to name1N. The equal convention |
is NOT allowed. |
MTB-742-03 BFT
fetch name1 {name2...name1N name2N} {-control_args} |
This is to request a transfer from the remote machine
to the host. This option requires at least one
filename as an argument. Name1 is the filename on the
remote machine (source) which is to be transferred to
name2N (destination) on the local machine. If name2N
is not given it will default to name1N. The equal |
convention is NOT allowed. |
cancel request_identifier {request_identifier ...} |
This will remove one or more entries from the list of |
pending requests, in either direction. |
request_identifiers can be chosen from one of the |
following: |
|
path |
identifies the relative pathname of the request. The |
star convention is not allowed. |
-id ID |
identifies one or more requests to be cancelled based |
on the entry ID of the reuqest. The star convention is |
not allowed. |
*
recover |
This is a recover command that will restart interrupted |
transfers and continue the transfer of pending requests in |
the queue. It is sufficient to merely submit the recover |
keyword and both queues (PC->Multics and Multics->PC) will |
be recovered and interrupted transfers will be started from |
where they left off. |
Control Arguments: The following is a list of control arguments |
which may be applied to a transfer request (store and fetch): |
|
-file_type TYPE, -ft TYPE |
specifies that the file is to be transferred as a TYPE |
file where type is either binary or ascii. (Default |
ascii) |
|
-queue N, -q N |
submits the request to the queue of priority N. There |
are 4 priorities numbered 1, 2, 3, and 4 with queue 1 |
being of the highest priority. (Default queue 3). |
|
Notes on file_type: The file_type binary indicates that the file |
is to be transferred with no <CR>/<LF conversions. The file_type |
ascii will transfer from PC->Multics converting a <CR><LF> pair |
to a single <LF>; Multics->PC transfers will convert a <LF> to a |
<CR><LF> pair. |
BFT MTB-742-03
Notes: When entering Multics pathnames on the PC it is important
to surround the pathname with double quotes. This is necessary
since MS-DOS will try to interpret less-than and greater-than
characters as I/O redirection commands. While entering commands
on the PC, for example, the user should not type:
bft s test.pl1 >udd>m>joe>test.pl1
but should instead type:
bft s test.pl1 ">udd>m>joe>test.pl1"