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

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

5.15. FtpPwd().

Получает имя текущего каталога на сервере FTP.
Синтаксис: 
rc = FtpPwd( pCurDir )
Параметры:

pCurDir
переменная, в которую будет помещена строка, с ответом сервера, содержащим имя текущего каталога.

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

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

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

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

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

Описание:

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

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

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

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

Имя текущего каталога в ответе сервера всегда заключено в двойные кавычки.

Пример:

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

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

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

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

   X:>rxFtpPwd ftp.software.ibm.com

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

FtpChDir(), FtpLogoff(), FtpMkDir(), FtpRmDir(), FtpSetUser()

5.16. FtpQuote().

Передаёт команду серверу FTP.
Синтаксис: 
rc = FtpQuote( pCmd [, pAnswer] )
Параметры:

pCmd
строка, содержащая команду FTP.
pAnswer
(необязательный) переменная, в которую будет помещена строка, с ответом сервера.

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

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

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

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

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

Описание:

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

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

Затем отправляет на сервер следующую последовательность команд: 
   <содержимое параметра pCmd>
 Если выполнение прошло успешно, то помещает ответ сервера в переменную, указанную в качестве параметра pAnswer, если она не инициализирована.

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

Сервер должен поддерживать обработку переданной команды FTP.

Примечание:

Про наличие второго параметра в оригинальной документации не упоминается.

Длина строки, возвращаемой во втором параметре, не превышает 197 байт.

Если сервер формирует многострочный ответ, то он искажается, поскольку:

  • все строки ответа могут не поместиться в 197 байт
  • в каждой строке откидываются несколько символов от начала строки и опускаются символы <CR><LF> в конце строки

Пример:

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

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

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

   OS/2 operating system

   X:>rxFtpQuote ftp.software.ibm.com syst

   UNIX Type: L8

   X:>rxFtpQuote 127.0.0.1 type i

   Type set to I (Image/Binary).

   X:>rxFtpQuote ftp.software.ibm.com type i

   TYPE is now 8-bit binary
Связанные функции:

FtpLogoff(), FtpSite(), FtpSys(), FtpSetUser()

5.17. FtpRename().

Переименовывает файл на сервере FTP.
Синтаксис: 
rc = FtpRename( remoteOldFile, remoteNewFile )
Параметры:

remoteOldFile
имя существующего файла на сервере FTP
remoteOldFile
новое имя, которое будет присвоено этому файлу

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

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

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

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

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

Описание:

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

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

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

Пример:

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

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

   if pHost = '' | oldFile = '/' | newFile = '' then do
      say ''
      say 'Usage: rxFtpRename host/oldfile newfile'
      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 = FtpRename( oldFile, newFile )
   if rc = -1 then do
      say ''
      say 'FtpRename()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'File '||oldFile||' renamed to '||newFile||' OK'
   end

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

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

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

5.18. FtpRmDir().

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

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

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

Пример:

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

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

   if pHost = '' | pDir = '/' then do
      say ''
      say 'Usage: rxFtpRmDir 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 = FtpRmDir( pDir )
   if rc = -1 then do
      say ''
      say 'FtpRmDir()   FTPERRNO='||FTPERRNO
   end
   else do
      say ''
      say 'Directory '||pDir||' removed OK'
   end

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

   Directory /Data/Ftp/Other removed OK
Связанные функции:

FtpChDir(), FtpLogoff(), FtpMkDir(), FtpPwd(), FtpSetUser()

5.19. FtpSetActiveMode().

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

pMode
режим FTP:
'0' пассивный
'1' активный

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

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

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

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

Описание:

В отличии от функций FtpSetBinary() и FtpSetUser(), которые просто выполняют установку параметров сессии FTP, функция FtpSetActiveMode() сначала проверяет наличие соединения с сервером и устанавливает его, если оно ещё не было установлено, или восстанавливает его, если оно было разорвано.

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

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

В дальнейшем, функции:

FtpAppend()
FtpDir()
FtpGet()		 FtpLs()
FtpPut()
FtpPutUnique()

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

Примечание:

В оргинальной документации утверждается, что режимом FTP по умолчанию является пассивный режим. На самом деле, по крайней мере для REXX FTP API версии 2.1, по умолчанию используется активный режим FTP.

Пример:

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

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

   if pHost = '' | toFile = '/' then do
      say ''
      say 'Usage: rxFtpSetActiveMode 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 = FtpSetActiveMode( '0' );
   if rc = 1 then do
      say ''
      say 'FTP mode is passive'
   end
   else do
      say ''
      say 'FtpSetActiveMode("0") error   RC='||rc
      signal halt
   end

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

   rc = FtpSetActiveMode( '1' );
   if rc = 1 then do
      say ''
      say 'FTP mode is active'
   end
   else do
      say ''
      say 'FtpSetActiveMode("1") 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 rxFtpSetActiveMode.cmd */
 Примеры результатов выполнения: 
   X:>rxFtpSetActiveMode xxx.txt 127.0.0.1/Data/Ftp/Test.txt

   FTP mode is passive

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

   FTP mode is active

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

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



Главное меню