The IDLnetURL::GetFtpDirList function method retrieves a list of files (returned as an array of strings) available from a remote FTP server on a particular path. The path must resolve to a directory and end with a slash. If the directory is empty, a single empty string is returned. When the SHORT keyword is set, the FTP server may or may not include directories and file statistics in the returned listing.

This method sets the RESPONSE_CODE and RESPONSE_HEADER properties, which contain response information sent by the remote server. The information stored in these properties can be useful when troubleshooting transmission problems. Receiving callbacks and printing the status strings with the VERBOSE and CALLBACK_FUNCTION properties set is another valuable troubleshooting technique.

This method generates an error if the transmission fails. Use a CATCH statement to trap errors and print the error messages and response codes.

Note: If the FTP server generates response code 530 or 67, a login is required or the current username and password are incorrect. A catch statement can be used to trap errors and print the error messages and response codes.

If a FTP connection fails, try switching the connection mode from Active to Passive using the FTP_CONNECTION_MODE property.

Syntax

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

Return Value

A string array containing the directory listing. If the directory is empty, the return value is a single empty string.

Arguments

None.

Keywords

FTP_EXPLICIT_SSL

Set this keyword to explicitly use SSL to transfer commands and data to or from the remote FTP server. It is not necessary to set this keyword when the scheme is “ftps”, (which implicitly activates SSL).

See Secure FTP for additional notes on SSL connections.

URL

Set this keyword equal to a string that specifies the complete URL of the location from which the directory listing is to be retrieved. If this keyword is set, the URL_* properties are ignored.

Note: When using a URL that contains a password, the password appears as clear text. To avoid this security problem when using a password, set the URL_* properties explicitly rather than using the URL keyword.

SHORT

Set this keyword to retrieve an abbreviated directory listing that does not include file statistics. FTP servers do not implement the short listing switch consistently; a server may or may not show directory entries and symbolic links correctly. If the SHORT keyword is not set, the default method behavior is to include file statistics in the directory listing, usually including file size and date.

Examples

The following example uses the IDLnetURL::GetFtpDirList function method to retrieve the listing from the /orbits directory of the NASA FTP server.

The code sample url_docs_ftp_dir.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 turtledoves.pro at the IDL Command Line.

;-----------------------------------------------------------------
FUNCTION Url_Docs_Ftp_Dir_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_dir
 
  ; if the url object throws an error it will be caught here
  CATCH, errorStatus
  IF (errorStatus NE 0) THEN BEGIN
  CATCH, /CANCEL
   
  ; display the error msg in a dialog
  r = DIALOG_MESSAGE(!ERROR_STATE.msg, TITLE='URL Error', $
  /ERROR)
  PRINT, !ERROR_STATE.msg
   
  ; get the properties that will tell us more detail about $
  ; the error.
  oUrl->GetProperty, RESPONSE_CODE=rspCode, $
  RESPONSE_HEADER=rspHdr, RESPONSE_FILENAME=rspFn
  PRINT, 'rspCode = ', rspCode
  PRINT, 'rspHdr= ', rspHdr
  PRINT, 'rspFn= ', rspFn
   
  ; since we are done we can destroy the url object
  OBJ_DESTROY, oUrl
  RETURN
  ENDIF
   
   
  ; create a new url object
  oUrl = OBJ_NEW('IDLnetUrl')
   
  ; the url object will make callbacks to this pro code function
  oUrl->SetProperty, CALLBACK_FUNCTION ='Url_Docs_Ftp_Dir_Callback'
   
  ; set VERBOSE to 1 to see more info on the transaction
  oUrl->SetProperty, VERBOSE = 1
   
  ; an ftp transaction
  oUrl->SetProperty, URL_SCHEME = 'ftp'
   
  ; The FTP server
  oUrl->SetProperty, URL_HOST = 'nssdcftp.gsfc.nasa.gov/miscellaneous'
   
  ; name of dir to get directory listing for on the $
  ; remote ftp server
  oUrl->SetProperty, URL_PATH = 'orbits'
   
  ; the appropriate username and password
  ;oUrl->SetProperty, URL_USERNAME = 'Anonymous'
  ;oUrl->SetProperty, URL_PASSWORD = ''
   
  ; Get the directory listing
  dirList = oUrl->GetFtpDirList()
   
  PRINT, ' directory listing: '
  PRINT, dirList, FORMAT='(A)'
   
  ; we are done so we release the url object
  OBJ_DESTROY, oUrl
END

Version History

6.4

Introduced