url(
url(
URL
,
OPTION
,
VALUE
)

The url( function synchronously loads a resource from the internet.

Parameters

This function has three parameters:

url – The address of the resource to be loaded, for example `"http://www.apple.com"`.

option – One or more option/value pairs can be included after the url parameter. These pairs specify things like what file or variable the resource should be placed into, what code (if any) to run when the resource load is complete, how progress should be reported, etc. See the description below for details on each option.

value – The value associated with an option/value pair. See below for details.

Description

This function loads a resource from the internet, for example a web page or an image. Unlike the urltask( function, this function is synchronous. This means that Panorama stops in its tracks until the communication is complete, so you should avoid this function if possible. The loadurl( and posturl( functions are also synchronous, but are much more limited than the url( function is, which can do anything loadurl( and posturl( do and much more.

For example, this procedure will display the home page of the ProVUE web site.

    displaydata url("http://www.provue.com")

Note that when we say “display”, we actually mean it displays the HTML source of the page, not what you would see in a web broswer. Of course you can use Panorama’s Web Browser object to actually display a web page in a form.

The url( function doesn’t always return text – it can also return binary data. This can be handy if you are downloading a non-text resource, for example an image. However, in some cases url( will return binary data when you expect text – it depends on the attributes returned by the web server. For example, loading a page from apple.com or google.com results in text, but loading a page from provue.com or nshipster.com returns binary data (at the time this was written). If you know that the data is text, you can just use it as text and it will be converted automatically, or you can use the binarytotext( function to do so explicitly.

#### Internet Errors

If an internet error occurs, the url( function will return an error. You should check for this with `if/error` or `try/catch` if you don’t want your program to abort. Note: Only actual internet errors (for example, the network is down) are handled by this technique. A missing web page (404 error) is not an internet error. You have to manually check the received content for that type of error.

#### Loading a resource with form data (HTTP POST)

So far, all of the examples shown have been for HTTP GET requests. You can also submit a POST request with one or more data items. To do this, create a dictionary with the items to be submitted, then pass this dictionary to the function using the post option.

    fileglobal urldata
    urldata = url("http://www.somesite.com/register",
        "post",initializedictionary("Name","John Smith","Email","jsmith@xyzmail.com"))

#### HTTP PUT, DELETE etc.

Most URLs are accessed via the GET or POST HTTP methods, but you can submit a request with any type of HTTP request.

    url("http://www.somesite.com/some/resource","METHOD","PUT", ... )

If you want to send additional items of data, use the “post” option as explained in the section above.

If you have no idea what PUT, DELETE etc. are you probably don’t need this option!

#### User Authentication

If a web page requires a user name and password, use the USER option. The option value must be in the format username:password.

    url("http://www.somesite/securepage","USER","johnsmith:secret")

If the user name or password is incorrect, the url( function will return an error.

#### HTTP HEAD request

If you specify a method of HEAD, the function will only fetch the header of the resource, not the actual resource itself. In that case the result will be a Panorama dictionary instead of text. The exact dictionary entries will vary depending on the server queried, but here is a typical example.

    dumpdictionary(url("http://www.provue.com","method","head")) ☞
    	Server=Apache/2.2.15 (Unix) mod_ssl/2.2.15 OpenSSL/0.9.8l PHP/5.3.3
    	Connection=Keep-Alive
    	Etag="4e6c5-b60f-4e4f0aea25200"
    	Keep-Alive=timeout=15, max=499
    	Content-Type=text/html
    	X-Frame-Options=SameOrigin
    	Expires=Thu, 09 Oct 2014 08:53:21 GMT
    	Cache-Control=max-age=60
    	Accept-Ranges=bytes
    	Last-Modified=Tue, 27 Aug 2013 16:51:20 GMT
    	Date=Thu, 09 Oct 2014 08:52:21 GMT
    	MS-Author-Via=DAV
    	Content-Length=46607

#### Timeout

The url( function will normally wait up to 60 seconds before giving up on a task. Use the timeout option to change this. This example changes the timeout to 10 seconds.

    url(...,"timeout",10, ...)

#### Cache Policy

Use the cachepolicy option if you want non-standard cache handling. If you want to ignore the cache and always go to the server, set the cache policy to 1.

    url(...,"cachepolicy",1, ...)

If you want to get hardcore and find out about other options, google `NSURLRequestCachePolicy`. For almost all operations, the default policy (0) is the way to go.

See Also

- encodehttppostdata( -- converts a dictionary into HTTP post data.
- info("httpheaders") -- returns a dictionary with information about a just completed HTTP download.
- info("urltaskinfo") -- returns information about a just completed HTTP download.
- ipaddress -- returns the current IP address of the computer, or "" if not connected.
- loadurl -- loads a resource from the internet.
- loadurl( -- loads a resource from the internet.
- posturl -- loads a resource from the internet, with form data.
- posturl( -- loads a resource from the internet, with form data.
- urltask( -- asynchronously loads a resource from the internet.
- urltaskcancel -- aborts a download initiated with the urltask( function.
- urltaskstatus -- enables connection error checking in urltask( completion code.
- zipinfo -- queries the web to obtain information about a zip code.
- zipinfoplus -- queries the web to obtain information about a zip code.

History

Version | Status | Notes
10.0 | New | New in this version.