Опыт применения REXX FTP API - Функции

Индекс материала
Опыт применения REXX FTP API
Введение
Установка
Коды возврата
Функции
Замечания по применению
Послесловие
Страница 7 из 11

5.10. FtpMkDir().

Создаёт новый каталог на сервере FTP.
Синтаксис: 
rc = FtpMkDir( remoteDir )
Параметры:

remoteDir
имя каталога на сервере FTP

Возвращаемое значение:

Функция возвращает одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет;
специальной переменной FTPERRNO присвоено значение 0
-1 ошибка во время выполнения;
код ошибки помещён в специальную переменную FTPERRNO

Специальной переменной FTPERRNO присваивается одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет
FTPSERVICE неизвестный сервис
FTPHOST неизвестный хост
FTPSOCKET невозможно получить сокет
FTPCONNECT невозможно соединиться с сервером
FTPLOGIN регистрация не выполнена
FTPABORT передача данных прервана
FTPLOCALFILE проблемы с открытием локального файла
FTPDATACONN проблемы с инициализацией соединения
FTPCOMMAND выполнение команды прервано, соединение с сервером может быть разорвано
FTPPROXYTHIRD прокси-сервер не поддерживает передачу третьей стороне
FTPNOPRIMARY нет первичного соединения для передачи по доверенности (proxy transfer)
FTPFAILURE команда не выполнена, соединение с сервером сохранено

Описание:

Если сессия FTP открыта, то сначала функция FtpMkDir() проверяет наличие соединения с сервером FTP и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

Имя или адрес сервера, имя пользователя и пароль задаются при открытии сессии FTP функцией FtpSetUser().

