Name: libURLftpUpload

Type: command

Syntax: libURLftpUpload <value>, <uploadURL> [, <callbackMessage>]

Summary: <upload|Uploads> data to an Internet <server> asynchronously via <FTP>.

Introduced: 1.1.1

OS: mac,windows,linux

Platforms: desktop,server,web

Security: network

Example:
libURLftpUpload field "Data","ftp://ftp.example.org/file.txt"

Example:
libURLftpUpload URL "binfile:data.jef",myURL,"uploadDone"

Example:
libURLftpUpload myData,"ftp://me:secret@example.net/file.txt"

Parameters:
value (string): 
uploadURL: The uploadURL specifies the server and location to upload to, in the form of an FTP URL.
callbackMessage: The name of a message to send after the URL is uploaded.

Description:
Use the <libURLftpUpload> <command> to put a <file> on a server.

The <libURLftpUpload> <command> is <non-blocking>, so it does not stop the current <handler> while the <upload> is completed. The <handler> continues while the <libURLftpUpload> <command> <upload|uploads> the <URL(keyword)> in the background. You can monitor the <upload> by checking the <URLStatus> <function(control_st)> periodically.

To upload a URL while blocking other operations, use the <put> <command> instead.

To upload a file, use the file <URL(keyword)> type (for <text file|text files>) or the <binfile> <URL(keyword)> type (for <binary file|binary files>). Because referring to a <file> <URL(glossary)|URL's> contents loads the <file> into memory, if you are uploading a large <file>, make sure you have enough memory available. You can also use the <libURLftpUploadFile> <command> to upload a <file>.

The <callbackMessage> is sent to the <object> whose <script> contains the <libURLftpUpload> <command>, after the <upload> is complete, so you can handle the <callbackMessage> to perform any tasks you want to delay until the URL has been <upload|uploaded>. Two <parameter|parameters> are sent with the <message> : the <URL(keyword)> and the <URLStatus> of the <file>.

>*Warning:*  Avoid using the <wait> <command> in a <handler> after executing the <libURLftpUpload> <command>. Since the <libURLftpUpload> <command> is <non-blocking>, it may still be running when your <handler> reaches the <wait> <command>. And since the <libURLftpUpload> command is part of the <Internet library> and is implemented in a <handler>, the <wait> <command> will stop the <upload> process if it is <execute|executed> while the <download> is still going on. In particular, do not use constructions like the following, which will sit forever without <upload|uploading> the file:

  libURLftpUpload field "Upload Data",myURL
  wait until the URLStatus of myURL is "uploaded" -- DON'T DO THIS

The <URLStatus> <function(control_st)> returns the status of the <upload|uploaded> file. If you no longer need to monitor the file's status, use the <unload> <command> to remove it from the <URLStatus> <function(glossary)|function's> listing.

>*Important:*  The <libURLftpUpload> <command> is part of the <Internet library>. To ensure that the <command> works in a <standalone application>, you must include this <Revolution custom library|custom library> when you create your <standalone application|standalone>. In the Inclusions section of the <Standalone Application Settings> window, make sure "Internet Library" is selected in the list of script libraries.

>*Note:* When included in a <standalone application>, the <Internet library> is implemented as a hidden <group> and made available when the <group> receives its first <openBackground> message. During the first part of the <application|application's> startup process, before this <message> is sent, the <libURLftpUpload> <command> is not yet available. This may affect attempts to use this <command> in <startup>, <preOpenStack>, <openStack>, or <preOpenCard> <handler|handlers> in the <main stack>. Once the <application> has finished starting up, the <library> is available and the <libURLftpUpload> <command> can be used in any <handler>.

References: script (property), object (object), startup (message), openBackground (message), preOpenStack (message), openStack (message), preOpenCard (message), Internet library (library), library (library), Revolution custom library (library), URL (keyword), ftp (keyword), file (keyword), binfile (keyword), non-blocking (glossary), standalone application (glossary), application (glossary), handler (glossary), function (glossary), binary file (glossary), command (glossary), execute (glossary), URL (glossary), main stack (glossary), text file (glossary), Standalone Application Settings (glossary), server (glossary), upload (glossary), message (glossary), parameter (glossary), download (glossary), URLStatus (function), libURLSetStatusCallback (command), unload (command), put (command), load (command), libURLSetFTPStopTime (command), libURLftpUploadFile (command), wait (command), group (command), libURLSetFTPMode (command), function (control_st)

Tags: networking
