IDLnetURL::FtpCommand

The IDLnetURL::FtpCommand function method can be used to execute FTP commands, delete files, make directories, delete directories, and change directories on the remote FTP server.

This method throws an error if the call fails. Use a catch statement to trap errors and print the error messages and response codes.

Note
When the FTP server issues response code 530 or 67, a login is required or the current username and password are incorrect.

This method sets the RESPONSE_CODE property, which contains the last FTP status code received. The RESPONSE_HEADER and RESPONSE_CODE properties are useful for troubleshooting problems. Receiving callbacks and printing the status strings with the VERBOSE property set to 1 is another valuable troubleshooting technique. Refer to Using Callbacks with the IDLnetURL Object for details.

If a FTP connection fails, it may be necessary to switch the connection mode from active to passive using the FTP_CONNECTION_MODE property.

Syntax

Result = Obj->[IDLnetURL::]FtpCommand(command [, /FTP_EXPLICIT_SSL] [, URL=string])

Return Value

The return value is the response header, which is a string. Examine the response header to determine if the command succeeded or failed.

Arguments

Command

A string or string array containing FTP commands to execute.

The following table lists the FTP commands that IDL allows:


CWD	Change a directory
DELE	Delete a file
MKD	Make a directory
RMD	Remove a directory
RNFR	Rename from
RNTO	Rename to Note - To rename a file, you must issue both the RNFR and RNTO commands in succession (see the following examples)

The following are examples of using standard commands:

"CWD data" 
"CWD .." 
 
"DELE path/filename" 
"DELE /path/filename" 
 
"MKD /path" 
"MKD path" 
 
"RMD /path" 
"RMD path" 
 
"RNFR /path/existingfilename" 
"RNTO /path/newfilename" 
...or... 
"RNFR path/existingfilename" 
"RNTO path/newfilename"

Keywords

FTP_EXPLICIT_SSL

Set this keyword to explicitly use SSL to transfer the commands and data to or from the remote FTP server. It is not necessary to set this keyword when the scheme is "ftps", as this implicitly activates SSL. See Secure FTP for additional notes on SSL connections.

URL

Set this keyword equal to the complete URL string of the location for which the command is to be executed. If this keyword is set, the URL_* properties are ignored.

Warning
If you include a username and password as plain text in a URL, both are potentially visible to others. To avoid this security risk, set the URL_* properties, including the URL_USERNAME and URL_PASSWORD properties, specifically.

Examples

The following example uses the IDLnetURL::FtpCommand function method to send a cwd FTP command to the ITT Visual Information Solutions FTP server. This command changes the working directory to /doc/examples (this is the only command that can be issued with this method to a read-only server).

Example Code
The code sample url_docs_ftp_cmd.pro is also located in the examples/doc/objects subdirectory of the IDL distribution. View the file in an IDL editor window by entering .EDIT url_docs_ftp_cmd.pro at the IDL Command Line.

;----------------------------------------------------------------- 
FUNCTION URL_CALLBACK, status, progress, data 
 
   ; print the info msgs from the url object 
   PRINT, status 
 
   ; return 1 to continue, return 0 to cancel 
   RETURN, 1 
END 
 
;----------------------------------------------------------------- 
PRO url_docs_ftp_cmd 
 
   ; Catch any errors generated by the IDLnetURL object 
   CATCH, errorStatus 
   IF (errorStatus NE 0) THEN BEGIN 
      CATCH, /CANCEL 
 
      ; Display the error msg in a dialog and at the IDL 
      ; command line. 
      r = DIALOG_MESSAGE(!ERROR_STATE.msg, TITLE='URL Error', $ 
         /ERROR) 
      PRINT, !ERROR_STATE.msg 
 
      ; Get the properties that tell us more about 
      ; the error and display at the IDL command line. 
      ourl->GetProperty, RESPONSE_CODE=rspCode, $ 
         RESPONSE_HEADER=rspHdr, RESPONSE_FILENAME=rspFn 
      PRINT, 'rspCode = ', rspCode 
      PRINT, 'rspHdr= ', rspHdr 
      PRINT, 'rspFn= ', rspFn 
 
      ; Destroy the url object and return. 
      OBJ_DESTROY, ourl 
      RETURN 
   ENDIF 
 
 
   ; Create a new url object 
   ourl = OBJ_NEW('IDLnetUrl') 
 
   ; Specify the callback function 
   ourl->SetProperty, CALLBACK_FUNCTION ='URL_CALLBACK' 
 
   ; Set verbose to 1 to see more details 
   ourl->SetProperty, VERBOSE = 1 
 
   ; Specify that we will do an ftp transaction 
   ourl->SetProperty, URL_SCHEME = 'ftp' 
 
   ; The ITT Visual Information Solutions FTP server 
   ourl->SetProperty, URL_HOST = 'data.ittvis.com' 
 
   ; Build an array of commands. The following sample command 
   ; array changes to the /doc/examples dir (which is all 
   ; that can be done with this method on a read-only server. 
   ; The following command will always work: 
   ; cmds = 'cwd /' 
 
   cmds = ['cwd doc/examples'] 
 
   ; Specify the appropriate username and password. If the 
   ; username is 'Anonymous', use a null string for the password. 
   ourl->SetProperty, URL_USERNAME = 'Anonymous' 
   ourl->SetProperty, URL_PASSWORD = '' 
 
   ; Send the command array to the FTP server, saving the 
   ; responses in an IDL variable. 
   respHdr = ourl->FtpCommand(cmds) 
 
   ; Display the responses. 
   PRINT, 'response header for the ftp commands' 
   PRINT, respHdr 
 
   ; Destroy the url object 
   OBJ_DESTROY, ourl 
 
END

Version History


6.4	Introduced