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.

Note: 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 NV5 Geospatial 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).

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 NASA FTP server
   ourl->SetProperty, URL_HOST = 'nssdcftp.gsfc.nasa.gov/miscellaneous/orbits'
 
   ; 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']
 
    cmds = ['cwd ..']
 
   ; Specify the appropriate username and password. If the
   ; username is 'Anonymous', use an empty 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