ft_transfer() sends a file to the remote system or fetches a file from the remote system.
In order to transfer files synchronously, the synchron parameter in the par structure must contain the value FT_SYNC.
In order to transfer files asynchronously, the synchron parameter in the par structure must contain the value FT_ASYNC.
For asynchronous file transfer, the function ft_transfer() returns a request ID which you must specify when you refer to this request.
File names must not exceed the length specified in the maxlfnsize or maxrfnsize fields of the ft_prop structure (see section “ft_properties - Determine properties of the program interface”).
Syntax
#include <ftapi.h>
long ft_transfer(const void *session, /* input */
const struct ft_admission *admis,
/* input */
const struct ft_transpar *par, /* input */
struct ft_err *errorinfo,
void *options); /* input */
Parameter
session
For asynchronous transfer:
Number of the session in which the transfer request is to be performed.
For synchronous transfer:
session must have the value NULL.
admis
Transfer admission for the remote system (see section “ft_admission” (Specifications concerning the remote system)).
par
Entries for the request which you specify with the structure ft_transpar:
struct ft_transpar
{
int ftparvers; /* input */
enum ft_direction direction; /* input */
enum ft_sync synchron; /* input */
char *locfn; /* input */
char *remfn; /* input */
enum ft_filetype filetype; /* input */
enum ft_writemode writemode; /* input */
enum ft_compress compress; /* input */
char *filepasswd; /* input */
char *locsuccproc; /* input */
char *locfailproc; /* input */
char *remsuccproc; /* input */
char *remfailproc; /* input */
long maxrecsize; /* input */
long cantime; /* input */
long starttime; /* input */
enum ft_prio priority; /* input */
enum ft_transpar transparent; /* input */
enum ft_encrypt encryption; /* input */
struct ft_transftam *ftamext; /* input */
char *locccsn; /* input */
char *remccsn; /* input */
enum ft_tabexp tabexp; /* input */
char *fud; /* input */
int fudlen; /* input */
enum ft_rform rform; /* input */
enum ft_tff tff; /* input */
enum ft_trf trf; /* input */
enum ft_moddate moddate; /* input */
enum ft_fncmode fncmode; /* input */
};
Note
Default values apply to certain parameters (see below) if you initialize this parameter list with the entries for the file transfer request with binary 0.
To initialize the parameter list with binary 0, use the command:memset (transpar, '\0', sizeof(struct ft_transpar));
The fields of the structure ft_transpar have the following meanings:
ftparvers
Version of the data structure.
ftparvers must be supplied the value FT_TPARV1, FT_TPARV2, FT_TPARV3 or FT_TPARV4.
direction
Direction of file transfer: FT_SEND
Send file to the remote system.
FT_RECEIVE
Fetch file from remote system. You cannot use wildcards when fetching a file.
synchron
Specifies how the file is to be transferred:FT_ASYNC
Asynchronous transfer (default value after initialization with binary 0).
FT_SYNC
Synchronous transfer.
locfn
File name in local system or preprocessing/postprocessing command.
In the case of local file names, it is now also possible to specify a preprocessing (when sending data) or postprocessing (when receiving data) command.
Absolute and relative path names are permissible. Relative path names refer to the directory in which the program is started.
remfn
File name in the remote system or preprocessing/postprocessing command.
In the case of remote file names, it is now also possible to specify a preprocessing (when sending data) or postprocessing (when receiving data) command.
Absolute and relative path names are permissible. Relative path names refer to the login name specified in the admission profile when the FTAC function is used, otherwise to the HOME directory, see "File transfer". As in the command ncopy, a preprocessing command may be specified next to it instead of a file name by using a preceding pipe (|) character (see also the command description of ncopy).
filetype
File type in local system:FT_NOTYPE
No specification of file type. The default values apply (see manual "openFT (Unix and Windows systems) - Command Interface", ft command). (default value after installation with binary 0)
FT_TEXT
The file contains text with variable record lengths. Records are delimited in Windows by CRLF (X’0D0A’) and in Unix systems by the linefeed character \n.
FT_USER
The file contains binary data with variable record length structured by the user. Each record starts with two bytes which indicate the length of the record.
FT_BINARY
The file contains an unstructured sequence of binary data.
writemode
specifies whether a new destination file is to be created or extended:
FT_NOMODE
No syntax is specified. The default values apply (see manual "openFT (Unix and Windows systems) - Command Interface", ft command). (default value after initialization with binary 0)
FT_OVERWR
An existing destination file is overwritten. If the destination does not already exist, a new one is created.
FT_EXTEND
The file transferred is added at the end of the existing destination file. If the destination does not already exist, a new one is created.
FT_NEW
A new destination file is created and written. If the destination file already exists, the request is rejected.
compress
Specifies whether data compression is to be used in transfer:FT_NOCOMPR
No compression (default value after initialization with binary 0).
FT_COMPRESS
Several identical characters in succession are transferred in compressed form (byte compression).
FT_COMPRESSZIP
Zip compression. In the case of connections to partners which do not support this compression, operation automatically switches to byte compression or no compression. Zip compression is only available if ftparvers is set to the value FT_TPARV2 and the Options parameter is specified when ft_transfer is called.
filepasswd
Password of the file in the remote system, if protected by password.
locsuccproc
Command executed in the local system following successful asynchronous file transfer.
locsuccproc must not be specified for synchronous file transfer requests.
Variables can be specified within a command or sequence of commands for follow-up processing. Further information is given in section “Commands for the follow-up processing”.
locfailproc
Command executed in the local system when an asynchronous file transfer is aborted due an error.
With synchronous file transfer request, locfailproc must not be specified.
Variables can be specified within a command or sequence of commands for follow-up processing. Further information is given below in section “Commands for the follow-up processing”.
remsuccproc
Command executed in the remote system following successful asynchronous file transfer.
Several partner systems(e.g. openFT (BS2000)) even support sequence of commands. Following successful transfer, these commands are executed in the remote system under the specified login.
Variables can be specified within a command or sequence of commands for follow-up processing. Further information is given below in section “Commands for the follow-up processing”".
remfailproc
Command executed in the remote system following unsuccessful asynchronous file transfer.
Several partner systems (e.g. openFT (BS2000)) even support sequence of commands. These commands are executed in the remote system under the specified login when file transfer that has been started is aborted due to an error.
Variables can be specified within a command or sequence of commands for follow-up processing. Further information is given below in section “Commands for the follow-up processing”.
Commands for the follow-up processing
The total number of entries for local follow-up processing, i.e. for locsuccproc and locfailproc, may not exceed 1000 characters.
The total number of entries for remote follow-up processing, i.e. for remssuccproc and remfailproc, may not exceed 1000 characters.
When starting follow-up processing in the local system, the variables are substituted with the values supplied by the ft_transfer() function.
The variable %FILENAME is provided for the file name, %PARTNER for the partner name, %RESULT for the result of the request and %RID for the request ID.
%RID is only allowed for local follow-up processing.
After follow-up processing is started, the variables in the particular system are replaced and the commands in the follow-up processing are executed. The following variable substitutions are permitted:%FILENAME
By the file name as specified for the corresponding system in the request.%PARTNER
For local follow-up processing the partner name specified in the call is used.
For follow-up processing in the remote system, %PARTNER is substituted by the name of the initiator system (with the name as known in the partner system).%RESULT
By the message number of the request as specified for the relevant system. Thus, for example, if a request is executed successfully,
%RESULT is assigned the value 0 (if the valueNULLis specified for options then the messages output at the program interface are compatible with those of the program interface in openFT < V10).%RID
By the request ID of the request in the local system (only local follow-up processing).
If the partners partner is an openFT (BS2000) system, you may also use the variables %ELEMNAME, %ELEMVERS and %ELEMTYPE.
During follow-up processing in the local Windows system, only the system environment variables are available.
Follow-up processing in the local Unix system and follow-up processing in a remote Unix does not involve execution of the sequence of commands stored in the .profile file. Only the default values of the $HOME, $LOGNAME, $PATH, and $USER shell variables are available, as well as the values of the $LANG and $TZ variables set by
root.When specifying BS2000 commands, remember to insert a slash (/) at the beginning of the command.
With requests for FTAM and FTP partners, only the "local follow-up processing” function is available. If FTAC is used in the remote system, this restriction can be avoided by creating an admission profile in the remote system and defining follow-up processing for it.
maxrecsize
Maximum permissible record length for files of type "text file" and "structured binary file". Thus, it is also possible to transfer and store records which are larger than the default value. However, you must observe that not all record lengths can be preprocessed in every partner system.
The maximum value must not exceed the length specified in the field maxrecord of the ft_prop structure (see section “ft_properties - Determine properties of the program interface”).
If you have selected the file type "binary", maxrecsize id the value for all records in the send file.
With FTAM partners, specification of the maximum record length is only effective when the file type FT_TEXT, FT_USER or FT_BINARY is specified for filetype.
cantime
Time at which a file transfer request is to be canceled. This time must be specified in internal format (seconds since 1.1.1970 00:00:00).
The value 0 means that no time cancellation is performed.
With synchronous requests, cantime is ignored.
starttime
Specifies the earliest time at which file transfer is to be started. This time must be specified in internal format (seconds since 1.1.1970 00:00:00).
The value 0 means that the file transfer is started as soon as possible.
For synchronous requests, starttime is ignored.
priority
Specifies the priority of the request:FT_PRIONORM
Normal priority (default value after initialization with binary 0).
FT_PRIOLOW
Low priority (is ignored for synchronous requests).
transparent
Specifies whether the file transfer is to be transparent:FT_NOTRANSPAR
Normal transfer (default value after initialization with binary 0).
FT_TRANSPARENT
Transparent file transfer.
encryption
Specifies whether the user data are to be encrypted or whether a data integrity check is to be performed:FT_NOENCRYPT
User data are not encrypted and no data integrity check is performed (default value after initialization with binary 0).
FT_ENCRYPT
User data are encrypted and data integrity is checked automatically.
openFT-CR must be installed to enable this.
FT_ONLYDICHECK
A data integrity check is performed for the transferred file contents.
The data integrity check is only available if ftparvers is set to the value FT_TPARV2 and the options parameter is specified when ft_transfer is called.
ftamext
FTAM-specific parameter made known with the structure ft_transftam (see also the commands ft and ncopy, options -av, -ac, -am, -lq and -cp):
struct ft_transftam
{
enum ft_available available; /* input */
char *account; /* input */
int accessmode; /* input */
char *legalq; /* input */
char *crpasswd; /* input */
};
The fields of the structure ft_transftam have the following meanings:
available
Specifies the availability of the destination file:
FT_NOAVAIL
No specification of availability (default value after initialization with binary 0).
FT_AVAILIMM
The destination file contains the attribute "immediately available".
FT_AVAILNIMM:
The destination file contains the attribute "not immediately available".
account
Account number for FTAM partners.
accessmode
Specifies the access rights for the destination file. The access rights are created by logical OR-ing of the individual rights:
FT_ACCR
The file may be read.
FT_ACCI
File units may be inserted into the file.
FT_ACCP
The file may be overwritten.
FT_ACCX
The file may be extended, i.e. data can be appended to the file.
FT_ACCE
File units may be deleted from the file.
FT_ACCA
File attributes may be read.
FT_ACCC
File attributes may be modified.
FT_ACCD
The file may be deleted.
legalq
Stipulates the copyright for the destination file.
crpasswd
Password required to create a file in the remote system.
locccsn
Specifies the name of the coding (CCS name) used to read or write the local file. CCS-name must be known in the local system.
If no coding is specified then the default coding value set for openFT via the operating parameters is used.
Support for "Coded Character Sets" (CCS) is only available if ftparvers is set to the value FT_TPARV2 and the options parameter is set when ft_transfer is called.
remccsn
Specifies the name of the coding (CCS name) used to read or write the remote file. CCS-name must be known in the remote system. If no coding is specified then character set defined via XHCS (BS2000 systems) or via the openFT operating parameters (other platforms) is used for coding.
Support for "Coded Character Sets" (CCS) is only supported for the openFT protocol and for partners with openFT V10.0 or higher and is only available if ftparvers is set to the value FT_TPARV2 and the options parameter is set when ft_transfer is called.
tabexp
In the case of an outbound send request, specifies whether tabulator expansion and the conversion of blank lines into lines with a character for non-FTAM partners are to be performed. Tabulator expansion is only available if ftparvers has the value FT_TPARV2 and the options parameter is specified when ft_transfer is called.
FT_TABAUTO
Tabulator expansion and the conversion of blank lines are activated when a file is sent to a BS2000, OS/390 or z/OS system (default value after initialization with binary 0).
FT_TABON
Tabulator expansion and the conversion of blank lines are activated.
FT_TABOFF
Tabulator expansion and the conversion of blank lines are deactivated.
fud
Address of a data area for the so-called "Further Details" which can indicate a more detailed cause of error if errors occur.
If NULL is specified then no more detailed error cause is output. The fud parameter is only available if ftparvers is set to the value FT_TPARV2 and the options parameter is specified when ft_transfer is called.
fudlen
Length of the data area for fud.
The fudlen parameter is only available if ftparvers is set to the value FT_TPARV2 and the options parameter is specified when ft_transfer is called.
rform
Specifies the record format of the file that is to be transferred. The rform parameter is only available if ftparvers is set to the value FT_TPARV2 and if the options parameter is specified when ft_transfer is specified.
FT_NOFORM
The record format of the file that is to be transferred is unknown (default value after initialization with binary 0).
FT_VARIABLE
The file to be transferred contains records with a variable record length.
FT_FIXED
The file to be transferred contains records with a standard, fixed record length.
FT_UNDEF
The file to be transferred contains records with an undefined record length.
tff
Specifies the format of the target file:
FT_NOTFF
Format like send file, see field trf (default value after initialization with binary 0).
FT_TFFBLOCK
The target file should be saved on a block-structured basis. This enables e.g. a file to be transferred to BS2000 and saved there as a PAM file. If you specify FT_TFFBLOCK, you must also specify the file type =FT_BINARY.
FT_TFFSEQU
The target file should be saved as a sequential file, and the record format should be retained. This enables e.g. an ISAM file or PAM file to be collected from BS2000. See also trf =FT_TRFUNDEF.
trf
Specifies the record format of the target file:
FT_NOTRF
Format like send file, see field ttf (default value after initialization with binary 0).
FT_TRFUNDEF
Specifies that the file is transferred as a sequential file and that the record format of the target file should be undefined. In other words, the record structure of the send file is lost. A block is written per transfer unit for the transfer to a BS2000 or z/OS system.
May not be specified together with ttf =FT_TFFBLOCK!
moddate
Specifies how the modification date of the target file is treated. This function only makes sense for requests to BS2000 partners with OSD as of V8.0 via the openFT protocol.
FT_MDSRC
Behavior as in openFT up to V11.0 applies: The modification date of the send file is transferred on Unix and Windows systems and POSIX (BS2000). The current time is taken as the modification date on BS2000 with DMS (default value after initialization with binary 0).
FT_MDFAIL
The modification date of the send file is transferred to the target file if the target system supports this transfer. If the target system does not support this function, the request is rejected.
May not be specified together with ft_writemode = FT_EXTEND!
fncmode
Specifies the file-name encoding-mode.
FT_FNCTRANS
Specification of the remote file name and follow-up processing for the remote system in transparent mode (compatible to the previous version; default value after initialization with binary 0).
FT_FNCCHAR
Specification of the remote file name and follow-up processing for the remote system in character mode. They are interpreted according to the character code of the remote system, i.e. for UNIX partners according to the openFT operating parameter option (ftmodo –fnccs) that has been set there. –fnc=c is only permitted for openFT partners as of openFT V12.1B. This functionality is only available if ftparvers is set to the value FT_TPARV4 and the Options parameter is specified when ft_transfer is called.
errorinfo
Area in which detailed information is stored if an error is encountered (see section “ft_err” (Error handling)).
The specification of this parameter is optional. If you do not require any more precise error information then you can specify the value NULL for errorinfo.
options
The specification of the options parameter is optional. If the value NULL is specified then message activity at the program interface is compatible with that of the program interface of openFT < V10.
Alternatively, it is possible to specify the ft_options structure (see section “ft_options” (Version of the program interface)) to activate the openFT message number scheme as of openFT V10 and the extensions to the function.
Return value
n | For successful asynchronous requests: request ID (n |
1 | For successful synchronous requests. |
0 | Error. File transfer was not initiated. |