Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  IDL Reference  >  I/O - Network  >  IDLnetURL::Get

IDLnetURL::Get

IDLnetURL::Get

The IDLnetURL::Get function method retrieves a resource from a remote HTTP or FTP server and writes it to disk, a memory buffer, or an array of strings. The returned data is written to disk in the location specified by the FILENAME keyword. If the file name is the same between method calls, the last file received is overwritten.

When retrieving a file from a remote FTP server, the Get method automatically changes directories to the path specified on the server before retrieving the file. The path is specified in the URL keyword or in the URL_PATH property.

This method supports SSL data transfers to and from remote HTTP or FTP servers. When the scheme is FTP and the path ends in a slash, a directory listing for the path-specified directory is returned. If the scheme is HTTP and the path is not set, this method attempts to get the index.htm file from the remote HTTP server.

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: When the HTTP server issues response code 401 or the FTP server generates response code 530, a login is required or the current username and password are incorrect.

Calls to the Get method are canceled when the return value of the callback function is zero.

See Using Callbacks with the IDLnetURL Object for details.

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

Syntax


Result = Obj->[IDLnetURL::]Get( [, /BUFFER] [, FILENAME=string] [, /FTP_EXPLICIT_SSL] [, /STRING_ARRAY] [, URL=string])

Return Value


This method returns one of the following:

  • A string containing the full path of the file retrieved from the remote HTTP or FTP server.
  • A byte vector, if the BUFFER keyword is set.
  • An array of strings, if the STRING_ARRAY keyword is set.
  • An empty string, if no data were returned by the method.

Arguments


None.

Keywords


FILENAME

Set this keyword equal to a string that holds the file name and path where the retrieved file is locally stored.

  • If FILENAME specifies a full path, the file is stored in the specified path.
  • If FILENAME specifies a relative path, the path is relative to IDL’s current working directory.
  • If FILENAME is not present or specifies an empty string, the file is stored in IDL’s current working directory under the name idl.dat.
  • If FILENAME is the same between calls to Get, the last file received is overwritten.

BUFFER

If this keyword is set, the return value is a buffer and the FILENAME keyword is ignored.

FTP_EXPLICIT_SSL

Set this keyword to explicitly use SSL to transfer commands and data to or from a 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.

STRING_ARRAY

Set this keyword to treat the return value as an array of strings. If this keyword is set, the FILENAME and BUFFER keywords are ignored.

URL

Set this keyword equal to a string that specifies the complete URL of the resource to be retrieved. The specified URL must contain a scheme and host, and may contain an optional path. If this keyword is set, the URL_* properties are ignored. If this keyword is not set, the URL_HOST property must be set prior to calling this method.

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.

Examples


The following example uses the IDLnetURL::Get function method to retrieve files from the a directory on an FTP server that you specify. A binary image file is saved to your local IDL main directory, and a text file is retrieved as an array of strings. Note that you will need to provide a valid FTP server name and path.

The code sample url_docs_ftp_get.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_get.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_get
 
   ; 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 and in the IDL output log
      r = DIALOG_MESSAGE(!ERROR_STATE.msg, TITLE='URL Error', $
         /ERROR)
      PRINT, !ERROR_STATE.msg
 
      ; Get the properties that will tell us more about the error.
      oUrl->GetProperty, RESPONSE_CODE=rspCode, $
         RESPONSE_HEADER=rspHdr, RESPONSE_FILENAME=rspFn
      PRINT, 'rspCode = ', rspCode
      PRINT, 'rspHdr= ', rspHdr
      PRINT, 'rspFn= ', rspFn
 
      ; Destroy the url object
      OBJ_DESTROY, oUrl
      RETURN
   ENDIF
 
   ; create a new IDLnetURL object 
   oUrl = OBJ_NEW('IDLnetUrl')
 
   ; Specify the callback function
   oUrl->SetProperty, CALLBACK_FUNCTION ='Url_Callback'
 
   ; Set verbose to 1 to see more info on the transacton
   oUrl->SetProperty, VERBOSE = 1
 
   ; Set the transfer protocol as ftp
   oUrl->SetProperty, url_scheme = 'ftp'
 
   ; EDIT THIS LINE: The FTP server
   oUrl->SetProperty, URL_HOST = 'ftp_server_name'
 
   ; EDIT THIS LINE: The FTP server path of the file to download
   oUrl->SetProperty, URL_PATH = 'valid_path/Day.jpg'
 
   ; Make a request to the FTP server.
   ; Retrieve a binary image file and write it 
   ; to the local disk's IDL main directory.
 
   fn = oUrl->Get(FILENAME = !DIR + '/Day.jpg' )  
 
   ; Print the path to the file retrieved from the remote server
   PRINT, 'filename returned = ', fn
 
   ; EDIT THIS LINE: The FTP server path of the next file to download
   oUrl->SetProperty, URL_PATH = 'valid_path/ascii.txt'
 
   ; Retrieve an ascii text file as an array of strings
   strings = oUrl->Get( /STRING_ARRAY )
 
   ; Print the returned array of strings
   PRINT, 'array of strings returned:'
   for i=0, n_elements(strings)-1 do print, strings[i]
 
   ; Destroy the url object
   OBJ_DESTROY, oUrl
 
END
 

Version History


6.4

Introduced



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us