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

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

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()