JP1/File Transmission Server/FTP（Windows(R)用）

ライブラリの使用方法

JP1/FTP APIライブラリは，JP1/FTPのファイル伝送機能をユーザプログラムから利用するときに使用します。

JP1/FTP APIライブラリを使用して，次のことができます。

• 一つのユーザプログラムから複数のホスト上（同一ホストでもよい）で動作する複数のJP1/FTPに伝送要求を登録できます。
• 伝送要求の登録には，同期型と非同期型があります。
  同期型：伝送が終了するまで待ち，終了結果を取得できます。
  非同期型：登録だけをして，あとで終了結果だけを取得できます。
  

関数を使用するための前提条件

JP1/FTPが提供する関数を使用するために必要なものを次に示します。

• JP1/FTP APIライブラリ
• コンパイラー：Visual C++

ユーザプログラムで使用できる言語を次に示します。

• C
• C++

JP1/FTP APIライブラリが前提とするコンパイラーを次に示します。

表7-1　JP1/FTP APIライブラリが前提とするコンパイラー

OS	コンパイラー	ヘッダファイル	インポートライブラリ
Windows Server 2003	Visual C++ 4.0	apihead.h	FTSFTP40.lib
	Visual C++ 5.0	apihead.h	FTSFTP50.lib
	Visual C++ 6.0	apihead.h	FTSFTP.lib
	Visual Studio 2005 (SP1)	apihead.h	FTSFTP80.lib
	Visual Studio 2008	apihead.h	FTSFTP90.lib
Windows Server 2003 (IPF)	Platform SDK February 2003	apihead.h	FTSFTP.lib
	Visual Studio 2005 (SP1)	apihead.h	FTSFTP80.lib
	Visual Studio 2008	apihead.h	FTSFTP90.lib
Windows Server 2008	Visual Studio 2005 (SP1)	apihead.h	FTSFTP80.lib
	Visual Studio 2008	apihead.h	FTSFTP90.lib
Windows Server 2008 (IPF)	Visual Studio 2005 (SP1)	apihead.h	FTSFTP80.lib
	Visual Studio 2008	apihead.h	FTSFTP90.lib

ヘッダファイルおよびインポートライブラリについては，各OSに対応したJP1/FTPに格納されているものを使用してください。格納先は，「付録A ファイルおよびディレクトリ一覧」を参照してください。

環境設定

SERVICESの設定

JP1/FTP Clientのサービス名「ftsc」を設定します。詳しくは，「2.2.2 ポート番号を設定する」を参照してください。

HOSTSの設定

クライアント側のJP1/FTPが動作しているホストのホスト名とIPアドレスを設定します。このホスト名はfts_ftp_open()の第1引数，伝送情報構造体で指定します。

OSのインストールディレクトリ\system32\drivers\etc\HOSTSに次の1行を追加してください。

 
xxx.xxx.xxx.xxx      yyyyyy

（凡例）

xxx.xxx.xxx.xxx：IPアドレス

yyyyyy：ホスト名

コーディング

伝送情報の指定

ファイル伝送要求の登録は，fts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()の引数に登録済みの伝送カード名や伝送情報構造体のアドレスを設定します。

• カード名称による伝送要求の登録
  ［伝送の登録／実行］で登録した伝送カード名を指定することで，伝送要求を登録できます。
  
• 伝送情報構造体による伝送情報の指定
  伝送に必要な情報を指定することで，伝送要求を登録できます。
  

• 伝送情報構造体

typedef struct _FTS_FTP_API_DATA_EX {
    char cardname[20+1];
    char host[256+1];
    unsigned int portnum;
    char username[50+1];
    char password[50+1];
    int type;
    int cmd;
    int mode;
    char quote[300+1];
    char localname[260+1];
    char remotename[260+1];
    char end_program[260+1];
    char abend_program[260+1];
    char comment[80+1];
    int fsize;
    char reserve[1240];     /*予約領域*/
} FTS_FTP_API_DATA_EX;
 

• 伝送情報構造体メンバの内容

cardname   :カード名称を指定します。
host       :FTPのホスト名を指定します。ftp>open aaaa
portnum    :FTPのポート番号を指定します。ftp>open aaaa bbbb
username   :ログイン名を指定します。ftp>user aaaa
password   :パスワードを指定します。
type       :伝送モードを指定します。
                 FTS_TYPE_A     データをASCIIコードと解釈し，送信します。
                     ftp>ascii
                 FTS_TYPE_I      データをイメージと解釈し，送信します。
                     ftp>binary
