How to use the library
You use the JP1/FTP API library when you use the file transmission function of JP1/FTP from a user program.
The 32-bit (ILP32 data model) and 64-bit (LP64 data model) versions of the API library are provided.
The JP1/FTP API library enables you to do the following:
-
Register transmission requests from a single user program to multiple JP1/FTPs that are running on different hosts (or on the same host)
-
Select the transmission type when you register transmission requests:
Synchronous type: Waits until a transmission is completed and the termination result is obtained.
Asynchronous type: Performs registration only and does not wait for the termination results (obtains the termination results later).
- Organization of this page
Licensing
You may copy the header file and libraries to the environment in which JP1/FTP is not installed to build a user program.
Languages
The following languages are supported for user programs:
-
C
-
C++
Setting up an environment
Setting /etc/services
Set the JP1/FTP client's service name as ftsc. For details, see 2.3.3 Setting the port numbers.
Setting /etc/hosts
Set the host name and IP address of the host on which the client's JP1/FTP daemon is running. Specify this host name in the connection information structure and the transmission information structure.
Add the following line to /etc/hosts:
xxx.xxx.xxx.xxx yyyyyy
- Legend:
-
xxx.xxx.xxx.xxx: IP address
yyyyyy: Host name
Coding
Specifying information for establishing a connection with JP1/FTP
To establish a connection with the JP1/FTP daemon, specify the address of the connection information structure in the argument of fts_ftp_open_ex().
-
Connection information structure
typedef struct _FTS_FTP_API_CONN_DATA { char hostname[256+1]; /* Client host name */ int priority; /* IP version to be given priority */ char reserve[1784]; /* Reserved area */ } FTS_FTP_API_CONN_DATA;
-
Content of the connection information structure members
- hostname
-
Specifies the host name or IP address of the computer on which the client's JP1/FTP daemon is running. When you specify an IP address, you can specify an IPv4 or IPv6 address. If a null value is specified, the local host name (the physical host name returned by the OS's hostname command) is assumed.
If specification of a local IP address at the FTP client is enabled, the value specified in this argument becomes the local IP address of the FTP client.
If a null value is specified, the physical host of the FTP client is assumed.
If specification of a local IP address at the FTP client is disabled, the local IP address of the FTP client is automatically assigned by the OS. For details about the definition that enables specification of a local IP address at the FTP client, see 3.15 Using JP1/FTP in a multiple IP address environment.
- priority
-
Specifies the Internet protocol version to be given priority.
FTS_AF_INET: IPv4 is given priority.
FTS_AF_INET6: IPv6 is given priority.
In all other cases, FTS_AF_INET is assumed,
- reserve
-
Reserved area. Initialize the area by specifying \0.
- Note
-
Make sure that a char-type variable value ends with \0.
Specifying the transmission information
To register a file transmission request, you set the registered transmission card name and the address of the transmission information structure in the arguments of fts_ftp_syn_request_ex() and fts_ftp_asyn_request_ex().
-
Using the card name to register transmission requests:
You can register a transmission request by specifying a transmission card name registered using Registration And Execution Of Transmission Requests.
-
Using the transmission information structure to specify transmission information:
You can register a transmission request by specifying the information needed for transmission.
-
Transmission information structure
typedef struct _FTS_FTP_API_DATA_EX { char cardname[20+1]; /* Card name */ char host[256+1]; /* Remote host name */ unsigned int portnum; /* Port number */ char username[80]; /* Remote user name */ char password[80]; /* Password */ int type; /* Transmission mode */ int cmd; /* Send/receive type */ int mode; /* Compression mode */ char quote[300+1]; /* FTP command */ char localname[256+1]; /* Local file name */ char remotename[256+1]; /* Remote file name */ char end_program[256+1]; /* Name of program to start at normal end */ char abend_program[256+1]; /* Name of program to start at abnormal end */ char comment[80+1]; /* Comment */ int fsize; /* Size check */ int ftps; /* Use FTPS */ int scertval; /* Check the expiration date of the server certificate */ char cacertpath[256+1]; /* Path to the CA certificate */ char crlpath[256+1]; /* Path to the CRL */ char reserve[716]; /* Reserved area */ } FTS_FTP_API_DATA_EX;
-
Description of the transmission information structure members
- cardname
-
Specifies the card name.
- host
-
Specifies the FTP host name: ftp>open aaaa
- portnum
-
Specifies the FTP port number: ftp>open aaaa bbbb
- username
-
Specifies the login name: ftp>user aaaa
- password
-
Specifies the password.
- type
-
Specifies the transmission mode:
FTS_TYPE_A: Interprets data as being in ASCII code and then sends it (ftp>ascii).
FTS_TYPE_I: Interprets the data as an image and then sends it (ftp>binary).
- cmd
-
Specifies the type of transmission.
By using OR to specify single/multiple-file transmission, you can specify a combination of single-file transmission and multiple-file transmission.
Transmission types:
FTS_CMD_SEND (send): ftp>put aaaa bbbb
FTS_CMD_RECV (receive): ftp>get cccc ddddd
FTS_CMD_APPE (send with append): ftp>append eeee fffff
Single/multiple-file transmission:
FTS_MLT_AUTO: Switch automatically between single-file and multiple-file transmission. This is the default.
FTS_MLT_MULTIPLE: Perform multiple-file transmission.
FTS_MLT_SINGLE: Perform single-file transmission.
FTS_MLT_AUTO switches transmission automatically as follows:
When sending
The function checks whether * or ? is used in the local file name. If * or ? is used, multiple-file transmission is used. If neither of them is used, single-file transmission is used.
When receiving
The function checks whether * or ? is used in the remote file name. If * or ? is used, multiple-file transmission is used. If neither of them is used, single-file transmission is used.
Examples
Sending multiple files:
cmd = FTS_CMD_SEND | FTS_MLT_MULTIPLE;
Receiving a single file:
cmd = FTS_CMD_RECV | FTS_MLT_SINGLE;
Sending (with append) by automatic switching:
cmd = FTS_CMD_APPE | FTS_MLT_AUTO;
or
cmd = FTS_CMD_APPE;
(If specification of single/multiple-file transmission is omitted, FTS_MLT_AUTO is assumed.)
- mode
-
Specifies compressed transmission.
FTS_MODE_S: Does not perform compressed transmission.
FTS_MODE_C: Performs compressed transmission.
- quote
-
Specifies the FTP command to execute.
This structure member is a character string consisting of commands, such as CWD and SITE, delimited by semicolons (;) (the character string must end with \0).
Only commands that do not establish a data connection can be specified. Whether a command can be executed by the FTP server depends on the FTP server.
- localname
-
Specifies the local file name.
Examples
ftp>put aaaa bbbb
ftp>get cccc dddd
- remotename
-
Specifies the remote file name.
Examples
ftp>put aaaa bbbb
ftp>get cccc dddd
- end_program
-
Specifies the full path name of the program to start when transmission ends normally.
- abend_program
-
Specifies the full path name of the program to start when transmission ends abnormally.
- comment
-
Specifies any character string.
- fsize
-
Specifies whether to check the file size after transmission.
FTS_FSIZE_TRUE: Checks the size.
FTS_FSIZE_FALSE: Does not check the size.
- ftps
-
Specifies whether to use FTPS.
FTS_FTPS_TRUE: Uses FTPS.
FTS_FTPS_FALSE: Does not use FTPS.
- scertval
-
Specifies whether to check the expiration date of the server certificate.
FTS_SCVAL_TRUE: Checks the expiration date of the server certificate.
FTS_SCVAL_FALSE: Does not check the expiration date of the server certificate.
- cacertpath
-
Specifies a full path to the CA certificate file.
- crlpath
-
Specifies a full path to the CRL file.
- reserve
-
Reserved area. Initialize the area by specifying \0.
- Note
-
Make sure that a char-type variable value ends with \0.
Obtaining transmission-end information
You can obtain the termination information for transmission requests registered by fts_ftp_syn_request_ex() and fts_ftp_asyn_request_ex().
-
When fts_ftp_syn_request_ex() is used to register requests:
Specify the address of the transmission-end information structure in the fourth argument of fts_ftp_syn_request_ex().
-
When fts_ftp_asyn_request_ex() is used to register requests:
Specify the address of the transmission-end information structure in the second argument of fts_ftp_event_ex().
-
Transmission-end information structure
typedef struct _FTS_FTP_API_RETDATA_EX { /* Data when transmission was successful */ int trans_status; /* Transmission end status: success (TRANS_SUCCESS) */ /* Transmission end status: failure (TRANS_FAILURE) */ char cardname[20+1]; /* Card name */ unsigned long trno; /* Transmission number */ unsigned long trcno; /* Connection number */ /* Data when transmission was successful */ unsigned long trans_size; /* Transmitted data size */ /* Data when transmission (compressed) was successful */ unsigned long trans_size_comp; /* Transmitted data size after compression */ /* Data when transmission failed */ int ab_kind; /* System call error (FTS_ERR_SYSTEM) */ /* Logical error (FTS_ERR_LOGIC) */ /* Protocol error (FTS_ERR_PROTOCOL) */ /* Forced termination error (FTS_ERR_FORCE) */ /* SSL communication error (FTS_ERR_SSL) */ char ab_place[8]; /* Location of error */ char ab_func[32]; /* Name of module resulting in error */ char ab_system[32]; /* System call name */ unsigned long ab_errno; /* Error number */ char ab_promes[256]; /* Protocol message (error) */ #ifndef FTS_API_64BIT char full_trans_size[8]; /* Transmitted data size */ char full_trans_size_comp[8]; /* Transmitted data size after compression */ #endif int ab_sslerno; /* SSL communication error number */ char reserve[1668]; /* Reserved area */ } FTS_FTP_API_RETDATA_EX;
-
Description of transmission-end information structure members
- trans_status
-
Returns one of the following values indicating the termination status of transmission:
TRANS_SUCCESS: Normal termination
TRANS_FAILURE: Abnormal termination
- cardname
-
Returns the transmission card name.
- trno
-
Returns the transmission number.
- trcno
-
Returns the connection number.
- trans_size (Applicable to normal termination only)
-
Transmitted data size (Can be referenced only when the transmitted data size is smaller than 4 gigabytes).
- trans_size_comp (Applicable to normal termination only)
-
Transmitted data size after compression (Can be referenced only when the transmitted data size is smaller than 4 gigabytes).
- ab_kind (Applicable to abnormal termination only)
-
Returns the error type:
FTS_ERR_SYSTEM: System call error
FTS_ERR_LOGIC: Logical error
FTS_ERR_PROTOCOL: Protocol error
FTS_ERR_FORCE: Forced termination error
FTS_ERR_SSL: SSL communication error
- ab_place (Applicable to abnormal termination only)
-
Returns the location of the error.
- ab_func (Applicable to abnormal termination only)
-
Returns the name of module resulting in the error.
- ab_system (Applicable to abnormal termination only)
-
Returns the system call name.
- ab_errno (Applicable to abnormal termination only)
-
Returns the system call error number.
One of the following values is returned:
2000: Timeout was detected during system function (system-call-name) processing.
2001: Transmission file size mismatch was detected during system function (system-call-name) processing.
2003: The maximum file size supported for transmission by JP1/FTP was exceeded during system function (system-call-name) processing.
Other: A value is returned by the system function (system-call-name), but the target of the return value depends on the system function, as follows:
• For the getaddrinfo function: getaddrinfo return value (In Linux, the return value is negative, but it is converted to an unsigned value.)
• For the getnameinfo function: getnameinfo return value (In Linux, the return value is negative, but it is converted to an unsigned value.)
• For other functions: errno value
- ab_promes (Applicable to abnormal termination only)
-
Returns the protocol message sent from the server.
- full_trans_size (Applicable to normal termination only)
-
Transmitted data size (Referenced using fts_ftp_buftoll()).
- full_trans_size_comp (Applicable to normal termination only)
-
Transmitted data size after compression (Referenced using fts_ftp_buftoll()).
- ab_sslerno (Applicable to abnormal termination only)
-
Returns the SSL communication error number.
- reserve
-
Reserved area.
Compiling and linking
-
To use the 64-bit library, specify FTS_API_64BIT for the compile option.
Example: cc -DFTS_API_64BIT -c sample.c
-
To use fts_ftp_buftoll(), specify the FTS_NO_TRANSIZE_LIMIT compile option.
Example: cc -DFTS_NO_TRANSIZE_LIMIT -c sample.c
-
Link the following library:
For the 32-bit library: libftsftp_r.so
For the 64-bit library: libftsftp64_r.so
-
In Linux, specify -lpthread in the link option.
Notes about using libraries
-
The API libraries support multithreading.
-
The following usage is not permitted:
Using a single fts_ftp_open_ex() function to issue multiple fts_ftp_syn_request_ex() and fts_ftp_asyn_request_ex() functions concurrently (concurrent execution of fts_ftp_syn_request_ex() and fts_ftp_asyn_request_ex() by multiple processes)
-
If a wildcard character is specified, the transmission-end information that can be obtained is as follows:
When the function terminates normally: Transmission-end information for the last file transmitted
When the function terminates abnormally: Transmission-end information for the first file resulting in an error
-
In Linux, specify the library path in the following environment variable:
LD_LIBRARY_PATH
Example in bash:
LD_LIBRARY_PATH=/opt/jp1_fts/lib/api/apilib export LD_LIBRARY_PATH
Example in csh:
setenv LD_LIBRARY_PATH /opt/jp1_fts/lib/api/apilib
-
For the 32-bit library, if the size of the transmitted data or of the compressed data that was transmitted is 4 gigabytes or greater, the transmission-end information structure members trans_size and trans_size_comp cannot be referenced. This is because trans_size and trans_size_comp are the unsigned long type, and in the ILP32 data model, if the data size is 4 gigabytes or greater, overflow occurs. If the transmitted data size (or transmitted data size after compression) is 4 gigabytes or greater, convert the transmission-end information structure members full_trans_size and full_trans_size_comp to numeric values by using fts_ftp_buftoll()before referencing them.
-
Only POSIX threads are supported.
-
A value cannot be set in fts_errno. It can only be referenced.
-
If you call fts_ftp_open_ex() once in a process and call fts_ftp_syn_request_ex() by multiple threads concurrently, transmission is performed serially. To perform concurrent transmissions, call fts_ftp_open_ex() each time fts_ftp_syn_request_ex() is called. Note that you need as many fts_ftp_close() functions as the number of fts_ftp_open_ex() calls that are issued.
-
fts_ftp_syn_request_ex() and fts_ftp_asyn_request_ex() cannot be mixed together when only one fts_ftp_open_ex() is used to call them. If these functions are mixed, the transmission result cannot be received successfully.
-
All API functions become thread cancellation points.
-
If a thread has been canceled, make sure that you use fts_ftp_close() to release connection with the JP1/FTP daemon that was used by the canceled thread. If you continue using the connection, the transmission result cannot be received successfully.