# Appendix A: Functions

This appendix lists and describes all the UPLOADit functions available to your FileMaker scripts. Each function lists a few examples, related functions, and possible error responses.

## Upld-DefineRealmXML

Use this function to define realms from within your database. The XML you give this function is set up in the exact same way the UPLOADit_Realms.xml file is set up. When you define realms with this function, they are immediately available and they are added to the UPLOADit_Realms.xml file for the next time your UPLOADit server is stopped and restarted.

### Example

External("Upld-DefineRealmXML", "<UPLOADit><realm name='newrealm'><path>/UPLOADit/newrealm/</path></realm></UPLOADit>")
External("Upld-DefineRealmXML", New_Realm_XML_Field)

### Related

Upld-DeleteRealm

### Possible Error Responses [?]

"XXX; Line: YYY; Column: ZZZ"
  The plug-in had a problem parsing the XML you gave it. The error will be XXX. The error occurred at line YYY, column ZZZ in the XML you gave it.
"Could not allocate memory for the Upload Server."
  The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

## Upld-DeleteRealm

Use this function to delete a defined realm. You can delete any realm that has been defined either through the Upld-DefineRealmXML function, through the Configuration Dialog, or through the UPLOADit_Realms.xml file. The parameter you give this function should be the name of the realm you need to delete.

### Example

External("Upld-DeleteRealm", "myrealm")

### Related

Upld-DefineRealmXML

### Possible Error Responses [?]

"No Realm exists with the name 'XXX'"
  The realm you were trying to delete does not exist.
"Could not allocate memory for the Upload Server."
  The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.
"You must specify the name of the Realm to Delete."
  You did not specify the name of a realm. Make sure you define a parameter.

## Upld-File-Copy

Use this function to copy one file to another location on your hard drive. This function takes two named parameters, the "src" and "dest" parameters. The "src" parameter is the full path to the file that you would like to copy. The "dest" parameter is the full path to the folder where you would like to copy the file to. (The "dest" parameter can also point to a non-existent file, and the file you are copying will be renamed as it is copied.) The "src" and "dest" parameters can be in any order, but they must be separated by a semicolon (";").

### Example

External("Upld-File-Copy", "src='c:\UPLOADit\image.jpg'; dest='c:\my files\' ")
External("Upld-File-Copy", "src='/UPLOADit/flower.jpg'; dest='/UPLOADit/image.jpg' ")

### Related

Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Exists
Upld-File-Move
Upld-File-Rename
Upld-File-Size

### Possible Error Responses [?]

"You cannot copy Folders with this function; you must specify a File."
  You can only copy files with this function.
"Source File does not exist."
  The file you are trying to copy does not exist.
"Source File is invalid: XXX"
  XXX represents the reason why the file you are trying to copy or the path to that file is invalid.
"You must specify the Source File ('src' parameter)."
  You did not specify the file you are trying to copy. Make sure you have the 'src' parameter defined.
"File Destination is invalid: XXX"
  XXX represents the reason why the destination path you are trying to copy the file to is invalid.
"You must specify the File Destination ('dest' parameter)."
  You did not specify a destination for the file you are trying to copy. Make sure you have the 'dest' parameter defined.
"File Copy Failed: XXX"
  XXX represents an error from the operating system.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

## Upld-File-CreateFolder

Use this function to create a folder (directory) on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "folder" parameter is the full path to the non-existent folder that you would like to create. If you specify multiple sub-folders that do not exist, they will all be created. In other words, if you specify the folder "c:\this\is\a\test\", and none of the "this", "is", "a", or "test" folders exist, they will all be created.

### Example

