Command: httppost

Syntax

httppost <url>, <datafile> {,<file> | <dir> }

Description

Sends data to a web server across the interent and downloads (fetches) the reply into a file. This command effectively performs an HTTP POST operation.

A successful URL retrieval will set the system numeric found to 1. An error will set it to 0.

Note: If the web-server from which the download is being made has authorization checks involving the completion of a web-page, e.g. a login page, then this will not be processed like a browser. Such cases will have the effect of merely downloading the login page, instead of the requested file.

Parameters

<url>
The URL (Universal Resource Locator) of the file to be fetched. This can be a string expression, a string constant within quotes or straight text. If the text contains characters not usually permitted within file names, the text should be quoted. The prefix 'http:' may be omitted.
<datafile>
The name of a local file (or blob) whose data is to be sent.
<file>
The name of the local file to be created or overwritten. If the file name contains a directory path, sub-directories will be created automatically where necessary.
<dir>
A directory into which the file will be copied. The local file name will be the trailing file name part of <url>. This directory must already exist. If neither <file> nor <dir> are specified a local file is created in the current directory. The local file name will be the trailing file name part of <url>.

Switches

-cb=<proc>
By default this command will wait for the download operation to complete before continuing. An alternative is to execute the download in asynchronous mode, whereby the command will complete after initiating the download but without waiting for it to finish, and a callback procedure will be executed later when the actual download does finish. This switch requests asynchronous mode and provides the callback. The callback takes the following form:
```
procedure ~myapp.mycallback {
   args id=string,status=numeric,url=string
#  process the result ...
}
```
Where id is a user value supplied by the -id switch to identify the operation, status is a download completion enumeration, and url is the url supplied to the original httpget command.

Possible status values are:
    0 - Successful download
    1 - Failed download due to a download http error
    2 - Failed download due to timing out before finishing
    3 - Failed download due to an abort before finishing (see the -k switch).

The callback procedure <proc> should not be a local procedure in case it goes out of scope and gets removed during the wait.
-id=<string>
A user value to identify the download operation when used asynchronously (see the -cb switch).
-k=<string>
A way of aborting an asynchronous download. Combined with the -id switch this can be used to force the download to finish prematurely before it has completed.
```
httppost -k,-id='mydownload'
```
-nam=<strings>
One or more names, combined with the -val switch, providing name/value pairs making up the request. This forces the request to be of type application/x-www-form-urlencoded, and the post data becomes comprised entirely of the name/value pairs (in the appropriate format). Any data supplied in <datafile> or the -ty switch is ignored.
-os=<ident>
Record the returned http packet header contents in a string identifier. If the identifier does not exist, a new string array is created using current scope rules. Each line of the header is recorded in a separate array element.
This switch has no effect on the outgoing request, but merely gets information contained in the response.
-tim=<num>
Set a timeout (in seconds) on the operation. The default is 30 seconds.
-ty=<string>
Text to add to the outgoing http header to specify the type of data in <datafile>. The header prefix "Contents-Type:" should not be present because it will be added automatically.
-val=<strings>
When combined with the -nam switch, this defines one or more values which, in combination with the -nam strings, provide name/value pairs to be sent as form-data.
-z
Decompress the file if it is in gzip format. If <file> is omitted, then the name of the local file is provided by the gzipped data. If the file is in gzip format but the -z switch is not present, no uncompresion is done.

Examples

Upload a data file myfile.xml to a web servlet. The returned data will be stored in a local file result.xml. Time out after 10 seconds wait.

httppost //remotenode/MyServlet, myfile.xml, result.xml, -tim=10, -ty='text/xml'

Do the same (without the timeout) and record the returned http header information.

string header[] ;# Not strictly necessary
httppost //remotenode/MyServlet, myfile.xml, result.xml, -ty='text/xml', -os=header

Do the same, but asynchronously, processing for the result later.

atable myatab
procedure ~myatab.myproc = {
   args id=string,status=numeric,url=string
   if (status)
      tell <'Download of ',url,'failed. Status',status>
   else {
   # Do something with the result
   }
}
httppost //remotenode/MyServlet,myfile.xml,result.xml,-ty='text/xml',-os=~myatab.header,\ 
   -cb=~myatab.myproc,-id='result.xml',-to=30
#  do other stuff while waiting ...