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

ライブラリの使用方法

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

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

一つのユーザプログラムから複数のホスト上（同一ホストでもよい）で動作する複数のJP1/FTPに伝送要求を登録できます。

伝送要求の登録には，同期型と非同期型があります。
同期型：伝送が終了するまで待ち，終了結果を取得できます。
非同期型：登録だけをして，あとで終了結果だけを取得できます。

言語

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

C

C++

環境設定

/etc/servicesの設定

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

/etc/hostsの設定

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

/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[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;

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

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_SEND | FTS_MLT_MULTIPLE;
            単一ファイルの受信
            cmd = FTS_CMD_RECV | FTS_MLT_SINGLE;
            自動切替で送信(追加)
            cmd = FTS_CMD_APPE | FTS_MLT_AUTO;
               または
            cmd = FTS_CMD_APPE;   
            （単／複伝送指定を省略するとFTS_MLT_AUTOになります。）
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引数に伝送終了情報構造体のアドレスを指定します。

伝送終了情報構造体

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) */
                                  /* 強制終了エラー(FTS_ERR_FORCE) */
  char ab_place[8];               /* エラー発生場所 */
  char ab_func[32];               /* エラー発生モジュール名称 */
  char ab_system[32];             /* システムコール名称 */
  unsigned long ab_errno;         /* エラー番号 */
  char ab_promes[256];            /* プロトコルメッセージ（エラー） */
 
  char full_trans_size[8];        /* 伝送データサイズ */
  char full_trans_size_comp[8];   /* 圧縮後伝送データサイズ */
 
  char reserve[1672];             /* 予約領域 */
} FTS_FTP_API_RETDATA_EX;

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

  trans_status  :伝送の終了状態を示す次の値を返します。
                     TRANS_SUCCESS（正常終了）
                     TRANS_FAILURE（異常終了）
  cardname      :伝送のカード名称を返します。
  trno          :伝送番号を返します。
  trcno         :接続番号を返します。
  trans_size    :（正常終了時だけ）
                     伝送データサイズ（Linux(IPF)の場合に参照します。
                     Linux(IPF)以外の場合は伝送データサイズが4ギガバ
                     イト未満のときだけ参照可能です。）
  trans_size_comp    
                :（正常終了時だけ）
                     圧縮後伝送データサイズ（Linux(IPF)の場合に参照し
                     ます。Linux(IPF)以外の場合は圧縮後伝送データサイズ
                     が4ギガバイト未満のときだけ参照可能です。）
  ab_kind       :（異常終了時だけ）
                   エラー種別を返します。
                     FTS_ERR_SYSTEM（システムコールエラー）
                     FTS_ERR_LOGIC（論理エラー）
                     FTS_ERR_PROTOCOL（プロトコルエラー）
                     FTS_ERR_FORCE（強制終了エラー）
  ab_place      :（異常終了時だけ）
                     エラー発生場所を返します。
  ab_func       :（異常終了時だけ）
                     エラー発生モジュール名称を返します。
  ab_system     :（異常終了時だけ）
                     システムコール名称を返します。
  ab_errno      :（異常終了時だけ）
                     システムコールエラー番号を返します。
  ab_promes     :（異常終了時だけ）
                     サーバ（着信側）より送られてきたプロトコルメッセージ
                     を返します。
  full_trans_size
                :（正常終了時だけ）
                     伝送データサイズ（Linux(IPF)の場合は使用できま
                     せん。Linux(IPF)以外の場合に参照しますが，
                     fts_ftp_buftoll()を使用して参照します。）
  full_trans_size_comp 
                :（正常終了時だけ）
                     圧縮後伝送データサイズ（Linux(IPF)の場合は使用
                     できません。Linux(IPF)以外の場合に参照しますが，
                     fts_ftp_buftoll()を使用して参照します。）

コンパイルとリンク

シングルスレッド・プログラム

すべてのインターフェース，ライブラリはILP32データモデルだけ提供しています。ユーザプログラムもILP32データモデルとして作成，コンパイルおよびリンクしてください（Linux（IPF版）の場合，すべてのインターフェース，ライブラリはLP64データモデルだけ提供しています。ユーザプログラムもLP64データモデルとして作成，コンパイルおよびリンクしてください）。

次に示すライブラリをリンクしてください。
HP-UX (PA-RISC)：libftsftp.aまたはlibftsftp.sl
HP-UX (IPF)：libftsftp.aまたはlibftsftp.so
Solaris，AIX，Linux：libftsftp.aまたはlibftsftp.so
Solarisの場合，共有ライブラリ(.so)をリンクするときは，-L，-Rオプションを指定してください。
（例）cc -o sample sample.c -L/usr/lib/jp1_fts/lib -R/usr/lib/ jp1_fts/lib -lftsftp

fts_ftp_buftoll()を使用する場合は，コンパイルオプション-DFTS_NO_TRANSIZE_LIMITを指定してください。

マルチスレッド・プログラム

