downloaddatafromserver
URL
,
TEMPID
,
EXTRADATA

The downloaddatafromserver statement asynchronously downloads pre-calculated binary data from a Panorama server.


Parameters

This statement has three parameters:

url – URL of data on server of (in compressed format).

tempid – ID of data on server of (so it can be deleted when finished).

extradata – extra data to be passed thru to post download routine (usually a dictionary).


Description

This statement asynchronously downloads pre-calculated binary data from the server. Before using this statement you must call a server statement that pre-calculates the binary data into a temporary file on the server and returns a URL and temporary ID for the data. You can then use the downloaddatafromserver statement to actually download the data. After the data is downloaded the temporary file on the server is automatically deleted for you. Panorama uses the downloaddatafromserver statement internally for tasks like data synchronization when a shared file is opened. (Note: Internally, the downloaddatabasefromserver statement uses the urltask( function to actually download the data from the server.)

Here is an example of how this statement is used. (The example is incomplete because there currently is no documented method for preparing the binary data on the server, this is done using undocumented methods.) This example illustrates the asynchronous nature of the downloaddatafromserver statement, in other words, the data is downloaded in the background. Because the program doesn’t wait for the downloaded data, the downloaded data is not available to the code immediately after the downloaddatafromserver statement. Usually your code will simply return after this statement. As shown in the example below, your procedure must contain a label named DownloadReady:. When the downloaded data is ready, Panorama will automaticaly restart your code at this point so that you can process the data.

// not shown ... calling the server to prepare binary data,
//     returning tempFileURL and tempFileID
downloadfromserver tempFileURL,tempFileID,""
// download is happening in background, so we just return for now
rtn
//
// download has finished, our data is ready
DownloadReady:
let downloadedData = parameter(1) // get the downloaded data
// now do something with the downloaded data

It’s important to keep in mind that the restarted code is not a continuation of the original code, so any local variables that were in use are now gone. This is the reason for the EXTRADATA dictionary parameter. If you need to be able to access any local variables you were using, put them into the EXTRADATA dictionary. The restarted code can access these values by extracting them from the dictionary, as shown in the example below.

let myLocalOne = ... some value ...
let myLocalTwo = ... some value ...
...
...
downloadfromserver tempFileURL,tempFileID,
    initializedictionary(
        "LOCAL1",myLocalOne,
        "LOCAL2",myLocalTwo)
rtn
//
// download has finished, our data is ready
DownloadReady:
let downloadedData = parameter(1) // get the downloaded data
let extraData = parameter(2) // get the extra data back
let myLocalOne = getdictionaryvalue(extraData,"LOCAL1")
let myLocalTwo = getdictionaryvalue(extraData,"LOCAL2")
// now do something with the downloaded data and local values

The EXTRADATA dictionary is not limited to local variables – you can put any calculated value into this dictionary. This example saves the time at the start of the download, then uses the saved time to calculate and display the elapsed time when the download is complete.

downloadfromserver tempFileURL,tempFileID,
    initializedictionary("STARTTIME",supernow())
rtn
//
// download has finished, our data is ready
DownloadReady:
let downloadedData = parameter(1) // get the downloaded data
let extraData = parameter(2) // get the extra data back
let startTime = getdictionaryvalue(extraData,"STARTTIME")
nsnotify "Download complete",
    "TEXT",pattern(supernow()-startTime,"# second~")
// now do something with the downloaded data

If you expect a large amount of data to be downloaded, you might like Panorama to display the progress of the download in the tool bar banner. You can do this by adding a BANNER item to the extra data dictionary, with a value that evaluates to true ("YES", "TRUE", "ON" or true()), as shown in this example.

downloadfromserver tempFileURL,tempFileID,
    initializedictionary("BANNER","YES")

Of course you can put as many items as you like into the extra data dictionary, including a banner specification, local variables, and arbitrary calculations.


See Also


History

VersionStatusNotes
10.2NewNew in this version.