Programming Server Event Scripts

Programming Robo-FTP Server Event Scripts is very similar to programming Robo-FTP Client Command scripts, with a few notable exceptions.

Server Event Scripts start with the current user's home directory as the current working directory and commands that require active user input should not be used with Server Event Scripts because the event script processor does not display a window when it executes. A few of the commands that should not be used for this reason are ASK, BROWSE, MESSAGEBOX and BREAK. Basically, you need to avoid all commands that require a human to type or click anything. Please see the "Script Programming" section of the Script Help File installed with Robo-FTP Server for the full list of available commands.

The Logon and Begin* events can alter server behavior with their return code. For more information on returning error codes from scripts see the Returning Error Codes from Scripts topic under Select Topics in Script Programming in the Robo-FTP Script Help File. In those cases the some error codes have special meanings. Any non zero value not listed below will result in a permission denied response. The special error codes are listed below.

The third difference is that each server event populates a set of variables with information relevant to the event. These variables are listed below. The ones in black cannot be changed, the ones in red can be altered to change server behavior.

Each of the event variables initially set during the Logon Event (with the exception of %event_logondatetime) will also be available during all other event types.

Logon Event

%event_logonname -- User name of user that just logged on. This variable is set for all event types.

%event_logonhome -- Full path for home directory of user that just logged on. In the logon event this can be changed to give the user  a different home directory for this log in session. This variable is set for all event types.

%event_logonremoteip -- Address of user that just logged on. This variable is set for all event types.

%event_logonprotocol -- Connection protocol of user that just logged on. This variable is set for all event types.

%event_logondatetime -- Date and time of the logon event (in the same format as the existing %datetime script variable.)

 Note: Logon event scripts do not run until after a user is successfully authenticated, in order to conserve system resources. However, the log on itself will be rejected if the script returns a non-zero value.

Logoff Event

%event_logoffresult -- Logoff error code, zero indicates success logoff, non zero indicates some kind of abnormal disconnect.

%event_logoffname -- User name of user that just logged off. This variable is deprecated, use %event_logonname instead.

%event_logoffhome -- Full path for home directory of user that just logged off. This variable is deprecated, use %event_logonhome instead.

%event_logoffdatetime -- Date and time of the logoff event (in the same format as the existing %datetime script variable.)

Begin Upload Event

%event_uploadfile -- Name of the file to be uploaded

%event_uploadfolder -- Name of the folder where file will be uploaded.

%event_uploadpath -- Full path and file name for file to be uploaded to. This can be changed during the event to upload to a different location.

%event_uploaddatetime -- Date and time of the upload event (in the same format as the existing %datetime script variable.)

%event_uploadargs[*] -- An array containing query string arguments for HTTP uploads. A query string of ?arg1=value1 would result in %event_uploadargs[arg1] = "value1"

Upload Complete Event

This event fires after upload is complete. Please note that many clients rename the file after upload is complete for resume managment purposes. This can cause an error during the rename on the client or the variables listing file information below to be incorrect.

%event_uploadresult -- Upload error code, zero indicates success.

%event_uploadfile -- Name of the file just uploaded (or that was attempted, if known.)

%event_uploadfolder -- Name of the folder where file was just uploaded.

%event_uploadpath -- Full path and file name for file that was just uploaded.

%event_uploadfilesize -- Size in bytes of the file that was just uploaded.

%event_uploaddatetime -- Date and time of the upload event (in the same format as the existing %datetime script variable.)

%event_uploadfiledatetime -- Data and time of the uploaded file.

Begin Download Event

%event_downloadfile -- name of the file to be downloaded (or that was attempted, if known)

%event_downloadfolder -- name of the folder where file will be downloaded from.

%event_downloadpath -- full path and file name for file that is to be downloaded. This can be changed to have it download a different file. Note: This may confuse some clients progress indicator as they will be expecting a file of one size and getting a different one.

%event_downloadfilesize -- size in bytes of the file that was just downloaded

%event_downloaddatetime -- date and time of the download event (in the same format as the existing %datetime script variable)

%event_downloadfiledatetime -- data and time of the downloaded file

Download Complete Event

%event_downloadresult -- download error code, zero indicates success

%event_downloadfile -- name of the file just downloaded (or that was attempted, if known)

%event_downloadfolder -- name of the folder where file was just downloaded

%event_downloadpath -- full path and file name for file that was just downloaded

%event_downloadfilesize -- size in bytes of the file that was just downloaded

%event_downloaddatetime -- date and time of the download event (in the same format as the existing %datetime script variable)

%event_downloadfiledatetime -- data and time of the downloaded file

Change Directory Event

%event_chgdirresult -- directory change error code, zero indicates success

%event_fromchgdirname -- full path name of directory just exited

%event_tochgdirname -- full path name of directory just entered

%event_chgdirdatetime -- date and time of the directory change event (in the same format as the existing %datetime script variable)

Note: This event is not triggered on SFTP connections

Delete Complete Event

%event_deleteresult -- delete error code, zero indicates success

%event_deletefile -- name of the file just deleted (or that was attempted, if known)

%event_deletefolder -- name of the folder where file was just deleted

%event_deletepath -- full path and file name for file that was just deleted

%event_deletefilesize -- size in bytes of the file that was just deleted

%event_deletedatetime -- date and time of the delete event (in the same format as the existing %datetime script variable)

%event_deletefiledatetime -- data and time of the deleted file

Rename Complete Event

%event_renameresult -- rename error code, zero indicates success

%event_renamelocalfile -- name of the local file that was the subject of the rename attempt (if known)

%event_renamelocalfolder -- folder containing the local file that was the subject of the rename attempt

%event_renamelocalpath -- full name and path of the local file that was the subject of the rename attempt

%event_renamenewlocalfile -- post-rename local file name

%event_renamenewlocalfolder -- post-rename local path of the folder containing the file that was the subject of the rename attempt

%event_renamenewlocalpath -- post-rename full name and path of the local file

%event_renameoldserverpath -- old file name and path relative to server root (as served to client)

%event_renamenewserverpath -- new file name and path relative to server root (as served to client)

%event_renamefilesize -- size in bytes of the file that was just renamed

%event_renamedatetime -- date and time of the rename event (in the same format as the existing %datetime script variable)

%event_renamefiledatetime -- data and time of the renamed file

Post Begin Event

%event_postpath -- path to the target of the POST

%event_postdatetime --  date and time of the POST event (in the same format as the existing %datetime script variable)

%event_postvariables[*]  -- An array containing arguments passed using the HTTP POST method. When the Post event is made using the multipart/form-data content-type and a file is uploaded as part of the post, these variables will only be be populated when they appear prior to the file data in the HTTP message body.

Note: This event is only triggered on HTTP connections

The %event_kind variable is populated for every type of event and contains the name of the event that triggered the script. This makes it possible to design a single Server Event Script to handle more than one type of event.

For most reliable operation, event scripts that use commands with file pointers should explicitly reset the pointer at the beginning of the script. This applies to commands like GETNEXTFILE, GETFILE, GETSITEFILE, FTPGETFILE and WRITEFILE.

Best practices dictate that Server Event Script files be saved in the \ProgramData\Scripts folder under the Robo-FTP Server installation directory so they will be automatically included if you ever need to transfer the Robo-FTP Server installation to a new machine (see: Moving Robo-FTP Server to Another Computer.)

See also: Debugging Server Event Scripts