Hitachi

For Windows Systems JP1 Version 11 JP1/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:

Organization of this page

Prerequisites for using the functions

To use the functions provided by JP1/FTP, you need the following:

The following languages are supported for user programs:

The JP1/FTP API library requires the following compilers:

Table 7‒1: Compilers required by the JP1/FTP API library

Compiler

Type

Header file

Import library

Visual Studio 2012

32-bit

apihead.h

FTSFTP110.lib

64-bit

apihead.h

FTSFTP110_x64.lib

Visual Studio 2013

32-bit

apihead.h

FTSFTP120.lib

64-bit

apihead.h

FTSFTP120_x64.lib

For details on the storage locations of the header file and import library, see A. List of Files and Directories. The OSs under which Visual Studio itself can be installed depend on the Visual Studio specifications.

To Page Top

Setting up an environment

Setting services

Set the JP1/FTP client's service name as ftsc. For details, see 2.2.3 Setting the port numbers.

Setting hosts

Set the host name and IP address of the host on which the client's JP1/FTP program is running. Specify this host name in the connection information structure and the transmission information structure.

Add the following line to OS-installation-directory\system32\drivers\etc\HOSTS: 

xxx.xxx.xxx.xxx      yyyyyy
Legend:

xxx.xxx.xxx.xxx: IP address

yyyyyy: Host name

To Page Top

Coding

Specifying information for establishing a connection with JP1/FTP

To establish a connection with the JP1/FTP Client service, 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;

  • Description of the connection information structure members

    • hostname

      Specify the host name or IP address of the host on which the JP1/FTP Client service 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.11 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[50+1];    /* Remote user name */
    char password[50+1];    /* Password */
    int type;               /* Transmission mode */
    int mode;               /* Compression mode */
    int cmd;                /* Send/receive type */
    char quote[300+1];      /* FTP command */
    char localname[260+1];  /* Local file name */
    char remotename[260+1]; /* Remote file name */
    char end_program[260+1]; /* Name of program to start at normal end */
    char abend_program[260+1]; /* Name of program to start at abnormal end */
    char comment[80+1];     /* Comment */
    int fsize;              /* Size check */
    char reserve[1240];     /* 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).

    • mode

      Specifies whether to use compressed transmission.

      FTS_MODE_S: Does not use compressed transmission.

      FTS_MODE_C: Uses compressed transmission.

    • 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. Note that this specification is applicable to reception only.

      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.

      Example

      Receiving a single file:

      cmd = FTS_CMD_RECV|FTS_MLT_SINGLE;

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

    • reserve

      Reserved area. Initialize the area by specifying \0.

    Note

    Make sure that a char-type variable value ends with \0.

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

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 */
#ifdef FTS_API_64BIT
  unsigned __int64 trans_size;   /* Transmitted data size */
  unsigned __int64 trans_size_comp; /* Transmitted data size
                                       after compression */
#else
  unsigned long trans_size;      /* Transmitted data size */
  unsigned long trans_size_comp; /* Transmitted data size
                                    after compression */
#endif
 
  /* Data when transmission failed */
  int ab_kind;                   /* System call error
                                    (FTS_ERR_SYSTEM) */
                                 /* Logical error
                                    (FTS_ERR_LOGIC) */
                                 /* Protocol error
                                    (FTS_ERR_PROTOCOL) */
  char ab_place[8];              /* Location of error */
  char ab_func[32];              /* Name of module resulting
                                    in error */
  char ab_system[32];            /* System call name */
  int ab_syskind;       /* System call type */
                        /* Win32 API(FTS_SYSKIND_WIN32) */
                        /* C runtime(FTS_SYSKIND_CRUNTIME) */
                        /* WinSock API(FTS_SYSKIND_WINSOCK) */
  unsigned long ab_errno;        /* Error number */
  char ab_promes[256];           /* Protocol message (error) */
 
#ifndef FTS_API_64BIT
  /* Data when transmission of more than 4 gigabytes of */
  /* data was successful  */
  DWORD trans_size_Low;      /* Transmitted data size (value
                                of the trailing 32 bits). */
  LONG trans_size_High;      /* Transmitted data size (value
                                of the leading 32 bits). */
  DWORD trans_size_comp_Low; /* Transmitted data size
                                after compression (value
                                of the leading 32 bits). */
  LONG trans_size_comp_High; /* Transmitted data size
                                after compression (value
                                of the trailing 32 bits). */
#endif
 
  char reserve[1668];     /* Reserved area */
} FTS_FTP_API_RETDATA_EX;

To Page Top

Compiling and linking

To Page Top

Notes about using libraries

To Page Top

Trademarks

All Rights Reserved. Copyright (C) 2016, Hitachi, Ltd.