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.
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.
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"))
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!
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.
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
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, ...)
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
History
| Version | Status | Notes |
| 10.0 | New | New in this version. |