The IDLnetURL::Put method sends a file or a buffer of data to a remote HTTP or FTP server.

This method returns when one of the following events occurs:

  • The method completes successfully.
  • The method encounters an HTTP or FTP error.
  • The return status of the callback function indicates the caller wants to cancel the Put.

If the URL keyword is not set, the URL_PATH property must be set to the destination (filename) on the remote HTTP or FTP server.

When sending data to an HTTP server, IDL uses the “Put” transmission method by default. To use the “Post” transmission method, set the POST keyword.

When sending a file to a remote FTP server, the Put method automatically changes directories to the path specified before sending the desired file. If the directories do not exist before sending the desired file, the Put method attempts to create them using the path specified.

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

See Using Callbacks with the IDLnetURL Object for details.

Errors

This method generates an error if the transmission fails, or if the remote server is unable to complete the Put or Post request. When an error is generated, the remote HTTP server typically sends an HTML response file indicating the reason for the failure. The FILENAME keyword can be used to set the name for this response file. The RESPONSE_FILENAME property contains the complete path to the error file.

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.

Use a CATCH statement to trap errors and print the error message and response code. A HTTP server 401 response code, or a FTP server 530 or 67 response code means that a login is required, or the current username and password are incorrect.

If a FTP connection fails, you may need to switch the connection mode from Active to Passive using the FTP_CONNECTION_MODE property.

A HTTP Put or HTTP Post will fail if the remote HTTP server is out of space, or if the path (destination of the file or data) does not exist or can not be created.

Remote servers typically must be configured to support HTTP Put or Post operations. If the remote server does not support these operations, the HTTP Put or Post will fail. Typical error responses to this situation are “400 Bad Request” and “405 Method Not Allowed”.

Syntax

Result = Obj->[IDLnetURL::] Put ( data, BUFFER=value, FILENAME=string, /FTP_EXPLICIT_SSL, /POST, [, /STRING_ARRAY] URL=string)

Return Value

If the server sent a response to the Put or Post request, the return value contains the complete path to the response file (or a string array if the STRING_ARRAY keyword is set). If the server did not send a response to the Put or Post request, the return value is an empty string.

Arguments

DATA

When the BUFFER keyword is not set, the data argument is a string containing the name of a file to be transferred. In this case:

  • If Data specifies a full path, the file is uploaded from the specified path.
  • If Data specifies a relative path, the path is relative to IDL’s current working directory.

When the BUFFER keyword is set, Data is an IDL variable containing the data to be transferred. The data buffer can be a scalar or an array of the following types:

  • BYTE
  • INT
  • UINT
  • LONG
  • ULONG
  • LONG64
  • ULONG64
  • FLOAT
  • DOUBLE
  • STRING

Note: If the buffer contains string values, a linefeed character (10B) is appended to the end of each string before it is passed to the remote server.

Keywords

BUFFER

Set this keyword to cause the Data argument to be interpreted as the name of an IDL variable to be sent to the remote server.

FILENAME

Set this keyword to a string giving the name of the response file if an error occurs. If this keyword is not set then IDLnetURL will choose a default name. After the ::Put method returns, the file name can be retrieved using the RESPONSE_FILENAME property.

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” (which implicitly activates SSL).

See  Secure FTP for additional notes on SSL connections.

POST

Set this keyword to use the HTTP POST command rather than the HTTP PUT command. This keyword is ignored if the URL Scheme is 'ftp' or ‘ftps’.

STRING_ARRAY

Set this keyword to return the response as a string array instead of writing to a file. If this keyword is set, the FILENAME keyword is ignored.

URL

Set this keyword equal to a string that specifies the complete URL of the location to which the data will be transferred. 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.

Examples

Conceptual Examples

result = Obj->Put(file)

The input parameter is a full or relative path to the local file to transfer to the remote server. The URL_* properties are used. The URL_HOST and URL_PATH properties must be set prior to making this type of Put call. The URL_PATH property determines the destination (filename) on the remote server. The URL_SCHEME property determines if the file is sent using HTTP or FTP. If the remote server sends a response file, it is written to the location specified by the RESPONSE_FILENAME property.

result = Obj->Put(file, URL='scheme://host/path')

The input parameter is a full or relative path to the local file to transfer to the remote server. The URL_* properties are not used. The destination and filename used on the remote server is determined by the path portion of the URL keyword.

result = Obj->Put(data, /BUFFER, /POST)

The input parameter is an IDL variable containing the data to post to the remote server. The URL_* properties are used. The URL_HOST and URL_PATH properties must be set prior to making this type of Post call. The URL_PATH property determines the destination (typically a CGI script that processes the posted data) on the remote server. In this case, the URL_SCHEME property must be HTTP.

Extended Example

;-----------------------------------------------------------------
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_Put
 
   ; If the IDLnetURL 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 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
 
 
   ; Sreate 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 info on the transacton
   oUrl->SetProperty, VERBOSE = 0
 
   ; This is an ftp transaction
   oUrl->SetProperty, URL_SCHEME = 'ftp'
 
   ; EDIT THIS LINE: put in a valid ftp server name
   oUrl->SetProperty, URL_HOST = 'ftp_server_name'
 
   ; Specify the destination path/filename
   ; EDIT THIS LINE: put in the valid path for your server
   oUrl->SetProperty, URL_PATH = 'valid_path/Night.jpg'
 
   ; Specify the appropriate username and password
   oUrl->SetProperty, URL_USERNAME = 'Anonymous'
   oUrl->SetProperty, URL_PASSWORD = ''
 
   ; Build a path to an IDL example jpeg file
   fn = FILEPATH('Night.jpg',SUBDIR=['examples', 'data'])
 
   ; Use an ftp put request to send the file to the $
   ; remote ftp server
   result = oUrl->Put(fn)
 
   ; we are done so we release the url object
   OBJ_DESTROY, oUrl
END

Version History

6.4

Introduced

8.4

Added FILENAME keyword

8.6.1

Added STRING_ARRAY keyword

See Also

IDLnetURL::Delete, IDLnetURL::Get