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

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

5.20. FtpSetBinary().

Задаёт режим передачи файлов, который будет использоваться функциями REXX FTP API по умолчанию.
Синтаксис: 
rc = FtpSetBinary( pMode )
Параметры:

pMode
режим передачи файлов:
'Ascii' текстовый
'Binary' двоичный

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

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

Значение Описание
1 нормальное завершение, ошибок нет
0 ошибка, требуемое действие не выполнено

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

Описание:

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

В дальнейшем, если при вызове функций:

FtpAppend()
FtpGet()		 FtpPut()
FtpPutUnique()

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

Пример:

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

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

   if pHost = '' | toFile = '/' then do
      say ''
      say 'Usage: rxFtpSetBinary 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 = FtpSetBinary( 'Binary' );
   if rc = 1 then do
      say ''
      say 'Transfer mode is "Binary"'
   end
   else do
      say ''
      say 'FtpSetBinary("Binary") error   RC='||rc
      signal halt
   end

   rc = FtpGet( toFile||'.b', fromFile )
   if rc = -1 then do
      say ''
      say 'FtpGet()   FTPERRNO='||FTPERRNO
      signal halt
   end
   else do
      say ''
      say 'File '||fromFile||' received to '||toFile||'.b OK'
   end

   rc = FtpSetBinary( 'Ascii' );
   if rc = 1 then do
      say ''
      say 'Transfer mode is "Ascii"'
   end
   else do
      say ''
      say 'FtpSetBinary("Ascii") error   RC='||rc
      signal halt
   end

   rc = FtpGet( toFile||'.a', fromFile )
   if rc = -1 then do
      say ''
      say 'FtpGet()   FTPERRNO='||FTPERRNO
      signal halt
   end
   else do
      say ''
      say 'File '||fromFile||' received to '||toFile||'.a OK'
   end

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

   Transfer mode is "Binary"

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

   Transfer mode is "Ascii"

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

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

5.21. FtpSetUser().

Открывает сессию FTP.
Синтаксис: 
rc = FtpSetUser( pHost, pUser, pPass [, pAcct] )
Параметры:

pHost
адрес или имя хоста (сервера FTP)
pUser
имя пользователя сервера FTP
pPass
пароль пользователя сервера FTP
pAcct
(необязательный) аккаунт пользователя сервера FTP; информация об аккаунте пользователя, зависящая от конкретного хоста

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

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

Значение Описание
1 нормальное завершение, ошибок нет
0 ошибка, требуемое действие не выполнено

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

Описание:

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

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

Фактически соединение с сервером FTP будет выполнено при первом же вызове любой функции из перечисленных ниже:

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

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

Затем будет установлено соединение с сервером FTP и выполнена следующая последовательность команд: 
   USER <содержимое параметра pUser>
   PASS <содержимое параметра pPass>
   ACCT <содержимое параметра pAcct>
   PWD
 и только потом будут выполнены действия вызванной функции.

Все установки, выполненнные функцией FtpSetUser(), сбрасывает функция FtpLogoff(), закрывая сессию 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(), FtpLogoff(), FtpLs(), FtpMkDir(), FtpPut(), FtpPutUnique(), FtpPwd(), FtpQuote(), FtpRename(), FtpRmDir(), FtpSetActiveMode(), FtpSetBinary(), FtpSite(), FtpSys()

5.22. FtpSite().

Передаёт информационную строку серверу FTP.
Синтаксис: 
rc = FtpSite( pInfo )
Параметры:

pInfo
информационная строка для сервера FTP.

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

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

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

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

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

Описание:

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

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

Затем отправляет на сервер следующую последовательность команд: 
   SITE <содержимое параметра pInfo>
 Сервер должен поддерживать обработку переданной информационной строки.

Пример:

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

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpSite host info'
      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 = FtpSite( pInfo )
   if rc = -1 then do
      say ''
      say 'FtpSite()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'Information transfered OK'
   end

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

   Information transfered OK

   X:>rxFtpSite ftp.software.ibm.com xxx

   FtpSite()   FTPERRNO=FTPCOMMAND
Связанные функции:

FtpLogoff(), FtpQuote(), FtpSys(), FtpSetUser()

5.23. FtpSys().

Получает информацию об операционной системе сервера FTP.
Синтаксис: 
rc = FtpSys( pAnswer )
Параметры:

pAnswer
переменная, в которую будет помещена строка с информацией об операционной системе сервера.

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

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

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

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

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

Описание:

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

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

Затем отправляет на сервер следующую последовательность команд: 
   SYST
 Если выполнение прошло успешно, то помещает информацию об операционной системе сервера в переменную, указанную в качестве параметра pAnswer, если она не инициализирована.

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

Пример:

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

   if pHost = '' then do
      say ''
      say 'Usage: rxFtpSys 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 = FtpSys( xSys )
   if rc = -1 then do
      say ''
      say 'FtpSys()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say rc
   end

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

   OS/2 operating system

   X:>rxFtpSys ftp.software.ibm.com

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

FtpLogoff(), FtpQuote(), FtpSite(), FtpSetUser()

5.24. FtpVersion().

Получает версию билиотеки REXX FTP API.
Синтаксис: 
rc = FtpVersion( pAnswer )
Параметры:

pAnswer
переменная, в которую будет помещён номер версии библиотеки REXX FTP API.


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

Функция FtpVersion() всегда возвращает пустую строку ("").

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

Описание:

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

Всегда возвращает пустую строку в качестве кода возврата и помещает номер версии REXX FTP API в переменную, указанную в качестве параметра pAnswer, если она не инициализирована.

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

Пример:

Ниже приведён текст программы, которая демонстрирует номер версии библиотеки REXX FTP API. 
   /* rxFtpVersion.cmd - function example */
   if RxFuncQuery( 'FtpLoadFuncs' ) then do
      rc = RxFuncAdd( 'FtpLoadFuncs', 'rxFtp', 'FtpLoadFuncs' )
      rc = FtpLoadFuncs( )
   end

   rc = FtpVersion( pVer )
   say ''
   say 'REXX FTP API Version '||pVer
   /* end of file rxFtpVersion.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpVersion

   REXX FTP API Version 2.1
Связанные функции:

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