Job Management Partner 1/File Transmission Server/FTP Description, Reference and Operator's Guide

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 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).

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 first argument of fts_ftp_open() 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 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];
    char host[256+1];
    unsigned int portnum;
    char username[80];
    char password[80];
    int type;
    int cmd;
    int mode;
    char quote[300+1];
    char localname[256+1];
    char remotename[256+1];
    char end_program[256+1];
    char abend_program[256+1];
    char comment[80+1];
    int fsize;
    char reserve[1240];
} 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).

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.
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) */
  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) */
 
  char full_trans_size[8];      /* Transmitted data size */
  char full_trans_size_comp[8]; /* Transmitted data size
                                     after compression */
 
  char reserve[1672];           /* 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 (referenced in the case of Linux (IPF). In a system other than Linux (IPF), this value can be referenced only when the transmitted data size is less than 4 gigabytes).

trans_size_comp (Applicable to normal termination only)

Transmitted data size after compression (referenced in the case of Linux (IPF). In a system other than Linux (IPF), this value can be referenced only when the transmitted data size is less 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

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.

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 (not available for Linux (IPF)). This value is referenced by using fts_ftp_buftoll() in a system other than Linux (IPF).

full_trans_size_comp (Applicable to normal termination only)

Transmitted data size after compression (not available for Linux (IPF)). This value is referenced by using fts_ftp_buftoll() in a system other than Linux (IPF).

Compiling and linking

Single-thread program

ILP32 data models are provided for all interfaces and libraries. Create, compile, and link your user programs also as ILP32 data models. (For Linux (IPF version), only LP64 data models are provided for all interfaces and libraries. Therefore, create, compile, and link your user programs as LP64 data models.)

Link the following library:
libftsftp.a or libftsftp.so

In Solaris, specify the -L and -R options when you link shared libraries (.so).
Example: cc -o sample sample.c -L/opt/jp1_fts/lib/api/apilib -R/opt/jp1_fts/lib/api/apilib -lftsftp

In AIX, if you link libftsftp.so, specify -brtl in the link option.

If you use fts_ftp_buftoll(), specify the -DFTS_NO_TRANSIZE_LIMIT compile option.

Multi-thread program

ILP32 data models are provided for all interfaces and libraries. Create, compile, and link your user programs also as ILP32 data models. (For Linux (IPF version), only LP64 data models are provided for all interfaces and libraries. Therefore, create, compile, and link your user programs as LP64 data models.)

In the definition of a preprocessor, define and compile FTS_THREAD_SAFE.
Example: cc -D FTS_THREAD_SAFE -c sample.c

In HP-UX, link libpthread.sl.

In Solaris, link libpthread.so.

Link the following library:
libftsftp_r.a or libftsftp_r.so

In Solaris, specify the -L and -R options when you link shared libraries (.so).

In AIX, if you link libftsftp_r.so, specify -brtl in the link option.

In Linux, specify -lpthread in the link option.

If you use fts_ftp_buftoll(), specify the -DFTS_NO_TRANSIZE_LIMIT compile option.

Notes about using libraries

The following usage is not permitted:
Using a single fts_ftp_open() 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 is specified, fts_ftp_event_ex() can obtain the following transmission-end information:
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 Solaris, if you have compiled a user program using a version earlier than 09-00, change the old library path to the new path supported by version 09-00 or later and then re-compile the user program.

In Linux, if you use a shared library, 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

In a system other than Linux (IPF), if the transmitted data size (or the transmitted data size after compression) 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, reference the transmission-end information structure members trans_size and trans_size_comp.
In Linux (IPF), you can reference trans_size and trans_size_comp as is even if the transmitted data size (or transmitted data size after compression) is 4 gigabytes or greater.

The transmission-end information structure members full_trans_size and full_trans_size_comp cannot be referenced directly. Use fts_ftp_buftoll() to convert them to numeric values before you reference them.

When you use fts_ftp_buftoll(), you use the variable type long long. However, some compilers do not support the long long type by default. In such a case, specify the compile option that enables the long long type.

If you use a secondary group (set the JP1FTS_CSUPPLEGROUP environment variable to ON) and a static library, you must link a library version 09-00 or later.

Notes about using libraries for multi-thread programs

In HP-UX, only kernel threads are supported for HP-UX 11.0 or later. DCE threads are not supported.

Only POSIX threads are supported.

A value cannot be set in fts_errno. It can only be referenced.

If you call fts_ftp_open() 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() 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() 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() 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.

[Contents][Back][Next]

[Trademarks]