すべてのインターフェース，ライブラリはILP32データモデルだけ提供しています。ユーザプログラムもILP32データモデルとして作成，コンパイルおよびリンクしてください（Linux（IPF版）の場合，すべてのインターフェース，ライブラリはLP64データモデルだけ提供しています。ユーザプログラムもLP64データモデルとして作成，コンパイルおよびリンクしてください）。

プリプロセッサへの定義で，FTS_THREAD_SAFEを定義してコンパイルしてください。
（例）cc -D FTS_THREAD_SAFE -c sample.c

HP-UXの場合，libpthread.slをリンクしてください。

Solarisの場合，libpthread.soをリンクしてください。

次に示すライブラリをリンクしてください。
HP-UX (PA-RISC)：libftsftp_r.aまたはlibftsftp_r.sl
HP-UX (IPF)：libftsftp_r.aまたはlibftsftp_r.so
Solaris，AIX，Linux：libftsftp_r.aまたはlibftsftp_r.so

Solarisの場合，共有ライブラリ（.so）をリンクするときは，-L，-Rオプションを指定してください。

AIXの場合，libftsftp_r.soをリンクする場合は，リンクオプションに-brtlを指定してください。

Linuxの場合，libftsftp_r.a またはlibftsftp_r.soをリンクするときは，リンクオプションに-lpthreadを指定してください。

fts_ftp_buftoll()を使用する場合は，コンパイルオプション-DFTS_NO_TRANSIZE_LIMITを指定してください。

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

次のような使用方法はできません。
一つのfts_ftp_open()で複数のfts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()を同時に発行（マルチプロセスによるfts_ftp_syn_request_ex()，fts_ftp_asyn_request_ex()の同時実行）

ワイルドカードを指定した場合，fts_ftp_event_ex()で取得できる伝送終了情報は，次のとおりです。
正常の場合：最後に伝送したファイルの伝送終了情報
異常の場合：最初に異常になったファイルの伝送終了情報

Linuxの場合，共用ライブラリを使用するときは，次の環境変数にライブラリのパスを指定してください。
LD_LIBRARY_PATH
（例）bashの場合
LD_LIBRARY_PATH=/opt/jp1_fts/lib/api/apilib
export LD_LIBRARY_PATH
（例）cshの場合
setenv LD_LIBRARY_PATH /opt/jp1_fts/lib/api/apilib

Linux (IPF)以外での使用で，伝送データサイズまたは圧縮後伝送データサイズが4ギガバイト以上になる場合，伝送終了情報構造体メンバのtrans_sizeおよびtrans_size_compは参照できません。trans_sizeおよびtrans_size_compは，unsigned long型であり，ILP32データモデルの場合，4ギガバイト以上になるとオーバーフローするためです。伝送データサイズまたは圧縮後伝送データサイズが4ギガバイト以上になる場合，伝送終了情報構造体メンバのfull_trans_sizeまたはfull_trans_size_compを参照してください。
Linux (IPF)の場合は，伝送データサイズまたは圧縮後伝送データサイズが4ギガバイト以上になる場合でもそのままtrans_sizeおよびtrans_size_compを参照できます。

伝送終了情報構造体メンバのfull_trans_sizeおよびfull_trans_size_compは直接参照できません。fts_ftp_buftoll()で数値に変換して参照してください。

fts_ftp_buftoll()を使用する場合，変数型long longを使用しますが，コンパイラによってはlong long型がデフォルトでは使用できない場合があります。この場合，long long型を有効にするコンパイルオプションを指定してください。

セカンダリグループを使用する（環境変数JP1FTS_CSUPPLEGROUPをONに設定する）場合で，静的ライブラリを使用する場合は，08-50以降のライブラリとリンクする必要があります。

マルチスレッド・プログラム用ライブラリ使用時の注意事項

HP-UXの場合，HP-UX 11.0以降のカーネル・スレッドにだけ対応しています。DCEスレッドでは動作できません。

POSIXスレッドにだけ対応しています。

fts_errnoには値を設定できません。参照だけできます。

プロセスで1回fts_ftp_open()をコールし，複数スレッドでfts_ftp_syn_request_ex()を同時にコールすると，伝送はシリアルに行います。同時伝送する場合はfts_ftp_syn_request_ex()のコールごとに，fts_ftp_open()をコールしてください。なお，fts_ftp_open()をコールする回数分，fts_ftp_close()も必要です。

一つの fts_ftp_open()でfts_ftp_syn_request_ex()，fts_ftp_asyn_request_ex()を混在してコールすることはできません。混在させた場合，伝送結果が正常に受け取れません。

全API関数は，スレッドの取り消し点となります。

スレッドの取り消しが行われた場合，取り消されたスレッドで使用していたJP1/FTPデーモンとのコネクションは，fts_ftp_close()で必ず解放してください。解放しないでコネクションを継続して使用した場合，伝送結果が正常に受け取れません。

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

[他社商品名称に関する表示]