cmd        :伝送の種類を指定します。
            単／複伝送をORで指定することで，単一ファイル伝送または
            複数ファイル伝送を組み合わせて指定できます。
            ただし，この指定は受信の場合だけ有効です。
            伝送の種類
                 FTS_CMD_SEND  送信します。 ftp>put aaaa bbbb
                 FTS_CMD_RECV  受信します。 ftp>get cccc ddddd
                 FTS_CMD_APPE  送信（追加）します。 ftp>append eeee fffff
            単／複伝送
                 FTS_MLT_AUTO   単一ファイル伝送と複数ファイル伝送を
                                自動で切り替えます。デフォルトです。
                 FTS_MLT_MULTIPLE  複数ファイル伝送をします。
                 FTS_MLT_SINGLE    単一ファイル伝送をします。
            FTS_MLT_AUTOでは，次のように伝送が自動切り替えされます。
                 送信の場合:ローカルファイル名に，*または?が使用されている
                            か判定し，*または?が使用されていれば複数ファイ
                            ル伝送に，使用されていなければ単一ファイル伝送
                            に切り替わります。
                 受信の場合:リモートファイル名に，*または?が使用されている
                            か判定し，*または?が使用されていれば複数ファイ
                            ル伝送に，使用されていなければ単一ファイル伝送
                            に切り替わります。
            （例）
            単一ファイルの受信
            cmd = FTS_CMD_RECV | FTS_MLT_SINGLE;
mode       :圧縮伝送の指定します。
                 FTS_MODE_S  圧縮伝送をしません。
                 FTS_MODE_C  圧縮伝送をします。
quote      :実行したいFTPコマンドを指定します。
                 CWD，SITEなどのコマンドをセミコロン（';'）で
                 区切った文字列（文字列の最後は'\0'）
localname  :ローカルファイル名を指定します。
                 （例）ftp>put aaaa bbbb
                      ftp>get cccc dddd
remotename :リモートファイル名を指定します。
                 （例）ftp>put aaaa bbbb
                      ftp>get cccc dddd
end_program  :伝送正常終了時に起動するプログラム名をフルパスで指定します。
abend_program:伝送異常終了時に起動するプログラム名をフルパスで指定します。
comment      :任意の文字列を指定できます。
fsize        :伝送後のファイルサイズ確認の有無を指定します。
                 FTS_FSIZE_TRUE  サイズ確認をします。
                 FTS_FSIZE_FALSE  サイズ確認をしません。

注意事項

char型の変数値の最後は，「\0」にしてください。

伝送終了情報の取得

fts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()で登録した伝送要求に対する終了情報を取得できます。

• fts_ftp_syn_request_ex()で要求を登録した場合
  fts_ftp_syn_request_ex()の第4引数に伝送終了情報構造体のアドレスを指定します。
  
• fts_ftp_asyn_request_ex()で要求を登録した場合
  fts_ftp_event_ex()の第2引数に伝送終了情報構造体のアドレスを指定します。
  

• 伝送終了情報構造体（IPF以外の場合）

typedef struct _FTS_FTP_API_RETDATA_EX {
  /* 常時のデータ */
  int trans_status;          /* 伝送終了状態 成功（TRANS_SUCCESS） */
                             /* 伝送終了情報 失敗（TRANS_FAILURE） */
  char cardname[20+1];       /* カード名称 */
  unsigned long trno;        /* 伝送番号 */
  unsigned long trcno;       /* 接続番号 */
 
  /* 伝送成功時のデータ */
  unsigned long trans_size;  /* 伝送データサイズ */
 
  /* 伝送（圧縮）成功時のデータ */
  unsigned long trans_size_comp; /* 圧縮後伝送データサイズ */
 
  /* 失敗時のデータ */
  int ab_kind;               /* システムコールエラー(FTS_ERR_SYSTEM) */
                             /* 論理エラー(FTS_ERR_LOGIC) */
                             /* プロトコルエラー(FTS_ERR_PROTOCOL) */
  char ab_place[8];          /* エラー発生場所 */
  char ab_func[32];          /* エラー発生モジュール名称 */
  char ab_system[32];        /* システムコール名称 */
  int ab_syskind;            /* システムコール種別 */
                             /* Win32 API(FTS_SYSKIND_WIN32) */
                             /* C runtime(FTS_SYSKIND_CRUNTIME) */
                             /* WinSock API(FTS_SYSKIND_WINSOCK) */
  unsigned long ab_errno;    /* エラー番号 */
  char ab_promes[256];       /* プロトコルメッセージ（エラー） */
 
  /* 4ギガバイトを超えた伝送成功時のデータ */
  DWORD trans_size_Low;      /* 伝送データサイズ（下位32ビットの値）*/
  LONG trans_size_High;      /* 伝送データサイズ（上位32ビットの値）*/
 
  /* 4ギガバイトを超えた伝送（圧縮）成功時のデータ */
  DWORD trans_size_comp_Low;
                          /* 圧縮後伝送データサイズ（上位32ビットの値）*/
  LONG trans_size_comp_High;
                          /* 圧縮後伝送データサイズ（下位32ビットの値）*/
 
  char reserve[1668];     /* 予約領域 */
} FTS_FTP_API_RETDATA_EX;
 

• 伝送終了情報構造体（IPFの場合）

