File transfer

Synchronous transfer

For synchronous file transfer, use the function ft_transfer(). In the parameter list, the parameter synchron must contain the value FT_SYNC. The control is not returned to the program until file transfer is completed. You can use the return values to determine whether file transfer has been successful.

Asynchronous file transfer

Several functions are necessary in order to perform synchronous file transfer. They result from the fact that, with asynchronous file transfer requests are issued, stored in the request queue and possibly not executed until later. The requests must be administered and the successful transfer must be monitored. It is therefore only possible to transfer files asynchronously within "sessions".
A program for asynchronous file transfer is made of two parts:

• In the first part, you open a session. Further, you issue one or more file transfer requests. If necessary, you can delete file transfer requests.
  openFT executes the request itself at the next possible opportunity.

• In the second part, you query the status of the request later and terminate the request on successful completion. If necessary, you can determine which requests have not been completed and terminate these as appropriate. Then you can close the session.

Schematic of the program structure:

The following function calls are absolutely necessary for asynchronous file transfer:

1. ft_open()
   The function ft_open() opens a session. The result of ft_open() is a session number (session identification) which uniquely identifies the session. This session number must be specified as parameter for function calls within the same session.
   When you open a session, you must assign an existing directory as working directory. In this working directory, the files are stored with management information about the existing file transfer requests.
   You may assign the same working directory to several different consecutive sessions. This brings the advantage that you can administer requests from various sessions together.
   You can conduct several sessions in parallel in one program. With ft_open(), however, you can only open more than one session simultaneously if each of the parallel sessions is assigned a different working directory.

2. ft_transfer()
   The ft_transfer() is used to issue an asynchronous file transfer request. The parameter synchron in the parameter list must contain the value FT_ASYNC. You may issue several asynchronous requests in succession in one session.
   When the request has been successfully entered in the request queue, you are returned a request ID as the result of ft_transfer(). The request ID uniquely identifies the request. This request ID is valid, even beyond the session, until the request is terminated with the function ft_reqterm().
   When the request is present in the request queue, you do not have to take care of the request execution. openFT executes the asynchronous request at the earliest possible time. If, for example, a partner is not available at the moment, openFT keeps trying to execute the request. The request is thus held in the request queue until it has been completed or any deletion date that has been specified is reached.

3. ft_reqstat()
   You can use the function ft_reqstat() to determine whether or not the file transfer has been successfully completed. As asynchronous file transfer is not carried out immediately, you should delay the use of the function ft_reqstat() and repeat the status query. When the request is completed, the parameter status is assigned the value FT_STATT, if terminated, it is assigned the value FT_STATA.

4. ft_reqterm()
   You must terminate the request using the function ft_reqterm(). This function deletes the request ID of the request and also the file in which the relevant information about the file transfer request is stored. Resources which are no longer required are released.
   The management file has the name mf. Request-ID and is located in the directory indicated as workdir parameter with the function call ft_open().
   The request IDs of requests which have not been completed are retained, even after the session in which the requests were issued has been closed These requests can be completed at a later time by referencing the associated request ID, if the current session is assigned to the same working directory as the session in which the request was originally issued.

5. ft_close()
   You can use the function ft_close() to close the session.

HOME directory

If absolute file or directory names were not specified in the remote Unix or Windows systems then the user’s HOME directory in the remote system is of importance. Relative path names always refer to the HOME directory of the corresponding user unless a definition to the contrary has been made by an FTAC profile.
The following applies to the HOME directory:

• In Unix systems, the HOME directory is the directory which is opened for the user after login.

• In Windows systems, a user’s HOME directory for openFT requests is the directory entered in user administration for this user.
  If no directory is entered for the user in user administration then the user’s profile path is used as the HOME directory. The profile path is \Users\User where User does not have to be identical to the name of the user.
  If it is also not possible to determine the user’s profile path, then the openFT home directory is created in the \Users directory and access rights are granted in full to SYSTEM, administrators and the corresponding user.
  In this case, the name of the home directory created by openFT is determined as follows:

  • Local user ID: UserID.Computer-name

  • Global user ID (domain\user ID): UserID.Domain

Managing asynchronous requests

Further functions are available for managing asynchronous requests:

• ft_cancel()
  You can use the function ft_cancel() to cancel asynchronous requests which are in the course of being processed or which are waiting to be processed in the request queue request queue.
  This function is expedient only when the program to be created has a user interface and the user has options for intervening. For example, you could imagine a program which displays waiting file transfer requests to the user (ft_reqstat (status=FT_STATW)) and allow him or her to abort these requests.
  Another application is when file transfer request have issued by mistake and should now be deleted.
  With the function ft_cancel(), you can only cancel requests which are present in the request queue and which have a request ID. If the request was issued in another session, the current session must be assigned the same working directory as for the session in which the request was issued. If the ft_transfer() function returns the value 0, the request could not be entered into the request queue. These unsuccessful attempts to enter requests terminate with an error message.
  Requests which you cancel with ft_cancel(), must be terminated with ft_reqterm() in order for the associated request ID to be deleted.

• ft_reqlist()
  All transfer requests must be completed so that associated request IDs and management files can be deleted and resources that are not required released.
  With the function ft_reqlist(), you determine uncompleted requests from all sessions which have been assigned the same working directory as the current session. Please note that not all request which have not be completed are determined, but only those from sessions with the same working directory.