uploadfiletoserver
UPLOADOPTIONS
,
REPLY

The uploadfiletoserver statement uploads a file or folder to a Panorama server.


Parameters

This statement has two parameters:

uploadoptions – dictionary of additional options. This dictionary must contain a FILE entry with the path and name of the file to be uploaded. The HOST entry specifies the name of the server the file is to be uploaded to, if this is missing, the host of the current database is used (if the current database isn’t shared, this is an error). If CALLBACKLABEL is present, upload will be asynchronous, and label must specify a label in the calling procedure that will be called back when the upload is complete. If there is a COMPRESS entry with a true value ("YES", "TRUE", true(), etc), the file will be compressed before uploading and then decompressed on the server (the compress option is set automatically if uploading a folder). If UPLOADFOLDER is present, the finished file will be moved into the specified folder on the server, the options are "WEBDOCUMENTSPATH", "APACHEWEBDOCUMENTSPATH" and "PUBLICDATABASEPATH". Any additional values will be passed thru to the callback routine. If there is a PROGRESSINBANNER entry with a true value ("YES", "TRUE", true(), etc) then the progress of the upload will be displayed in the tool bar banner.

reply – dictionary with information about finished upload, including tempfileid on server. If asynchronous, this parameter is not used, but the same dictionary will be passed to the callback.


Description

This statement uploads a file to a temporary file on the specified server. The upload operation is controlled by a dictionary of options passed to the statement. At a minimum, this dictionary must contain the path and name of the file to upload/ Here is a basic example that allows the user to choose an image file and upload it to a server named “Test Server”.

local fileChoice,uploadReply
choosefileDialog fileChoice,".jpg.gif.png"
uploadfiletoserver initializedictionary(
    "FILE",fileChoice,
    "HOST","Test Server"
    ),uploadReply
let uploadedFileID = getdictionaryvalue(uploadReply,"TEMPFILEID")

Advanced options can be controlled by adding additional options to the specification dictionary. This example is nearly identical to the previous example, but the uploaded file is compressed before being uploaded, then uncompressed on the server end. In other words, the final result is the same as the previous example, but most likely the upload will be faster since the data is compressed for the upload. Another advantage of using compression is that it allows folders and packages to be uploaded (in fact, the compress option is automatically enabled if a folder or package is supplied for upload). Since the upload may take a while, this example also uses the progressinbanner option to show the progress of the upload in the tool bar banner (in the center of the tool bar).

local fileChoice,uploadReply
choosefileDialog fileChoice,".jpg.gif.png"
let uploadOptions = initializedictionary(
    "FILE",fileChoice,
    "HOST","Test Server",
    "COMPRESS","YES",
    "PROGRESSINBANNER","YES")
uploadfiletoserver uploadOptions,uploadReply
let uploadedFileID = getdictionaryvalue(uploadReply,"TEMPFILEID")

The uploaded file is usually placed in a temporary folder on the server, but you can also specify a destination folder. Only specific named folders are allowed, including: "WEBDOCUMENTSPATH", "APACHEWEBDOCUMENTSPATH" and "PUBLICDATABASEPATH". This example uploads an image into the public database folder. Note that when a file or folder is uploaded into a specified folder, it is given the same name it had on the client. If a file or folder with that name already exists, it will be replaced.

local fileChoice,uploadReply
choosefileDialog fileChoice,".jpg.gif.png"
let uploadOptions = initializedictionary(
    "FILE",fileChoice,
    "HOST","Test Server",
    "COMPRESS","YES",
    "PROGRESSINBANNER","YES",
    "UPLOADFOLDER","WEBDOCUMENTSFOLDER")
uploadfiletoserver uploadOptions,uploadReply

Asynchronous Uploads

All of the previous example upload the file synchronously – in other words, Panorama would stop everything else until the upload was complete. Since a file upload make take a while, you may want to let the upload happen in the background, allowing normal Panorama operation in the meantime. To do this, add a CALLBACKLABEL option to the options dictionary, and remove the reply parameter from the statement. This option must correspond to a label in the procedure. When the upload is finished, Panorama will call the subroutine at this label, passing the reply dictionary as a parameter. If your code needs to do any additional work after the upload is finished, this is where that work will be done.

local fileChoice,uploadReply
choosefileDialog fileChoice,".jpg.gif.png"
let uploadOptions = initializedictionary(
    "FILE",fileChoice,
    "HOST","Test Server,
    "COMPRESS","YES",
    "PROGRESSINBANNER","YES",
    "UPLOADFOLDER","PUBLICDATABASEPATH",
    "CALLBACKLABEL","Done"
    )
uploadfiletoserver uploadOptions
return
// finish upload task
Done:
let uploadReply = parameter(1)
let uploadedFileID = getdictionaryvalue(uploadReply,"TEMPFILEID")
message uploadedFileID

Keep in mind that the code that runs after the upload is complete is being called separately from the main code in this procedure. Local variable values that existed in the main code are not available to this code. You can put extra values in the option dictionary in the main part of the code, these will be passed to the callback reply dictionary. In this example, the time the file was uploaded is saved and then can be used by the callback code.

local fileChoice,uploadReply
choosefileDialog fileChoice,".jpg.gif.png"
let uploadOptions = initializedictionary(
    "FILE",fileChoice,
    "HOST","Test Server,
    "COMPRESS","YES",
    "PROGRESSINBANNER","YES",
    "UPLOADFOLDER","PUBLICDATABASEPATH",
    "CALLBACKLABEL","Done",
    "TIME",timepattern(now(),"hh:mm am/pm")
    )
uploadfiletoserver uploadOptions
return
// finish upload task
Done:
let uploadReply = parameter(1)
let uploadTime = getdictionaryvalue(uploadReply,"TIME")
message "Upload time: "+pattern(now()-uploadTime,"# second~")

This example only used one extra value, but you can pass as many extra values as you like.


See Also


History

VersionStatusNotes
10.2NewNew in this version.