The hostdownload statement downloads a shared file to this computer, prompting the user for the location.
Parameters
This statement has three parameters:database – is the url of the host to be added to the list of hosts available to this computer.
host – name of the host to download from. This parameter is optional, if omitted, the download will be the same as the current shared database, or an error if the current database is not shared.
options – download options, in the form of option=value.
Description
This statement downloads a shared file to this computer, prompting the user for the location. This example will prompt the user to specify where to place the downloaded file, then download it:
hostdownload "Contacts","Company Server"
Once the remote host has been added, you’ll see it listed in the Server Administration Wizard.
A third optional parameter can be used to specify additional options, including the path to save the downloaded file, whether or not to display notifications, and how progress should be displayed.
The path= tag allows the program to specify where the file should be downloaded. (If this parameter is omitted, the user will be prompted for the location with a dialog.) This example is similar to the previous one, but the user is not prompted to select a download location. Instead, the database will be saved in the Databases folder inside the Documents folder (these folders must already exist).
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/"}
Normally the downloaded file has the same name as the server database, but you can use a different filename by including it in the path specification. You must include the full filename, including the .pandb extension.
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/Contact List.pandb"}
Panorama normally saves the location of downloaded databases, so that you can automatically open them with the Server Administration Wizard. If you don’t want that to happen, use the savepath=no tag.
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/" savepath=no}
There are also two options that control how this statement interacts with the download manager in the Server Administration Wizard. The defaultpath= tag controls whether the download path becomes the default path for later downloads, the default is no. The downloadmanager= tag controls whether or not the download will be displayed in the Server Administration Wizard download manager, again the default is no.
Use the open= tag if you would like the database to automatically open after it is downloaded, like this:
hostdownload "Contacts","Company Server",{open=yes}
If you want Panorama to skip the download step if the database has already been opened, use the redownload=no tag. This usually only makes sense if you also use the open=yes tag. This example will open the shared Contacts database. If it hasn’t been downloaded to this computer yet, it will download it first, then open it. If the database has already been downloaded, it will simply open the previously downloaded copy. (Note: This will not work if it was previously downloaded with the savepath=no tag, or if the database was manually transferred to this computer via email, USB stick, etc.)
hostdownload "Contacts","Company Server",{open=yes redownload=no}
By the way, you can use the shareddatabasebookmarkedpath( function to find the local copy of a shared database, like this.
shareddatabasebookmarkedpath("Company Server","Contacts") ☞ /Users/myname/Documents/Contacts.pandb
If the database hasn’t been downloaded yet, this function will return empty text (""). But if you’re using the hostdownload statement you don’t need to check this yourself, the hostdownload statement checks for you.
The notify= tag specifies whether you would like a notification at the beginning and/or end of the download. This example automatically displays a notification when the download starts, and again when it finishes.
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/" notify="start,finish"}
Actually the notify= tag in this example is unnecessary, since notification at the start and finish are the default. Here is how you would download without any notifications.
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/" notify=no}
If the hostdownload statement is used with a form, you can use a Progress Indicator object to display the progress of the download. Use the progress= tag to tell the hostdownload statement the name of the variable used by the Progress Indicator object. The Progress Indicator object should be set to a range of 0 to 100. As the download proceeds, this variable will be updated with the completion percentage. You could also display this percentage numerically with a Text Display Object.
If you are performing multiple concurrent downloads, you will need to use multiple variables. You can come up with the individual names yourself, or you can set up a template that automatically creates the variable names using the database and server names. In the progress= tag, use «database» where you want the database name inserted, and «host» where you want the server name inserted. Of course you’ll need to adjust the formula in your Progress Indicator objects accordingly.
hostdownload "Contacts","Company Server",{progress=download_progress_«host»_«database»}}
The Server Administration Wizard uses this technique to display download progress in a Matrix Object. If you want to display multiple progress values in a matrix, you’ll need to also update the entire matrix as progress occurs. To do this you must use the extraprogress= tag to tell the hostdownload statement the name of the variable that contains the matrix data.
hostdownload "Contacts","Company Server",{progress=download_progress_«host»_«database» extraprogress=PendingDownloadArray}}
To further customize, you have the option of running your own custom code at either the start of the download, the finish of the download, or both. To do this you have to add special labels to your code: startHostDownload: for code to run at the start of the download, and finishedHostDownload: for code to run after the download is complete (this runs before the database is opened, if you specified automatic opening). (See the goto statement to learn more about creating labels.)
Here is an example written to download the Contacts database, then when the download is complete ask the user if they want to open it now.
hostdownload "Contacts","Company Server",{path="~/Documents/Databases/" notify=no}
return
finishedHostDownload:
let downInfo = parameter(1)
let downloadedDatabase = getdictionaryvalue(downInfo,"DATABASE")
let serverName = getdictionaryvalue(downInfo,"HOST")
let downloadTime = getdictionaryvalue(downInfo,"ELAPSEDTIME")
alertmodal downloadedDatabase+" is ready, open it?",
"TEXT","Download completed from "+serverName+" in "+pattern(downloadElapsedTime,"# second~")+".",
"BUTTONS","Yes,No"
if info("dialogtrigger") = "Yes"
opendatabase getdictionaryvalue(downInfo,"PATH")
endif
As shown in this example, Panorama passes one parameter to the startHostDownload: and finishedHostDownload: procedures (the example above doesn’t have a startHostDownload: label, so no custom code is run at the start of the download). This parameter contains a dictionary that holds information about the downloaded file, including:
finishedHostDownload: code.Warning: The custom code cannot access or modify any local variables that were set up in the main part of the procedure. This is why many of the values that were set up by the main code (database name, server name, etc.) are passed to the custom code in a dictionary, otherwise that code could not access these values even though they were set up elsewhere in the same procedure.
See Also
History
| Version | Status | Notes |
| 10.2 | New | New in this version. |