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.

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

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

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)

"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

;-----------------------------------------------------------------  
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 more details 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'  
  
   ; EDIT THIS LINE: put in a valid ftp server name  
   ourl->SetProperty, URL_HOST = 'ftp.myserver.org'  
  
   ; Build an array of commands. The following sample command  
   ; array changes to a specific directory, deletes a file,  
   ; changes to the parent directory, and deletes the directory.  
   ; cmds = ['cwd some_directory/data', $  
   ;         'dele testfile.jpg' $  
   ;         'cwd ..' $  
   ;         'rmd data']  
   ; The following command will always work:  
   cmds = 'cwd /'  
  
   ; 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

IDL Online Help (March 06, 2007)