External("Upld-File-CreateFolder", "folder='/UPLOADit/new folder/' ")
External("Upld-File-CreateFolder", "c:\this\is\a\test\")

### Related

Upld-File-Copy
Upld-File-Delete
Upld-File-Exists
Upld-File-Move
Upld-File-Rename
Upld-File-Size

### Possible Error Responses [?]

"You must specify a name for the New Folder ('folder' parameter)."
  You did not specify a name for the folder you are trying to create. Make sure you have the 'folder' parameter defined.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper function syntax.
"Folder Creation Failed: XXX"
  XXX represents an error from the operating system.

## Upld-File-Delete

Use this function to delete a file from your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the existing file that you would like to delete.

### Example

External("Upld-File-Delete", "file='c:\UPLOADit\delete me.txt' ")
External("Upld-File-Delete", "/Documents/old image.jpg")

### Related

Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Exists
Upld-File-Move
Upld-File-Rename
Upld-File-Size

### Possible Error Responses [?]

"You cannot delete Folders with this function; you must specify a File."
  You can only delete files with this function.
"File does not exist."
  The file you are trying to delete does not exist.
"File Name is invalid: XXX"
  XXX represents the reason why the file you are trying to delete or the path to that file is invalid.
"You must specify a File to Delete ('file' parameter)."
  You did not specify the file you are trying to delete. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"File Deletion Failed: XXX"
  XXX represents an error from the operating system.

## Upld-File-Exists

Use this function to see if a file exists on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the file that you are testing the existence of.

### Example

External("Upld-File-Exists", "file='c:\UPLOADit\test.txt' ")
External("Upld-File-Exists", "/Documents/image.jpg")

### Related

Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Move
Upld-File-Rename
Upld-File-Size

### Possible Error Responses [?]

"You must specify a File to test ('file' parameter)."
  You did not specify the file you are trying to test for. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"File-Exists: XXX"
  XXX represents an error from the operating system.

## Upld-File-GetPathToDB

Use this function to retrieve the path to the folder containing the database you specify. This function will only work for databases that are on the local machine. The parameter you give must be the file name of the database you need the path from. If you need the path of the database where your script is running, you can use the Status(CurrentFileName) function to get the file name of the database. (If you ever changed the name of your database, using the Status(CurrentFileName) function would take that into account and this function would always work as expected.)

### Example

External("Upld-File-GetPathToDB", "mydb.fp5")
External("Upld-File-GetPathToDB", Status(CurrentFileName))

### Related

Upld-File-GetPathToFM

### Possible Error Responses [?]

"Database 'XXX' is not on the local hard drive."
  The database that you specified does not exist on the local hard drive (most likely it is a shared database), so the plug-in can't return the file path to you.
"Database 'XXX' does not exist."
  The database you specified is not currently open in FileMaker.
"You must specify the name of the database."
  You did not specify the name of the database that you are trying to get the file path for.

## Upld-File-GetPathToFM

Use this function to retrieve the path to the folder containing the FileMaker Pro application on your hard drive. This function does not take a parameter, so you can use the empty string ("").

### Example

External("Upld-File-GetPathToFM", "")

### Related

Upld-File-GetPathToDB

## Upld-File-Move

Use this function to move one file to another location on your hard drive. This function takes two named parameters, the "src" and "dest" parameters. The "src" parameter is the full path to the file that you would like to move. The "dest" parameter is the full path to the folder where you would like to move the file to. (The "dest" parameter can also point to a non-existent file, and the file you are moving will be renamed as it is moved.) The "src" and "dest" parameters can be in any order, but they must be separated by a semicolon (";").

### Example

External("Upld-File-Move", "src='c:\UPLOADit\image.jpg'; dest='c:\my files\' ")
External("Upld-File-Move", "src='/UPLOADit/flower.jpg'; dest='/UPLOADit/image.jpg' ")

### Related

Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Exists
Upld-File-Rename
Upld-File-Size

### Possible Error Responses [?]

"You cannot move Folders with this function; you must specify a File."
  You can only move files with this function.
"Source File does not exist."
  The file you are trying to move does not exist.
"Source File is invalid: XXX"
  XXX represents the reason why the file you are trying to move or the path to that file is invalid.
"You must specify the Source File ('src' parameter)."
  You did not specify the file you are trying to move. Make sure you have the 'src' parameter defined.
"File Destination is invalid: XXX"
  XXX represents the reason why the destination path you are trying to copy the file to is invalid.
"You must specify the File Destination ('dest' parameter)."
  You did not specify a destination for the file you are trying to move. Make sure you have the 'dest' parameter defined.
"File Move Failed: XXX"
  XXX represents an error from the operating system.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

## Upld-File-Rename

Use this function to rename an existing file on your hard drive. This function takes two named parameters, the "file" and "newname" parameters. The "file" parameter is the full path to the file that you would like to rename. The "newname" parameter is the new file name for the existing file. The "file" and "newname" parameters can be in any order, but they must be separated by a semicolon (";").

### Example

External("Upld-File-Rename", "file='c:\UPLOADit\image.jpg'; newname='image_backup.jpg' ")
External("Upld-File-Rename", "file='/UPLOADit/flower.jpg'; newname='image.jpg' ")

### Related

Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Exists
Upld-File-Move
Upld-File-Size

### Possible Error Responses [?]

"You cannot rename Folders with this function; you must specify a File."
  The path you specified pointed to a folder instead of a file.
"File does not exist."
  The path you specified pointed to a non-existent file.
"You must specify the File to Rename ('file' parameter)."
  You did not specify a file to rename. Make sure you have the 'file' parameter defined.
"You must specify a New Name for the File ('newname' parameter)."
  You did not specify a new name for the file. Make sure you have the 'newname' parameter defined.
"File Renaming Failed: XXXX"
  The plug-in could not rename the file for some reason. The "XXXX" should be the reason why it could not rename the file.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

## Upld-File-Size

Use this function to get the size of a file on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the file that you would like to get the size of.

### Example

External("Upld-File-Size", "file='/UPLOADit/image.jpg' ")
External("Upld-File-Size", "c:\my files\document.txt")

### Related

Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Exists
Upld-File-Move
Upld-File-Rename

### Possible Error Responses [?]

"You cannot get the size of Folders with this function; you must specify a File."
  You can only get the size of files with this function.
"File does not exist."
  The file you are trying to get the size of does not exist.
"File Name is invalid: XXX"
  XXX represents the reason why the file you are trying to get the size of or the path to that file is invalid.
"You must specify a File to get its Size ('file' parameter)."
  You did not specify the file you are trying to get the size of. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"Getting File Size Failed: XXX"
  XXX represents an error from the operating system.

## Upld-GetFieldValue

When a user uploads a file to your UPLOADit server, they submit a web form with their web browser. This web form can contain any number of web form fields. Use this function to get the value from any one of those form fields. The parameter you give this function should be the name of the field you need the value of. For example, if the web form contained a form field like this:

<input type="text" name="FirstName">

Then you could use this function with the parameter "FirstName" to get the value the user entered into that field in their web browser.

You also use this function to get special values about the currently connected user. Use one of the following parameter names to get that special value:

- "UPLOADit_Realm" - The name of the realm the currently connected user has uploaded files to.
- "UPLOADit_User" - The user name the currently connected user used in the User Name/Password dialog presented to them when they uploaded. (Note: The User Name/Password dialog is only displayed when you have defined a Password in your realm.)
- "UPLOADit_Result_URL" - If the web form has defined this value, this will return the Result URL that the users web browser will be redirected to. Most likely you will not need to retrieve this value into your database.
- "UPLOADit_IP" - The IP address of the currently connected user.

This function is only useful when a user's web browser is connected to your UPLOADit server. When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can use this function to retrieve the values from this user's web browser and then call the "Upld-ReleaseClient" function to redirect the user's web browser to its final location.

### Example

External("Upld-GetFieldValue", "FirstName")
External("Upld-GetFieldValue", "UPLOADit_User")

### Related

Upld-ReleaseClient
Upld-SetResultURL

### Possible Error Responses [?]

"There is no client connected."
  A user's web browser must be connected to your UPLOADit server to retrieve values from the web form they submitted. If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.
"You must specify which field value to retrieve."
  You did not specify the name of the form field you are trying to get the value of.

## Upld-Port

Use this function to define the TCP/IP port that you need your UPLOADit server to listen for connections on. By default, the port is set to 8080, but you can use anything in the range of 0 to 65535. There is one exception to this and that is on Mac OS X, where you cannot set the port below 1024 unless the FileMaker Pro process is running with super user privileges (something that is probably not a good idea). You must define this port before starting the server if you need it to be different than the default. (Note: If you change the port that your UPLOADit server listens for connections on, make sure you update the "action" attribute of your web form that upload files to your UPLOADit server. For more information on setting up your web form, please see the Chapter 2, "How to set up your Web Page Form", in this documentation.)

### Example

External("Upld-Port", "7777")

### Related

Upld-StartServer

### Possible Error Responses [?]

"You cannot change the port when the server is running. Stop the server and try again."
  You tried to change the port after the UPLOADit server was started.
"Could not allocate memory for the Upload Server."
  The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

## Upld-Register

Use this function to register your copy of UPLOADit. There are two ways you can use this function. If you specify the parameter "DIALOG", the plug-in will display a dialog asking you to fill in your registration information. Alternatively, you can specify your registration information in the order "First Name", "Last Name", and "Registration Number" all separated by the pipe character ("|"; usually created by typing shift-backslash). Whenever you use this function, you will be presented with a dialog containing our License Agreement for the plug-in that asks you to accept the agreement. If you need to use this function in a startup script to register the plug-in every time the solution starts, you can auto-accept the License Agreement by adding "|I Accept the License Agreement" to the end of your registration information.

### Example

External("Upld-Register", "DIALOG")
External("Upld-Register", "John|Doe|12-3456-7890-ABC-DEF-01")
External("Upld-Register", "First Name|Last Name|Registration Number|I Accept the License Agreement")

## Upld-ReleaseClient

When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can retrieve the values from the form that you need, possibly set a Result URL, and then you must release the user's web browser so that it can be redirected to its final location. Use this function to do that. If you do not use this function to release the user's web browser, the user's web browser will never get redirected and will either sit there forever doing nothing, or eventually time out and tell the user that the server did not respond. This function does not take a parameter, so you can use the empty string ("").

### Example

External("Upld-ReleaseClient", "")

### Related

Upld-GetFieldValue
Upld-SetResultURL

### Possible Error Responses [?]

"There is no client connected."
  If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.

## Upld-SetResultURL

When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can retrieve the values from the form that you need, and based on those values, you can decide if you need to redirect the user's web browser to an alternate page than what is defined in the realm or in the web form. You would then release the user's web browser to redirect it to the URL you have specified. One possible use for this feature is to validate the information the user has filled into your web form. For example, if your form asks for their name, zip code, and their resume file, and they submit the form without filling in their name field, you could redirect their web browser to an "error" page instead of the default "thank you" page that you have defined in your realm. (For more information on setting the Result URL based on form field values, please see Chapter 3, "How to set up your UPLOADit FileMaker Script".)

### Example

External("Upld-SetResultURL", "http://www.yahoo.com/")
External("Upld-SetResultURL", "http://www.myserver.com/error.htm?desc=Missing%20Name")

### Related

Upld-GetFieldValue
Upld-ReleaseClient

### Possible Error Responses [?]

"There is no client connected."
  A user's web browser must be connected to your UPLOADit server to set the Result URL to forward their web browser to after you release the client. If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.
"You must specify the Result URL."
  You did not specify the Result URL you want to set.

## Upld-StartServer

Use this function to start your UPLOADit server. This function first loads your realms from the UPLOADit_Realms.xml file, and then starts the server if it could successfully load the realm file. If this function has a problem loading the UPLOADit_Realms.xml file, it will report that error to your result field and not start the server. If you make changes to the UPLOADit_Realms.xml file on your hard drive, you will need to stop (using the Upld-StopServer function) and restart the server (using this function). If you make changes to the realms using the Upld-DefineRealmXML function or through the Configuration Dialog, those changes are active immediately; you do not need to stop and restart the server for those changes to take effect. (Changes made through the Upld-DefineRealmXML function or through the Configuration Dialog will be saved to your UPLOADit_Realms.xml file so that they will be retained if you do stop and restart your server, though.) This function does not take a parameter, so you can use the empty string ("").

### Example

External("Upld-StartServer", "")

### Related

Upld-Port
Upld-StopServer

### Possible Error Responses [?]

"Max Connections needs to at least be set to 1."
  The Max Connections setting was set to 0, which means that no one would be able to connect.
"Port is invalid: XXX"
  The port you specified is invalid.
"There was an error creating the server connection; check the Port."
  The plug-in could not start listening for incoming connections. You might want to check the TCP/IP Port to make sure it is not conflicting with another service on your computer. If you are on OS X, you may need to make sure you are not trying to use a TCP/IP Port number less than 1024.
"Error Loading Realm XML File: XXX; Line: YYY; Column: ZZZ"
  The plug-in had a problem parsing the UPLOADit_Realms.xml file. The error will be XXX. The error occurred at line YYY, column ZZZ in the UPLOADit_Realms.xml file.
"The server has already been started on port: XXX"
  The UPLOADit server is already running on TCP/IP Port XXX.
"Could not allocate memory for the Upload Server."
  The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.
"Error parsing parameters: XXX"
  The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

## Upld-StopServer

Use this function to stop your UPLOADit server. If you make changes to your UPLOADit_Realms.xml file on your hard drive, you can use this function and then the "Upld-StartServer" function to enable your changes. This function does not take a parameter, so you can use the empty string ("").

### Example

External("Upld-StopServer", "")

### Related

Upld-StartServer

### Possible Error Responses [?]

"Upload Server Object is NULL."
  The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

## Upld-Version

Use this function to return the version of the UPLOADit plug-in you have loaded in FileMaker Pro.

If you will be using the Auto Plug-in Update feature of the latest versions of FileMaker Server to distribute this plug-in to FileMaker Pro client machines, you will want to use the special "AUTO UPDATE" parameter with this function. When you use the special "AUTO UPDATE" parameter with this function, it will return the version of the plug-in in a "Auto Update friendly" form that can be used with the TextToNum() calculation function in FileMaker to accurately determine if one version is newer than another. Any time that you will be working with the version of the plug-in for Auto Update purposes, you should use the "AUTO UPDATE" parameter.

You can also use this function to bring up the UPLOADit Configuration Dialog without having to go through FileMaker Pro's Application Preferences dialog. If you give this function the parameter "CONFIGURE", it will open the UPLOADit Configuration Dialog just as if you went through FileMaker Pro's Application Preferences dialog. If you give this function the parameter "ABOUT", it will open the UPLOADit Configuration Dialog, but the first tab that will be shown will be the "About" tab, which contains version and registration information for the plug-in.

### Example

External("Upld-Version", "")
External("Upld-Version", "AUTO UPDATE")
External("Upld-Version", "CONFIGURE")
External("Upld-Version", "ABOUT")