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

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

5.6. FtpGet().

Копирует одиночный файл с сервера FTP на рабочую станцию в указанный локальный файл.

Синтаксис:

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

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

Затем, в зависимости от выбранного режима FTP (активный или пассивный), отправляет на сервер одну из следующих последовательностей команд:

   TYPE <I|A>       I=Binary, A=Ascii
   PORT <данные>    активный режим (по умолчанию)
   RETR <содержимое параметра remoteFile>
или
   TYPE <I|A>       I=Binary, A=Ascii
   PASV             пассивный режим
   RETR <содержимое параметра remoteFile>

Если выполнение прошло успешно, то локальный файл переписывается данными из файла, полученного с сервера.

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

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

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя локального файла, имя или адрес хоста и имя файла на сервере. А затем копирует файл с сервера на рабочую станцию в файл с указанным именем.

   /* rxFtpGet.cmd - function example */
   parse arg toFile pHost '/' fromFile

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

   if pHost = '' | toFile = '/' then do
      say ''
      say 'Usage: rxFtpGet 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 = FtpGet( toFile, fromFile, 'Binary' )
   if rc = -1 then do
      say ''
      say 'FtpGet()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File '||fromFile||' received to '||toFile||' OK'
   end

   rc = FtpLogoff()
   /* end of file rxFtpGet.cmd */

Примеры результатов выполнения:

   X:>rxFtpGet xxx.txt 127.0.0.1/Data/Ftp/Test.txt

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

   X:>rxFtpGet C:\robots.txt ftp.software.ibm.com/robots.txt

   File /robots.txt received to C:\robots.txt OK

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

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

5.7. FtpLoadFuncs().

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

Синтаксис:

rc = FtpLoadFuncs( [pMute] )

Параметры:

pMute

(необязательный) любое значение.

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

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

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

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

Описание:

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

Пример:

Чтобы получить возможность использовать в программе функции REXX FTP API, необходимо включить в неё следующие инструкции:

   rc = RxFuncAdd('FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs')
   rc = FtpLoadFuncs()

Пример вывода на консоль информации о библиотеке REXX FTP API:

   RxFtp 2.1 - REXX function package for tcp/ip ftp
   (c) Copyright International Business Machines Corporation 1993, 1999.
   All Rights Reserved.

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

FtpDropFuncs()

5.8. FtpLogoff().

Завершает сессию FTP.

Синтаксис:

rc = FtpLogoff( )

Параметры:

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

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

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

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

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

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

Описание:

Если сессия FTP открыта, то сначала функция FtpLogoff() проверяет наличие соединения с сервером FTP.

И, если соединение с сервером FTP существует, то отправляет на сервер следующую последовательность команд:

   QUIT

и закрывает соединение с сервером FTP.

Затем сбрасывает установки, сделанные функциями FtpSetBinary(), FtpSetActiveMode() и FtpSetUser(). Сессия FTP закрыта.

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя или адрес хоста. Затем отправляет на сервер неполную команду, после чего сервер по тайм-ауту разрывает соединение. Соединение автоматически восстанавливается во время следующей попытки доступа к серверу. Затем сессия закрывается и работа становится невозможна.

   /* rxFtpLogoff.cmd - function example */
   parse arg pHost

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpLogoff host'
      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 = FtpQuote( 'TYPE', xAnswer )
   if rc = -1 then do
      say ''
      say 'FtpQuote()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say xAnswer
   end

   rc = FtpSys( pSys )
   if rc = -1 then do
      say ''
      say 'FtpSys()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say pSys
   end

   rc = FtpLogoff()

   if rc = -1 then do
      say ''
      say 'FtpLogoff()   FTPERRNO='||FTPERRNO
   end

   rc = FtpSys( pSys )
   if rc = -1 then do
      say ''
      say 'FtpSys()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say pSys
   end
   /* end of file rxFtpLogoff.cmd */

Примеры результатов выполнения:

   X:>rxFtpLogoff 127.0.0.1

   FtpQuote()   FTPERRNO=FTPCOMMAND

   OS/2 operating system

   FtpSys()   FTPERRNO=FTPCOMMAND

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

FtpAppend(), FtpChDir(), FtpDelete(), FtpDir(), FtpGet(), FtpLs(), FtpMkDir(), FtpPut(), FtpPutUnique(), FtpPwd(), FtpQuote(), FtpRename(), FtpRmDir(), FtpSetActiveMode(), FtpSetBinary(), FtpSetUser(), FtpSite(), FtpSys()

5.9. FtpLs().

Получает список содержимого каталога сервера FTP в сокращённом виде; в списке будут присутствуют только имена файлов и каталогов.

Синтаксис:

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

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

Затем, в зависимости от выбранного режима FTP (активный или пассивный), отправляет на сервер одну из следующих последовательностей команд:

   PORT <данные>    активный режим (по умолчанию)
   NLST <содержимое параметра pPattern>
или
   PASV             пассивный режим
   NLST <содержимое параметра pPattern>

Если выполнение прошло успешно, то результатами заполняется набор переменных, имя-основа которых задаётся параметром pStem. Количество записей заносится в переменную из этого набора с индексом 0.

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

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

Примечание:

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

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

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

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

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

Пример:

Ниже приведён текст программы, которая в качестве параметров получает имя или адрес хоста и имя каталога на сервере. А затем отображает содержимое указанного каталога.

   /* rxFtpLs.cmd - function example */
   parse arg pHost '/' pDir

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

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpLs 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 = FtpLs( '.', 'xFile.' )
   if rc = -1 then do
      say ''
      say 'FtpLs()   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 rxFtpLs.cmd */

Примеры результатов выполнения:

   X:>rxFtpLs 127.0.0.1

   error.log
   Misc Tools
   Public
   ReadMe.txt
   Test.txt

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

   00_Catalog
   00_index
   00_index.tab
   User_Documentation
   User_Documentation.990517.rsr
   dir_structure
   dir_structure.990517.rsr
   index.html
   message.990517.rsr

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

FtpLogoff(), FtpDir(), FtpSetActiveMode(), FtpSetUser()