How to use the library

Languages

The following languages are supported for user programs:

• C

• C++

To Page Top

Setting up an environment

xxx.xxx.xxx.xxx      yyyyyy

To Page Top

Coding

To Page Top

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 (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

  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

  For the getnameinfo function: getnameinfo return 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()).

To Page Top

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.

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

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

To Page Top

Notes about using libraries

• 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 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

• If the transmission data size or compressed transmission data size is 4 gigabytes or more, 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.

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

To Page Top

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

To Page Top