How to use the library

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

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 */
      int ftps;               /* Use FTPS */
      int scertval;           /* Check the expiration date of the server certificate */
      char cacertpath[260+1]; /* Path to the CA certificate */
      char crlpath[260+1];    /* Path to the CRL */
      char reserve[708];      /* 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.

    Specify FTS_MLT_AUTO when FTS_CMD_SEND or FTS_CMD_APPE is specified as the transmission type.

    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.

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