Command: httpget

Syntax

httpget <url> {,<file> | <dir> }

Description

Downloads (fetches) a file across the internet. This command is also available under the name download. It effectively performs an HTTP GET 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.
<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.
```
httpget -k,-id='mydownload'
```
-nam=<strings>
One or more names, combined with the -val switch, providing name/value pairs to be appended to the URL as "&name=value" sequences. Values get automatically url-encoded (to "escape" characters not permitted in URLs), so prior encoding is not necessary.
-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.
-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 added to the URL.
-z
Decompress the file if it is in gzip format, or expand it if it is a .zip archive file.
For gzips, if <file> is omitted, then the name of the local file is provided within the gzipped data.
For .zip archives, <dir> provides an existing directory into which the archive is expanded, or if <dir> is omitted the archive will be expanded into the current directory.
If the file is in gzip or zip format but the -z switch is not present, no decompresion or expansion is done.

Examples

Download a file index.htm into the local directory. Time out after 10 seconds wait.

httpget 'http://remotenode/index.htm',-tim=10

Download into the local directory and record the http header.

string header[] ;# Not strictly necessary
httpget 'http://remotenode/index.htm', -os=header

Download into a specified directory.

mkdir /tmp/cache
httpget 'http://remotenode/index.htm', /tmp/cache

Download into a specified file, i.e. download and rename.

httpget 'http://remotenode/yourfile.dat', /tmp/cache/myfile.dat

Download and expand a zip archive into a specified directory.

mkdir /tmp/cache/images
httpget 'http://remotenode/images.zip', c:/tmp/cache/images

Download a whole set of image files, and print confirmation.

cd c:/HolidaySnaps
for i=1,50 {
    httpget //snaps.com/holiday/^(i).jpg
    tell '^(i).jpg downloaded'
}

Download an image file asynchronously, and display it when it arrives.

atable myatab
procedure ~myatab.myproc = {
   args id=string,status=numeric,url=string
   if (status)
      tell <'Download of ',url,'failed. Status',status>
   else
      wdisplay id
}
string dest='abc.jpg'
httpget 'http://www.bogus.com/imageserver/getimage?name=abc',dest,-cb=~myatab.myproc,-id=dest,-to=30
#  do other stuff while waiting ...