Затем отправляет на сервер следующую последовательность команд: 
   MKD <содержимое параметра remoteDir>
 Если выполнение прошло успешно, то на сервере создаётся новый каталог.

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя или адрес хоста и имя каталога на сервере. Затем создаёт новый каталог, делает его текущим и отображает его имя. 
   /* rxFtpMkDir.cmd - function example */
   parse arg pHost '/' pDir

   pDir = '/'||Strip( pDir );

   if pHost = '' | pDir = '/' then do
      say ''
      say 'Usage: rxFtpMkDir host/dir'
      say ''
      exit 1
   end

   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpSetUser( pHost, 'anonymous', 'anonymous@guest.ftp' )
   if rc \= 1 then do
      say 'FtpSetUser() - Not connected'
      exit 1
   end

   rc = FtpMkDir( pDir )
   if rc = -1 then do
      say ''
      say 'FtpMkDir()   FTPERRNO='||FTPERRNO
      signal halt
   end

   rc = FtpChDir( pDir )
   if rc = -1 then do
      say ''
      say 'FtpChDir()   FTPERRNO='||FTPERRNO
      signal halt
   end

   rc = FtpPwd( xPwd )
   if rc = -1 then do
      say ''
      say 'FtpPwd()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say xPwd
   end

   halt:
   rc = FtpLogoff()
   /* end of file rxFtpMkDir.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpMkDir 127.0.0.1/Data/Ftp/Other

   "E:/data/ftp/other" is current directory.
Связанные функции:

FtpChDir(), FtpLogoff(), FtpPwd(), FtpRmDir(), FtpSetUser()

5.11. FtpPing().

Проверяет доступность хоста.
Синтаксис: 
rc = FtpPing( pHost, pLength )
Параметры:

pHost
имя или адрес хоста
pLength
длина порции данных в пакете ICMP (минимальное значение: 1)


Возвращаемое значение:

Функция FtpPing() возвращает одно из следующих значений:

Значение Описание
<число> нормальное завершение, ошибок нет;
время в миллисекундах, прошедшее от отправки запроса до получения ответа
PINGREPLY хост не отвечает
PINGSOCKET невозможно получить сокет
PINGPROTO неизвестный протокол ICMP
PINGSEND передача завершилась с ошибкой
PINGRECV приём завершился с ошибкой
PINGHOST неизвестный хост

Cпециальной переменной FTPERRNO всегда присваивается значение 0.

Описание:

Вполне самостоятельная функция, никак не связанная с остальными функциями REXX FTP API (за исключением FtpLoadFuncs() и FtpDropFuncs()). Более того, она даже не использует FTP.

Получив имя хоста в качестве параметра, FtpPing() посылает запрос на получение адреса хоста серверу DNS. Если сервер DNS в системе не определён, то для поиска адреса хоста используется файл TCPIP\ETC\HOSTS.

Затем FtpPing посылает указанному хосту одиночный пакет ICMP "запрос-отклика" ("echo-request") заданной длины и ожидает ответ опрашиваемой системы.

Получив ответ, возвращает в вызывающую функцию число - промежуток времени между посылкой запроса и получением ответа в миллисекундах. Если ответ не пришёл за определённое время, то возвращает код ошибки.

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя или адрес хоста. А затем проверяет доступность указанного хоста (т.е. "пингует" его). 
   /* rxFtpPing.cmd - function example */
   parse arg pHost .

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpPing host'
      say ''
      exit 1
   end

   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpPing( pHost, 64 )
   if DataType(rc, 'N') then do
      say ''
      say pHost||'   ping='||rc||'ms'
   end
   else do
      say ''
      say pHost||'   error='||rc
   end
   /* end of file rxFtpPing.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpPing 127.0.0.1

   127.0.0.1   ping=0ms

   X:>rxFtpPing ftp.software.ibm.com

   ftp.software.ibm.com   error=PINGREPLY
Связанные функции:

Связанных функций нет.

5.12. FtpProxy().

Организует копирование файла напрямую с одного сервера на другой.
Синтаксис: 
rc = FtpProxy( toHost, toUser, toPass, toAcct,
               fromHost, fromUser, fromPass, fromAcct,
               toFile, fromFile, pMode )
Параметры:

toHost
имя или адрес хоста-получателя
toUser
имя пользователя хоста-получателя
toPass
пароль пользователя хоста-получателя
toAcct
аккаунт пользователя хоста-получателя; если не требуется должна быть указана пустая строка
fromHost
имя или адрес хоста-отправителя
fromUser
имя пользователя хоста-отправителя
fromPass
пароль пользователя хоста-отправителя
fromAcct
аккаунт пользователя хоста-отправителя; если не требуется должна быть указана пустая строка
toFile
имя файла-назначения с указанием пути куда копируется файл
fromFile
имя файла-источника с указанием пути откуда копируется файл
pMode
строка, определяющая режим передачи файлов:
'Ascii' текстовый
'Binary' двоичный

Возвращаемое значение:

Функция возвращает одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет;
специальной переменной FTPERRNO присвоено значение 0
-1 ошибка во время выполнения;
код ошибки помещён в специальную переменную FTPERRNO

Специальной переменной FTPERRNO присваивается одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет
FTPSERVICE неизвестный сервис
FTPHOST неизвестный хост
FTPSOCKET невозможно получить сокет
FTPCONNECT невозможно соединиться с сервером
FTPLOGIN регистрация не выполнена
FTPABORT передача данных прервана
FTPLOCALFILE проблемы с открытием локального файла
FTPDATACONN проблемы с инициализацией соединения
FTPCOMMAND выполнение команды прервано, соединение с сервером может быть разорвано
FTPPROXYTHIRD прокси-сервер не поддерживает передачу третьей стороне
FTPNOPRIMARY нет первичного соединения для передачи по доверенности (proxy transfer)
FTPFAILURE команда не выполнена, соединение с сервером сохранено

Описание:

Вполне самостоятельная функция, никак не связанная с остальными функциями REXX FTP API (за исключением FtpLoadFuncs() и FtpDropFuncs()).

Получив имена хостов в качестве параметров, FtpProxy() посылает запросы на получение адресов хостов серверу DNS. Если сервер DNS в системе не определён, то для поиска адресов хостов используется файл TCPIP\ETC\HOSTS.

Затем FtpProxy() соединяется с серверами FTP, работающими на заданных хостах, и отправляет им команды в следующей последовательности: 
   Получатель         Отправитель
   ------------------------------
   USER <toUser>
   PASS <toPass>
   ACCT <toAcct>
   PWD
   TYPE <I|A>                           I=Binary, A=Ascii
                      USER <fromUser>
                      PASS <fromPass>
                      ACCT <fromAcct>
                      PWD
                      TYPE <I|A>        I=Binary, A=Ascii
                      PASV
   PORT <данные,
         которые
         вернула
         команда
         PASV
         переданная
         источнику>
   STOR <toFile>
                      RETR <fromFile>
   QUIT
                      QUIT
 вынуждая сервер-получатель получить файл напрямую с сервера-отправителя.

Имя файла-назначения может отличаться от имени файла-источника.

Примечание:

В оригинальной документации отмечено, что параметр, определяющий режим передачи файлов не обязателен. Однако, если его опустить или задать неправильное значение, то FtpProxy() просто вернёт код возврата равный 0, не выполняя никаких действий.

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имена или адреса хостов и имена исходного и сохраняемого файлов. А затем организует передачу файла напрямую между серверами. 
   /* rxFtpProxy.cmd - function example */
   parse arg pTo pFrom .

   parse var pTo toHost '/' toFile
   parse var pFrom fromHost '/' fromFile

   toFile = '/'||Strip( toFile )
   fromFile = '/'||Strip( fromFile )

   if toHost = '' | toFile = '/' | fromHost = '' | fromFile = '/' then do
      say ''
      say 'Usage: rxFtpProxy targetHost/targetFile sourceHost/sourceFile'
      say ''
      exit 1
   end

   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpProxy( toHost, 'anonymous', 'anonymous@guest.ftp', '', ,
                  fromHost, 'anonymous', 'anonymous@guest.ftp', '', ,
                  toFile, fromFile, 'Binary' )
   if rc = -1 then do
      say ''
      say 'FtpProxy()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File transferred OK'
   end
   /* end of file rxFtpProxy.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpProxy 127.0.0.1/Data/Ftp/x.txt ftp.software.ibm.com/robots.txt

   FtpProxy()   FTPERRNO=FTPCOMMAND

   X:>rxFtpProxy ftp.mydomain.com/robots.txt ftp.software.ibm.com/robots.txt

   File transferred OK
Связанные функции:

Связанных функций нет.

5.13. FtpPut().

Копирует локальный файл с рабочей станции на сервер FTP, заменяя существующий.
Синтаксис: 
rc = FtpPut( localFile, remoteFile [, pMode] )
Параметры:

localFile
имя файла на локальной рабочей станции
remoteFile
имя файла на сервере FTP
pMode
(необязательный) строка, определяющая режим передачи файлов:
'Ascii' текстовый
'Binary' двоичный

Возвращаемое значение:

Функция возвращает одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет;
специальной переменной FTPERRNO присвоено значение 0
-1 ошибка во время выполнения;
код ошибки помещён в специальную переменную FTPERRNO

Специальной переменной FTPERRNO присваивается одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет
FTPSERVICE неизвестный сервис
FTPHOST неизвестный хост
FTPSOCKET невозможно получить сокет
FTPCONNECT невозможно соединиться с сервером
FTPLOGIN регистрация не выполнена
FTPABORT передача данных прервана
FTPLOCALFILE проблемы с открытием локального файла
FTPDATACONN проблемы с инициализацией соединения
FTPCOMMAND выполнение команды прервано, соединение с сервером может быть разорвано
FTPPROXYTHIRD прокси-сервер не поддерживает передачу третьей стороне
FTPNOPRIMARY нет первичного соединения для передачи по доверенности (proxy transfer)
FTPFAILURE команда не выполнена, соединение с сервером сохранено

Описание:

Если сессия FTP открыта, то сначала функция FtpPut() проверяет наличие соединения с сервером FTP и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

Имя или адрес сервера, имя пользователя и пароль задаются при открытии сессии FTP функцией FtpSetUser().

Затем, в зависимости от выбранного режима FTP (активный или пассивный), отправляет на сервер одну из следующих последовательностей команд: 
   TYPE <I|A>       I=Binary, A=Ascii
   PORT <данные>    активный режим (по умолчанию)
   STOR <содержимое параметра remoteFile>
или
   TYPE <I|A>       I=Binary, A=Ascii
   PASV             пассивный режим
   STOR <содержимое параметра remoteFile>
 Если выполнение прошло успешно, то файл на сервере FTP переписывается данными из локального файла на рабочей станции.

Режим FTP нужно переключить заранее функцией FtpSetActiveMode() (по умолчанию, активный).

Если параметр pMode опущен, то выбирается режим передачи файлов ранее установленный функцией FtpSetBinary() (по умолчанию, двоичный).

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя локального файла, имя или адрес хоста и имя файла на сервере. А затем копирует файл с рабочей станции на сервер в файл с указанным именем. 
   /* rxFtpPut.cmd - function example */
   parse arg fromFile pHost '/' toFile

   toFile = '/'||Strip( toFile );

   if pHost = '' | toFile = '/' then do
      say ''
      say 'Usage: rxFtpPut localfile host/remotefile'
      say ''
      exit 1
   end

   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpSetUser( pHost, 'anonymous', 'anonymous@guest.ftp' )
   if rc \= 1 then do
      say 'FtpSetUser() - Not connected'
      exit 1
   end

   rc = FtpPut( fromFile, toFile, 'Binary' )
   if rc = -1 then do
      say ''
      say 'FtpPut()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File '||fromFile||' transferred to '||toFile||' OK'
   end

   rc = FtpLogoff()
   /* end of file rxFtpPut.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpPut xxx.txt 127.0.0.1/Data/Ftp/Test.txt

   File xxx.txt transferred to /Data/Ftp/Test.txt OK

   X:>rxFtpPut C:\readme.txt 127.0.0.1/Data/Ftp/readme.txt

   File C:\readme.txt transferred to /Data/Ftp/readme.txt OK
Связанные функции:

FtpAppend(), FtpDelete(), FtpLogoff(), FtpGet(), FtpPutUnique(), FtpRename(), FtpSetActiveMode(), FtpSetBinary(), FtpSetUser()

5.14. FtpPutUnique().

Копирует локальный файл с рабочей станции на сервер FTP в файл с уникальным именем.
Синтаксис: 
rc = FtpPutUnique( localFile, remoteFile [, pMode] )
Параметры:

localFile
имя файла на локальной рабочей станции
remoteFile
имя файла на сервере FTP
pMode
(необязательный) строка, определяющая режим передачи файлов:
'Ascii' текстовый
'Binary' двоичный

Возвращаемое значение:

Функция возвращает одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет;
специальной переменной FTPERRNO присвоено значение 0
-1 ошибка во время выполнения;
код ошибки помещён в специальную переменную FTPERRNO

Специальной переменной FTPERRNO присваивается одно из следующих значений:

Значение Описание
0 нормальное завершение, ошибок нет
FTPSERVICE неизвестный сервис
FTPHOST неизвестный хост
FTPSOCKET невозможно получить сокет
FTPCONNECT невозможно соединиться с сервером
FTPLOGIN регистрация не выполнена
FTPABORT передача данных прервана
FTPLOCALFILE проблемы с открытием локального файла
FTPDATACONN проблемы с инициализацией соединения
FTPCOMMAND выполнение команды прервано, соединение с сервером может быть разорвано
FTPPROXYTHIRD прокси-сервер не поддерживает передачу третьей стороне
FTPNOPRIMARY нет первичного соединения для передачи по доверенности (proxy transfer)
FTPFAILURE команда не выполнена, соединение с сервером сохранено

Описание:

Если сессия FTP открыта, то сначала функция FtpPutUnique() проверяет наличие соединения с сервером FTP и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

Имя или адрес сервера, имя пользователя и пароль задаются при открытии сессии FTP функцией FtpSetUser().

Затем, в зависимости от выбранного режима FTP (активный или пассивный), отправляет на сервер одну из следующих последовательностей команд: 
   TYPE <I|A>       I=Binary, A=Ascii
   PORT <данные>    активный режим (по умолчанию)
   STOU <содержимое параметра remoteFile>
или
   TYPE <I|A>       I=Binary, A=Ascii
   PASV             пассивный режим
   STOU <содержимое параметра remoteFile>
 Если выполнение прошло успешно, то выполняется копирование локального файла рабочей станции на сервер.

Если файл с указанным именем уже существует на сервере, то к имени файла последовательно добавляется индекс 1, 2 и т.д.

Например, если делается попытка сохранить файл readme.txt, а он уже существует, то пробуют сохранить в файл readme1.txt. Если же и он существует, то пытаются сохранить в файл readme2.txt и так до тех пор пока не обнаружится свободное имя файла.

Режим FTP нужно переключить заранее функцией FtpSetActiveMode() (по умолчанию, активный).

Если параметр pMode опущен, то выбирается режим передачи файлов ранее установленный функцией FtpSetBinary() (по умолчанию, двоичный).

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя локального файла, имя или адрес хоста и имя файла на сервере. А затем копирует файл с рабочей станции на сервер в файл с указанным именем. 
   /* rxFtpPutUnique.cmd - function example */
   parse arg fromFile pHost '/' toFile

   toFile = '/'||Strip( toFile );

   if pHost = '' | toFile = '/' then do
      say ''
      say 'Usage: rxFtpPutUnique localfile host/remotefile'
      say ''
      exit 1
   end

   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpSetUser( pHost, 'anonymous', 'anonymous@guest.ftp' )
   if rc \= 1 then do
      say 'FtpSetUser() - Not connected'
      exit 1
   end

   rc = FtpPutUnique( fromFile, toFile, 'Binary' )
   if rc = -1 then do
      say ''
      say 'FtpPutUnique()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File '||fromFile||' transferred to '||toFile||' OK'
   end

   rc = FtpLogoff()
   /* end of file rxFtpPutUnique.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpPutUnique xxx.txt 127.0.0.1/Data/Ftp/Test.txt

   File xxx.txt transferred to /Data/Ftp/Test.txt OK

   X:>rxFtpPutUnique C:\readme.txt 127.0.0.1/Data/Ftp/readme.txt

   File C:\readme.txt transferred to /Data/Ftp/readme.txt OK
Связанные функции:

FtpAppend(), FtpDelete(), FtpLogoff(), FtpGet(), FtpPut(), FtpRename(), FtpSetActiveMode(), FtpSetBinary(), FtpSetUser()



Главное меню