Using SyncBackPro > Technical Reference > Scripting

These are functions that are defined in your Runtime script and are called by SyncBackPro. A runtime script can be used to change what happens when a profile is run. For example, you could stop a profile from being run if certain conditions aren't met, or perform actions when some files are copied, deleted, or renamed. The functions are called by SyncBackPro at the appropriate time. Runtime scripts are used by profiles and have access to the SBRunning, SBSystem, SBVariables, and SBHistory objects.

All the example code below is written in using the Pascal scripting language.

The order in which these routines are called is listed below. However, it may not run exactly in this order depending on the profile settings, e.g. the Run After program may be called after the log file is created. Also, routines may not be called, e.g. it's not a Fast Backup, there is no Run Before program, etc.

[Ransomware detection]

[Silently fail if no network connection or no internet connection]

[Check is source and/or destination can be reached]

RunAfterConfig

RunRunBeforeBefore

[Run Before program]

RunRunBeforeAfter

[Connects to FTP etc.]

[Prepares the profile log]

RunLogLocationInfoToAdd

RunLogLocationInfoCaption

RunLogLocationInfoInfo

RunDeleteAll

RunBeforeScanning

[Scans source and destination]

RunBeforeFolderCompare

RunAfterFolderCompare

RunShowDiffWindow

[Differences window shown]

[Processes each file...]

RunBeforeCopyFile / BeforeCopyFileEx

RunBeforeSetDateTimes

[Run After program]

[Close log, display log]

[Network disconnect]

RunProfileResult

[Email log]

RunBeforeEmailLog

RunEmailLogAttachToAdd

RunEmailLogAttachFilename

RunAfterEmailLog

function RunBeforeCopyFile(ToLeft, Filename; var ToDirCreated; var FromFileLocked; var ToFileLocked; var DoneCopy);

ToLeft: True if the left/source file is to be copied from the right/destination

Filename: The file to be copied (not including the base path)

ToDirCreated: Set to True if a directory was created

FromFileLocked: Set to True if the file to be copied is locked

ToFileLocked: Set to True if the file to be replaced is locked

DoneCopy: Set to True if the file was copied

Return value: An error message if the copy failed

This function is called before a file is to be copied, and before any version is made. On failure the function should return an error message (do not return an error message if the script is not copying files). If a directory was created in order to copy the file then ToDirCreated should be returned as True. If the from file is locked then FromFileLocked should be returned as True (and an error message should be returned). If the to file is locked then ToFileLocked should be returned as True (and an error message should be returned). If the file was copied then DoneCopy should be returned as True.

Note that once a script has copied a file then no other scripts will be called to copy the file. This means the order of run-time scripts used in a profile is important.

This function is not called if the run is a simulation.

IMPORTANT: If the profile is using a file integrity database, and you have a RunBeforeCopyFileEx function, then RunBeforeCopyFileEx will be called instead of RunBeforeCopyFile.

See also RunDiffColumnsCount

function RunDiffColumnTitle(Col; var Width);

Col: The column number

Width: Set it to the width the column should be (in pixels)

Return value: The columns title

This subroutine is called from the Differences window when the title for a custom column is required. The first custom column is column zero (0). The script is only called for its custom columns and not for columns created by other scripts.

function RunDiffColumnTitle(Col, Width);

begin

if (Col = 0) then begin

Result:='Custom Column 1';

Width:=100;

end else begin

Result:='Custom Column 2';

Width:=150;

end;

function RunDisabledCheck(var NoLog);

NoLog: Set this to TRUE if a log should not be created

Return value: A reason why the script should not continue running

This function is called very early on in the profile run and gives the script a chance to stop the profile from running. If the script does not want the profile to run it should return the reason, otherwise it should return an empty string if the profile should continue.

To stop a log file from being produced then set NoLog to True. For example, you may expect certain conditions, e.g. the network being unavailable, and so do not want a log file to be produced.

NOTE: The error message from the profile run indicates the profile is disabled. However, it is not. It is just that run that was disabled (aborted).

function RunDisabledCheck(var NoLog);

begin

NoLog:=FALSE;

if SBRunning.Restore Then

Result:='You cannot restore your files'

else

Result:='';

end;

function RunEmailLogAttachFilename(Cnt);

Cnt: On the first call this is zero, and then incremented on each call

Return value: The filename of the file to attach. The file must exist and be readable.

This function is called when the log file is about to be emailed. It gives the script an opportunity to add custom file attachments to the email.

Note that RunEmailLogAttachToAdd is called first, and then RunEmailLogAttachFilename() is called the appropriate number of times.

IMPORTANT: This function is called in the context of the main user interface thread. This means, for example, that the script global variables will not be as expected.

See RunEmailLogAttachToAdd for an example.

function RunEmailLogAttachToAdd;

Return value: The number of files to attach

This function is called when the log file is about to be emailed. It gives the script an opportunity to add custom file attachments to the email.

Note that RunEmailLogAttachToAdd is called first, and then RunEmailLogAttachFilename is called the appropriate number of times.

IMPORTANT: This function is called in the context of the main user interface thread. This means, for example, that the script global variables will not be as expected.

function RunEmailLogAttachToAdd;

begin

Result:=2;

end;

function RunEmailLogAttachFilename(Cnt);

begin

If (Cnt = 0) Then

Result:='c:\path\filename1.txt'

Else

Result:='c:\path\filename2.txt';

end;

function RunLogLocationInfoCaption(Left, Cnt);

Left: True is this call is for information on the left/source

Cnt: On the first call this is zero, and then incremented on each call

