Routines (alphabetical) > Object Classes > Network Object Classes > IDLnetURL::FtpCommand

# 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.

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 Exelis VIS 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