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

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

5. Функции.

Названия большинства функций REXX FTP API созвучны соответствующим подкомандам FTP. Поэтому в них легко ориентироваться тем, кто знаком с основами FTP.

5.1. FtpAppend().

Копирует файл с вашей рабочей станции на сервер FTP, добавляя его в конец существующего на сервере файла.
Синтаксис: 
rc = FtpAppend( 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 открыта, то сначала функция FtpAppend() проверяет наличие соединения с сервером FTP и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

5.2. FtpChDir().

Переходит в указанный каталог на сервере FTP и делает его текущим.
Синтаксис: 
rc = FtpChDir( 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 открыта, то сначала функция FtpChDir() проверяет наличие соединения с сервером FTP и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

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

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

Пример:

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

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

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpChDir 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

   if pDir \= '/' then do
      rc = FtpChDir( pDir )
      if rc = -1 then do
         say ''
         say 'FtpChDir()   FTPERRNO='||FTPERRNO
         signal halt
      end
   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 rxFtpChDir.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpChDir 127.0.0.1/Data/Ftp/Public

   "E:/data/ftp/public" is current directory.

   X:>rxFtpChDir ftp.software.ibm.com/pub

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

FtpLogoff(), FtpMkDir(), FtpPwd(), FtpRmDir(), FtpSetUser()

5.3. FtpDelete().

Удаляет файл на сервере FTP.
Синтаксис: 
rc = FtpDelete( remoteFile )
Параметры:

remoteFile
имя файла на сервере FTP

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

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

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

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

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

Описание:

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

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

Затем отправляет на сервер следующую последовательность команд: 
   DELE <содержимое параметра remoteFile>
 Если выполнение прошло успешно, то файл на сервере удаляется.

Пример:

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

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

   if pHost = '' | pFile = '/' then do
      say ''
      say 'Usage: rxFtpDelete host/file'
      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 = FtpDelete( pFile )
   if rc = -1 then do
      say ''
      say 'FtpDelete()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File '||pFile||' deleted OK'
   end

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

   File /Data/Ftp/Test.txt deleted OK
Связанные функции:

FtpAppend(), FtpGet(), FtpLogoff(), FtpPut(), FtpPutUnique(), FtpRename(), FtpSetUser()

5.4. FtpDir().

Получает список содержимого каталога сервера FTP в развернутом виде.
Синтаксис: 
rc = FtpDir( pPattern, pStem )
Параметры:

pPattern
шаблон выборки содержимого каталога.
Может содержать имя файла, имя каталога или шаблон имени файла с использованием символов-заменителей '*' и '?'.

Назначение символов-заменителей стандартно:
'?' заменяет один любой символ в имени
'*' заменяет любое количество символов в имени

Если в шаблоне не указан путь, то он применяется к содержимому текущего каталога.
pStem
строка, определяющая имя-основу набора переменных, в который будут помещены результаты;
строка обязательно должна заканчиваться точкой ('.').


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

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

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

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

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

Описание:

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

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

Затем, в зависимости от выбранного режима FTP (активный или пассивный), отправляет на сервер одну из следующих последовательностей команд: 
   PORT <данные>    активный режим (по умолчанию)
   LIST <содержимое параметра pPattern>
или
   PASV             пассивный режим
   LIST <содержимое параметра pPattern>
 Если выполнение прошло успешно, то результатами заполняется набор переменных, имя-основа которых задаётся параметром pStem. Количество записей заносится в переменную из этого набора с индексом 0.

Например, пусть параметр pStem содержит строку 'files.'. Тогда в переменную files.0 будет помещено количество записей в списке, а сами записи будут последовательно помещены в переменные files.1, files.2 и т.д.

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

Примечание:

Строка, передаваемая в параметре pPattern, может содержать имя файла, имя каталога или шаблон имени файла с символами-заменителями '*' и '?'.

Казалось бы, указав в качестве шаблона строку '*', можно получить полный список содержимого текущего каталога.

Однако серверы FTP неоднозначно обрабатывают такой запрос. Некоторые выдают ожидаемый список содержимого текущего каталога. Другие выдают список, в котором отсутствуют имена подкаталогов. Третьи же, выдав список файлов текущего каталога, заодно выдают и списки содержимого подкаталогов текущего каталога.

Поэтому для получения списка содержимого текущего каталога лучше использовать строку '.' (т.е. имя текущего каталога) в качестве параметра.

Такой запрос все серверы FTP обрабатывают однозначно.

Пример:

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

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

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpDir 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

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

   rc = FtpDir( '.', 'xFile.' )
   if rc = -1 then do
      say ''
      say 'FtpDir()   FTPERRNO='||FTPERRNO
   end
   else do
      if xFile.0 > 0 then do
         say ''
         do i = 1 to xFile.0
            say xFile.i
         end
      end
   end

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

   351      A          04-11-10   11:10  error.log
     0      A    DIR   04-12-10   08:59  Misc Tools
     0           DIR   04-10-10   08:33  Public
    50                 04-10-10   08:34  ReadMe.txt
    10      A          04-10-10   13:57  Test.txt

   X:>rxFtpDir ftp.software.ibm.com/pub

   total 520
   -rw-r--r--   1 102004493 201  192970 Jan 28 2001  00_Catalog
   -rw-r--r--   1 102004493 201     802 Jan 14 1999  00_index
   -rw-r--r--   1 102004493 201     595 Jan 14 1999  00_index.tab
   -rw-r--r--   1 102004493 201    2095 Jan 17 1999  User_Documentation
   -rw-r--r--   1 102004493 201    5890 Jan 19 1999  User_Documentation.990517.rsr
   dr-xr-x--x   2 102004493 201     256 Aug  4 2008  bin
   drwxrwxr-x   4 102004493 201     256 Jan  1 1980  comm
   drwxrwxr-x  13 102004493 201    4096 Feb  9 08:02 demos
   <...пропуск...>
Связанные функции:

FtpLogoff(), FtpLs(), FtpSetActiveMode(), FtpSetUser()

5.5. FtpDropFuncs().

Сбрасывает регистрацию всех функций REXX FTP API и делает их недоступными для использования.
Синтаксис: 
rc = FtpDropFuncs( )
Параметры:

Параметров нет.

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

Функции FtpLoadFuncs() и FtpDropFuncs() возвращают 0 в случае успешного выполнения.

Значение специальной переменной FTPERRNO не изменяется.

Описание:

Сбрасывает регистрацию и делает недоступными для использования все функции REXX FTP API.

Затем, чтобы выгрузить DLL, обеспечивающий работу REXX FTP API, необходимо закрыть все сессии (CMD.EXE), в которых выполнялись программы REXX, использующие REXX FTP API. Библиотека будет освобождена системой и её можно будет удалить или заменить.

Пример:

Чтобы получить возможность выгрузить DLL, обеспечивающий работу REXX FTP API, необходимо включить в программу следующую инструкцию: 
   rc = FtpDropFuncs()
Связанные функции:

FtpLoadFuncs()