typedef struct _FTS_FTP_API_RETDATA_EX {
  /* 常時のデータ */
  int trans_status;          /* 伝送終了状態 成功（TRANS_SUCCESS） */
                             /* 伝送終了情報 失敗（TRANS_FAILURE） */
  char cardname[20+1];       /* カード名称 */
  unsigned long trno;        /* 伝送番号 */
  unsigned long trcno;       /* 接続番号 */
 
  /* 伝送成功時のデータ */
  __int64 trans_size;        /* 伝送データサイズ */
 
  /* 伝送（圧縮）成功時のデータ */
  __int64 trans_size_comp;   /* 圧縮後伝送データサイズ */
 
  /* 失敗時のデータ */
  int ab_kind;               /* システムコールエラー(FTS_ERR_SYSTEM) */
                             /* 論理エラー(FTS_ERR_LOGIC) */
                             /* プロトコルエラー(FTS_ERR_PROTOCOL) */
  char ab_place[8];          /* エラー発生場所 */
  char ab_func[32];          /* エラー発生モジュール名称 */
  char ab_system[32];        /* システムコール名称 */
  int ab_syskind;            /* システムコール種別 */
                             /* Win32 API(FTS_SYSKIND_WIN32) */
                             /* C runtime(FTS_SYSKIND_CRUNTIME) */
                             /* WinSock API(FTS_SYSKIND_WINSOCK) */
  unsigned long ab_errno;    /* エラー番号 */
  char ab_promes[256];       /* プロトコルメッセージ（エラー） */
  char reserve[1684];        /* 予約領域 */
} FTS_FTP_API_RETDATA_EX;
 

• 伝送終了情報構造体メンバの内容

  trans_status       :伝送の終了状態を示す次の値を返します。
                           TRANS_SUCCESS（正常終了）
                           TRANS_FAILURE（異常終了）
  cardname           :伝送のカード名称を返します。
  trno               :伝送番号を返します。
  trcno              :接続番号を返します。
  trans_size         :（正常終了時だけ）
                           伝送データサイズ
  trans_size_comp    :（正常終了時だけ）
                           伝送データサイズ（圧縮）
  ab_kind            :（異常終了時だけ）
                           エラー種別を返します。
                           FTS_ERR_SYSTEM（システムコールエラー）
                           FTS_ERR_LOGIC（論理エラー）
                           FTS_ERR_PROTOCOL（プロトコルエラー）
  ab_place             :（異常終了時だけ）
                           エラー発生場所を返します。
  ab_func              :（異常終了時だけ）
                           エラー発生モジュール名称を返します。
  ab_system            :（異常終了時だけ）
                           システムコール名称を返します。
  ab_syskind           :（異常終了時だけ）
                           システムコール種別を返します。
                           FTS_SYSKIND_WIN32（Win32 API）
                           FTS_SYSKIND_CRUNTIME（C runtime）
                           FTS_SYSKIND_WINSOCK（WinSock API）
  ab_errno             :（異常終了時だけ）
                           システムコールエラー番号を返します。
  ab_promes            :（異常終了時だけ）
                           FTPサーバより送られてきたプロトコルメッセージを
                           返します。
  trans_size_Low       :（正常終了時だけ）
                           伝送データサイズの下位32ビットの値を返します。
  trans_size_High      :（正常終了時だけ）
                           伝送データサイズの上位32ビットの値を返します。
  trans_size_comp_Low  :（正常終了時だけ）
                           圧縮後の伝送データサイズの下位32ビットの値を返
                           します。
  trans_size_comp_High :（正常終了時だけ）
                           圧縮後の伝送データサイズの上位32ビットの値を返
                           します。
 

• コーディング時の注意事項
  JP1/FTP APIライブラリの関数を使用する前後に，必ず次の関数をコールしてください。
  
  • コール前

  WSAStartUp()      winsockライブラリ
   

  • コール後

  WSACleanUp()      winsockライブラリ
   

  この関数をコールしない場合，ライブラリの関数は正しく動作しません。使用方法については，winsockのマニュアルを参照してください。
  trans_size_Lowとtrans_size_Highは，二つのパラメータを組み合わせて一つの64ビット値を形成します。
  trans_size_comp_Lowとtrans_size_comp_Highは，二つのパラメータを組み合わせて一つの64ビット値を形成します。
  

リンク

ライブラリの関数を使用したプログラムを作成する場合は，FTSFTP.LIBをリンクしてください。

ライブラリ使用時の注意事項

• 次のような使用方法はできません。
  
  • 1プロセスで，マルチスレッドによって複数のfts_ftp_open()を同時に発行
  • 一つのfts_ftp_open()で複数のfts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()を同時に発行（マルチスレッドによるfts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()の同時実行）
• JP1/FTPをバージョンアップした場合，新しいライブラリとヘッダで再コンパイルが必要です。
• ワイルドカード指定した場合，fts_ftp_event_ex()で取得できる伝送終了情報は，次のとおりです。
  正常の場合：最後に伝送したファイルの伝送終了情報
  異常の場合：最初に異常になったファイルの伝送終了情報
  

[目次][前へ][次へ]

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