Return value: The caption string to use

This function is called when the log file is being created. It gives the script an opportunity to add custom information to the log file about the left/source and/or right/destination locations.

Note that RunLogLocationInfoToAdd is called first, and then RunLogLocationInfoCaption() is called the appropriate number of times.

See RunLogLocationInfoToAdd for an example.

function RunLogLocationInfoInfo(Left, Cnt);

Left: True is this call is for information on the left/source

Cnt: On the first call this is zero, and then incremented on each call

Return value: The information string to use

This function is called when the log file is being created. It gives the script an opportunity to add custom information to the log file about the left/source and/or right/destination locations.

Note that RunLogLocationInfoToAdd is called first, and then RunLogLocationInfoInfo is called the appropriate number of times.

See RunLogLocationInfoToAdd for an example.

function RunLogLocationInfoToAdd(Left);

Left: True if this call is for information on the left/source

Return value: The number of caption/info calls to make

This function is called when the log file is being created. It gives the script an opportunity to add custom information to the log file about the left/source and/or right/destination locations.

Note that RunLogLocationInfoToAdd is called first, and then RunLogLocationInfoInfo is called the appropriate number of times.

function RunLogLocationInfoToAdd(Left);

begin

if Left then

Result:=2

else

Result:=0;

end;

function RunLogLocationInfoCaption(Left, Cnt);

begin

if Left then begin

if (Cnt = 0) then

Result:='Caption 1'

else

Result:='Caption 2';

end else

Resul:='';

end;

function RunLogLocationInfoInfo(Left, Cnt);

begin

if Left then begin

if (Cnt = 0) then

Resul:='Info 1'

else

Resul:='Info 2';

end else

Resul:='';

end;

function RunPreCopyCheck;

Return value: A reason why the script should not continue running

This function is called after the files and folders have been compared, and after the Differences window is displayed (if it is to be displayed). It is called before any files are copied, moved, deleted, or renamed, and gives the script a chance to abort the profile, e.g. the script may decide there is not enough free space to copy everything and so abort. If the script does not want the profile to run it should return the reason, otherwise it should return an empty string if the profile should continue.

function RunPreCopyCheck;

begin

if NotEnoughDiskSpace Then

Result:='There is not enough disk space'

else

Result:='';

end;

function RunRunAfterBefore(Filename);

Filename: The full filename and command line parameters of program to be called in Run After

Return value: The filename and command line parameters of program to be called in Run After

This function is called before the Run After program is called. It is passed the full and expanded filename (and any command line arguments) that are going to be used, which could be an empty string. This function can decide not to run the program (by returning an empty string) or it could change the string to have a different program be called. If it wants the same program to be called it should return what was passed in Filename.

function RunRunBeforeBefore(Filename);

Filename: The full filename and command line parameters of program to be called in Run Before

Return value: The filename and command line parameters of program to be called in Run Before

This function is called before the Run Before program is called. It is passed the full and expanded filename (and any command line arguments) that are going to be used, which could be an empty string. This function can decide not to run the program (by returning an empty string) or it could change the string to have a different program be called. If it wants the same program to be called it should return what was passed in Filename. If an empty string is returned then nothing is run and RunRunBeforeAfter will not be called.

function RunShowDiffWindow(WillShow);

WillShow: Is the Differences window going to be displayed?

Return value: True if the Differences window should be displayed

Should the Differences window be displayed? Note that this function is not called if the profile run is unattended. In such cases the Differences window is never displayed.

procedure InitialiseVars(Checking);

Checking: Passed as True if the variables are being checked to see if they exist

This subroutine is called when the variables are initialised. Checking is passed as FALSE. Note that you need to be careful as many things haven't been initialised or created when this is called, e.g. no locations. It is called very early during the profile run (it is called just after RunDisabledCheck is called).

If you are setting variables then it is recommended you also make your script a Configuration script. This is so the users can see which variables the script sets, and also they can use the variables, e.g. in the source or destination paths.

In the example below the variable MyScriptVar is set to a dummy value if it's a call to check if the variable is valid.

// Called very early when a profile is run (Checking is False)

// Also called in profile config when asking what variables the script sets (Checking is True)

procedure InitialiseVars(Checking);

begin

if Checking then begin

// Profile is being saved

SBVariables.SetVar('MyScriptVar', '?');

end else begin

// Profile is being run

// Do nothing

end;

procedure RunAfterConfig;

This function is called very early on in the profile run and gives the script a chance to do any early initialisation work. It is called before any attempt is made to connect to the left/source or destination/right. It is called after RunBeforeConfig and at this point the left/source folder is known, for example.

procedure RunAfterCopyFile(ToLeft, Filename, Failed);

ToLeft: True if the file was copied from the right/destination

Filename: The name of the file (not including the base path)

Failed: True if the copy failed

This function is called after a file has been copied. If Failed is True then either the copy failed or the user has aborted. Note that Failed being False does not necessarily mean the file was actually copied, i.e. it does not guarantee a file was created because the location may not actually copy the file, e.g. it may actually simply send it to a printer. What a script location does when it copies a file is beyond SyncBack's control.

This function is not called if the run is a simulation.

procedure RunAfterDeleteFile(Left, Filename, Failed);

Left: True if the left/source file was deleted

Filename: The name of the file (not including the base path)

Failed: True if the delete failed

This function is called after a file has been deleted. If Failed is True then either the delete failed or the user has aborted. Note that Failed being False does not necessarily mean the file was actually deleted, e.g. it may not have existed.

This function is not called if the run is a simulation.

Runtime Scripts

Runtime Scripts