|
<< Click to Display Table of Contents >> Navigation: Using SyncBackPro > Technical Reference > Scripting > SBSystem |
These are functions that can be accessed from scripts via the SBSystem object. For example:
SBSystem.Say('Hello');
The SBSystem object is accessible from any type of script.
All the example code below is written in using the Pascal scripting language.
function BuildDateTime(Day, Mon, Year, Hour, Min, Sec, MSec);
Day: Day of the month
Mon: Month of the year
Year: Year
Hour: Hour of the day (24-hour clock)
Min: Minute of the hour
Sec: Second of the minute
MSec: Milli-seconds of the second
Return value: A date & time value, or 1.0 if the parameters passed are invalid
This function builds a date & time that can be used with SyncBack, e.g. in the AddFile function. Note that the date variable type in VBScript is already compatible with SyncBack.
For example, for 24th June 1971 15:31:02.123 you would call:
BuildDateTime(24, 6, 1971, 15, 31, 02, 123);
function CheckNetworkDrive(UNCOrPath);
UNCOrPath: UNC path or drive path to check
Return value: An error message on failure
This function checks to see if a network drive can be reached. A UNC path, e.g. \\server\share\folder\, or networked drive path, e.g. Z:\, can be passed. If it can be reached then an empty string is returned, otherwise an error message is returned.
Note that Windows will use your current credentials to check the connection, so it will succeed even if you do not have access to the share, but it will fail if you don't have valid credentials on the remote computer.
To check if a computer can be reached (via its hostname or IP address) use the function Ping
function CompareFilenames(Filename1, Filename2, CaseSensitive);
Filename1: A Unicode filename to compare with Filename2
Filename2: A Unicode filename to compare with Filename1
CaseSensitive: TRUE if the comparison should be case sensitive
Return value: Returns zero if the strings are ordinally identical
This function compare two filenames for ordinal (not liguistic) equality. Digits in the strings are considered as numerical content rather than text. For performance reasons, if you are just testing for equality (or not) then use SameFilenames instead.
* Returns zero if the strings are identical.
* Returns > 0 if the string pointed to by Filename1 has a greater value than that pointed to by Filename2.
* Returns < 0 if the string pointed to by Filename1 has a lesser value than that pointed to by Filename2.
See also SameFilenames
function CompressFile(Filename);
Filename: The full filename of the file to compress
Return value: Returns error message on failure
This function compresses a file or folder using NTFS compression. If the file or folder is already compressed then no error is returned.
See also DecompressFile
function COMRegister(Filename);
Filename: Filename of the COM/OCX/ActiveX component to register
Return value: An error message on failure
This function registers an COM/OCX/ActiveX component (DLL or EXE). Note that typically the user must have Administrator privileges to register components. On success an empty string is returned, otherwise an error message is returned.
IMPORTANT: If SyncBack is configured not to register COM objects (see Global Settings) then it will not register the component and silently fail.
Filename: The filename of the file to calculate the hash value of
Return value: CRC32 hash value of the file, or empty string on failure
This function returns the CRC32 hash value of a file in string format. Note that it may take a long time to calculate the hash values of large files, or files accessed via a slow connection.
See also MD5
Return value: Seconds since January 1, 1970, 00:00:00
This function returns the number of seconds since January 1, 1970, 00:00:00
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
function DateTimeToUnixMS(Str);
Return value: Milli-seconds since January 1, 1970, 00:00:00
This function returns the number of milli-seconds since January 1, 1970, 00:00:00
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
Str: The string to decode
Return value: The decoded string
This function decodes a string that has been previously encoded with the EncodeString function.
function DecompressFile(Filename);
Filename: The full filename of the file to decompress
Return value: Returns error message on failure
This function decompresses an NTFS compressed file. If the file does not exist, or is not compressed, then no error message is returned. Note that it cannot decompress folders.
See also CompressFile
function DecryptFile(Filename);
Filename: The full filename of the file to decrypt
Return value: Returns error message on failure
This function decrypts an NTFS encrypted file. If the file does not exist, or is not encrypted, then no error message is returned. Note that it cannot decrypt folders.
See also EncryptFile
Str: The string to decrypt
Return value: The decrypted string
This function decrypts a string that has been previously encrypted with the EncryptString function.
Str: The string to encode
Return value: The encoded string
This function encodes a string so that it can safely be stored in INI files, the registry, etc. It is useful for when the string may contain characters that may be invalid for the storage medium.
See also DecodeString
function EncryptFile(Filename);
Filename: The full filename of the file to encrypt
Return value: Returns error message on failure
This function encrypts a file using NTFS encryption. If the file does not exist, or is already encrypted, then no error message is returned. If the file is compressed, EncryptFile will decompress the file before encrypting it. Note that it cannot encrypt folders.
See also DecryptFile
Str: The string to encrypt
Return value: The encrypted string
This function encrypts a string so that it is no longer plain text. Note that the encrypted string is formatted as a list of numbers (seperated by spaces). This means it can safely be stored in INI files, the registry, etc. so there is no need to use the EncodeString function.
See also DecryptString
function ExcludeTrailingBackslash(Filename);
Filename: The filename to remove the trailing backslash from
Return value: The filename with any trailing backslash removed
This function removes a trailing backslash from a filename, if there is one.
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
SBSystem.ExcludeTrailingBackslash('C:\abc\def\'); // Returns C:\abc\def
SBSystem.ExcludeTrailingBackslash('C:\abc\def'); // Returns C:\abc\def
function Exec(CmdLine, WaitSecs, var RetVal, var ErrMsg);
CmdLine: The full program name and parameters
WaitSecs: The number of seconds to wait
RetVal: The integer return value of the program executed
ErrMsg: An error message if the program could not be executed
Return value: Returns True if the program was executed
This function executes a program and optionally waits for it to complete.
CmdLine can contain command line parameters. It must be a fully qualified filename, e.g. C:\abc\def param1 param2
If WaitSecs < 0 then it will wait forever the program to finish
If WaitSecs = 0 then it will not wait for the program to finish
If WaitSecs > 0 then it will wait that number of seconds for it to finish
You need to wrap double quotes around the program name (no need if it does not contain spaces) otherwise the return value will always be 1. Also, command line parameters should be wrapped in double quotes if they contain spaces. For example:
"D:\Documents and Settings\Mick\Desktop\deldest.bat" param1 "param 2"
and NOT:
D:\Documents and Settings\Mick\Desktop\deldest.bat param1 param 2
CmdLine can be prefixed with special parameters:
/min to minimize the window (and not make it active)
/max to maximize the window
/hide to hide the window
e.g. /min "D:\Documents and Settings\Mick\Desktop\deldest.bat" "param 1"
If you choose to wait for the program to terminate then its return value is returned in RetVal. Otherwise the value in RetVal is unknown and should be ignored.
On failure ErrMsg will be set to an error message.
If the program was executed then True is returned. False is returned if the program could not be executed, e.g. doesn't exist. Note that True does not mean the program did what you required. To verify that check RetVal.
For example:
Executed:=SBSystem.Exec('C:\Windows\System32\Notepadx.exe', 0, RetVal, ErrMsg);
To view a web page use the function OpenBrowser, and to open a file use the function OpenFile
function GetNTFSSecurity(Filename, SecRequired, var NTFSSec);
Filename: The filename of the file to get the security details of
SecRequired: The NTFS security information required
NTFSSec: The NTFS security requested
Return value: An error message on failure
This function retrieves the NTFS security of a file in string format. To get the security of a folder the filename must include a trailing slash.
Note that you must have the required security privilelages to get the security for a file.
The SecRequired parameter specifies what security information you require:
OWNER_SECURITY_INFORMATION (1) Include the owner.
GROUP_SECURITY_INFORMATION (2) Include the primary group.
DACL_SECURITY_INFORMATION (4) Include the discretionary access control list (DACL).
SACL_SECURITY_INFORMATION (8) Include the system access control list (SACL).
LABEL_SECURITY_INFORMATION (16)
These values can be combined, e.g. OWNER_SECURITY_INFORMATION + GROUP_SECURITY_INFORMATION
Idx: The profile name to retrieve (first profile is zero)
Return value: The name of the profile, or empty string if there is no such profile
This function retrieves the name of a profile. To get the number of profiles use the ProfileCount property. Note that the first profile is zero (0), and the last is ProfileCount - 1
Note that you should call ProfileCount to refresh the list.
GMTTime: A date & time in the GMT/UTC timezone
Return value: A local date & time
This function convert a GMT/UTC date & time to a local date & time. The function LocalToGMT will convert a local date & time to a GMT/UTC date & time.
Filename: The filename to check
Return value: True if Filename has a trailing backslash
This function checks if a string has a trailing backslash, and if so, returns True. Note that the function does not check if the file or folder actually exists.
For example:
SBSystem.IsFolder('c:\abc\def');
will return False, but
SBSystem.IsFolder('c:\abc\def\');
will return True.
function ISO8601ToLocalDateTime(Str);
Str: ISO 8601 format string
Return value: Local date and time
This function converts an ISO 8601 format string to a local date and time.
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
procedure Test;
var
s: String;
dt: TDateTime;
begin
s:=SBSystem.UTCDateTimeToISO8601(SBSystem.LocalToGMT(Now), FALSE);
dt:=SBSystem.ISO8601ToLocalDateTime(s);
ShowMessage(DateTimeToStr(dt));
end;
function LanguageCode(DomainName, ToTranslate);
DomainName: The translation domain to use (use default for SyncBack translations)
ToTranslate: The string to translate
Return value: The translated string, or ToTranslate if it cannot be translated
This function translates a string from English to the current language, assuming a translation is available. See also AddTranslationDomain to add translations.
LocalTime: A date & time in the local timezone
Return value: A GMT/UTC date & time
This function convert a local date & time to a GMT/UTC date & time. The function GMTToLocal will convert a GMT/UTC date & time to a local date & time.
Filename: The filename of the file to calculate the hash value of
Return value: MD5 hash value of the file, or empty string on failure
This function returns the MD5 hash value of a file in string format. Note that it may take a long time to calculate the hash values of large files, or files accessed via a slow connection.
See also SHA1
URL: The URL of the web page to open in a browser
Return value: True if the browser was opened to display the web page
This function opens the default web browser and directs it to go to the URL given. Note that it returns True only if the browser is opened, but it cannot know if the URL itself is valid or accessible.
For example:
SBSystem.OpenBrowser('http://www.2BrightSparks.com/');
To open a file use the function OpenFile
To check if a server can be reached use the function Ping
Filename: The complete filename of the file to open
Return value: An error message of failure, else an empty string
This function opens a file, e.g. a text document, with the default program for that file type, e.g. Notepad. Note that it returns an empty string only if the appropriate program was opened, but it cannot know if the file itself was opened by the program.
For example:
SBSystem.OpenFile('c:\folder\file.txt');
On failure an error message is returned.
To open a web page use the function OpenBrowser
HostnameOrIP: An I.P. address or hostname
Return value: An error message on failure
This function 'pings' a server to see if it is accessible. Note that some servers do not respond to ping requests (e.g. at time of writing microsoft.com does not). If the server responds to the ping requests then an empty string is returned, otherwise an error message is returned.
For example:
SBSystem.Ping('google.com');
To check if a network drive is accessible use the function CheckNetworkDrive
function SameFilenames(Filename1, Filename2, CaseSensitive);
Filename1: A Unicode filename to compare with Filename2
Filename2: A Unicode filename to compare with Filename1
CaseSensitive: TRUE if the comparison should be case sensitive
Return value: Returns TRUE if the strings are ordinally identical
This function compare two filenames for ordinal (not liguistic) equality. Digits in the strings are considered as numerical content rather than text.
See also CompareFilenames
function SBCmdLineParam(ParamIdx);
ParamIdx: The command line parameter to retrieve (first param is zero)
Return value: The command line parameter, or empty string if there is no such parameter
This function retrieves the command line parameters passed to SyncBack. To get the number of parameters use the SBCmdLineParamsCount property. Note that the first parameter is zero (0), and the last is SBCmdLineParamsCount - 1
function SBVersion(Filename, var Major, var Minor, var Release, var Build);
Filename: The filename of an executable, or an empty string for SyncBack
Major: The major version number of the executable
Minor: The minor version number of the executable
Release: The release version number of the executable
Build: The build version number of the executable
Return value: If an empty filename was passed then the name SyncBack is using
This function gets the version information from an executable. If Filename is passed as an empty string then it will return the version information of SyncBack itself. Also, passing an empty string will return the application name of SyncBack. In some situations SyncBack may be branded under a different name. If a filename is passed then the filename itself (stripped of the path) is returned.
For example:
AppName:=SBSystem.SBVersion(Filename, Major, Minor, Release, Build);
function SetCreateDateTime(Filename, LocalDateTime);
Filename: Complete filename of the file to change the creation date & time of
LocalDateTime: The local date & time to change the creation date & time to
Return value: An error message on failure
This function sets the creation date & time of a file to the one supplied. The filename must be a complete filename, and the date & time should be in the local timezone. It returns an error message on failure.
For example:
SBSystem.SetCreateDateTime('c:\folder\file.txt;, Now);
function SetFileAttributes(Filename, Attribs);
Filename: Complete filename of the file to change the attributes of
Attribs: The attributes to use
Return value: An error message on failure
This function sets the Windows file attributes of file. The filename must be a complete filename. It returns an error message on failure.
For example:
SBSystem.SetFileAttributes('c:\folder\file.txt', FILE_ATTRIBUTE_READONLY);
function SetLastModDateTime(Filename, LocalDateTime);
Filename: Complete filename of the file to change the modification date & time of
LocalDateTime: The local date & time to change the modification date & time to
Return value: An error message on failure
This function sets the last modification date & time of a file to the one supplied. The filename must be a complete filename, and the date & time should be in the local timezone. It returns an error message on failure.
For example:
SBSystem.SetLastModDateTime('c:\folder\file.txt', Now);
function SetNTFSSecurity(Filename, SecRequired, NTFSSec);
Filename: Complete filename of the file to change the NTFS security of
SecRequired: The security information to set
NTFSSec: The NTFS security in string format
Return value: An error message on failure
This function sets the NTFS security of a file to the one supplied. The filename must be a complete filename, and the NTFS security should be in string format. It returns an error message on failure.
Note that you must have the required security privilelages to set the security of a file.
To set the security of a folder the filename must include a trailing slash.
The SecRequired parameter specifies what security information you require:
OWNER_SECURITY_INFORMATION (1) Include the owner.
GROUP_SECURITY_INFORMATION (2) Include the primary group.
DACL_SECURITY_INFORMATION (4) Include the discretionary access control list (DACL).
SACL_SECURITY_INFORMATION (8) Include the system access control list (SACL).
LABEL_SECURITY_INFORMATION (16)
These values can be combined, e.g. OWNER_SECURITY_INFORMATION + GROUP_SECURITY_INFORMATION
For example:
SBSystem.SetNTFSSecurity('c:\folder\file.txt', OWNER_SECURITY_INFORMATION + GROUP_SECURITY_INFORMATION, NTFSSec);
Filename: The filename of the file to calculate the hash value of
Return value: SHA1 hash value of the file, or empty string on failure
This function returns the SHA1 hash value of a file in string format. Note that it may take a long time to calculate the hash values of large files, or files accessed via a slow connection.
See also SHA256
Filename: The filename of the file to calculate the hash value of
Return value: SHA256 hash value of the file, or empty string on failure
This function returns the SHA256 hash value of a file in string format. Note that it may take a long time to calculate the hash values of large files, or files accessed via a slow connection.
See also CRC32
Filename: The filename of the file to calculate the hash value of
Return value: SHA512 hash value of the file, or empty string on failure
This function returns the SHA512 hash value of a file in string format. Note that it may take a long time to calculate the hash values of large files, or files accessed via a slow connection.
See also SHA256
function ToDaysHoursMinsSecs(Seconds, SecondsString, MinutesString, HoursString, DaysString, NoSecsIfHours);
Seconds: The number of seconds to convert
SecondsString: The string to use for seconds, e.g. 'secs.'
MinutesString: The string to use for minutes, e.g. 'mins.'
HoursString: The string to use for hours, e.g. 'hours'
DaysString: The string to use for days, e.g. 'days'
NoSecsIfHours: If passed as TRUE then if there is more than on hour then skip showing the remaining seconds
Return value: The string representation of the seconds
Given a number of seconds, this function returns it broken down into days, hours, minutes, etc.
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
SBSystem.ToDaysHoursMinsSecs(123456, 'secs', 'mins', 'hrs', 'days', TRUE); // Returns '1 days 10 hrs 17 mins'
SBSystem.ToDaysHoursMinsSecs(123456, 'secs', 'mins', 'hrs', 'days', TRUE); // Returns '1 days 10 hrs 17 mins 36 secs'
function UpdateFileStatus(Status);
Status: The file status message to display in the SyncBack main window
Return value: True if the profile is terminating
This function updates the current file status shown in the SyncBack main window. Note that SyncBack itself will display the appropriate status messages when files are being copied, deleted, etc. The current file status message is the message displayed below the current status messages.
For example:
SBSystem.UpdateFileStatus('Taking the stereo from your car...');
See also UpdateStatus
function UpdateStatus(Status);
Status: The status message to display in the SyncBack main window
Return value: True if the profile is terminating
This function updates the current status shown in the SyncBack main window. Note that SyncBack itself will display the appropriate status messages when tasks are being performed, e.g. Scanning for changes. The status message is the message displayed above the current file status message.
For example:
SBSystem.UpdateStatus('Taking your dog for a walk...');
See also UpdateFileStatus
function UTCDateTimeToISO8601(UTCDateTime, DropMills);
UTCDateTime: The UTC/GMT date & time
DropMills: If TRUE the milli-seconds are ignored
Return value: ISO 8601 format string
This function converts a UTC/GMT date & time into an ISO 8601 format string.
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
SBSystem.ShowMessage(SBSystem.UTCDateTimeToISO8601(Now, FALSE)); // 2022-09-16T11:42:14.406Z
procedure AddTranslationDomain(DomainName);
DomainName: The name of the translation domain
This function adds a custom translation domain so that a script can provide its own translations for strings. Strings are translated using TranslateString.
A domain is the name of a .MO translation file (without the .MO extension). The .MO file must be placed into the appropriate \locale\[language code]\LC_MESSAGES\ sub-folders of the SyncBack installation folder. There should be a .MO file for each language that strings can be translated into. MO files are created using the freeware POEdit program.
See the TranslationExample.vbs for an example.
procedure BetweenDates(Date1, Date2, var days, var hours, var mins, var secs);
Date1: The first date
Date2: The second date
days: Set to the number of days between the dates
hours: Set to the number of hours between the dates
mins: Set to the number of minutes between the dates
secs: Set to the number of seconds between the dates
This function calculates the time between two dates.
Important: This function is only available when using Pascal or Basic scripting and is not available with VBScript etc.
procedure Test;
var d1, d2: TDateTime;
d, h, m, s: Integer;
begin
d:=0;
h:=0;
m:=0;
s:=0;
d1:=EncodeDate(2022, 06, 24) + EncodeTime(9, 10, 11, 12);
d2:=EncodeDate(2021, 03, 12) + EncodeTime(22, 0, 15, 0);
SBSystem.BetweenDates(d1, d2, d, h, m, s);
// 468 days 11 hours 9 mins 56 seconds
SBSystem.ShowMessage(IntToStr(d) + ' days ' + IntToStr(h) + ' hours ' + IntToStr(m) + ' mins ' + IntToStr(s) + ' seconds');
end;
ToSay: What the computer should say, or the filename of a .WAV file
This subroutine uses the speech engine in Windows to have the computer say what you request. It can also be used to play .WAV files (by passing the filename). However, if used in a profile, and Azure Speech is used in that profile, then the voice set in the profile is used with Azure Speech.
For example:
SBSystem.Say('2 bright sparks rock my world');
procedure SayBing(ToSay, Voice);
ToSay: What the computer should say
Voice: Which voice to use (TBingVoice)
This subroutine uses the Azure Speech cloud service to have the computer say what you request.
For example:
SBSystem.SayBing('2 bright sparks rock my world', bv_EnglishBritainFemale);
procedure ShowMessage(Message);
Message: Message to display
This function is the same as the global ShowMessage method except it will not display the message if it is not acceptable to do so, e.g. there is no user interface, the profile is being run unattended, etc.
Seconds: The number of seconds to sleep
This function sleeps for the specified number of seconds. Note that you should not sleep for more than a few seconds in case the user wants to abort. The script (and profile or anything else) cannot abort while sleeping.
For example:
SBSystem.Sleep(2);
See also SBRunning.Sleep
This property returns the language code of the user interface, e.g. 'en' for English. See also AddTranslationDomain and TranslateString
This is a read-only property.
This property returns True if there is a desktop. It would return False, for example, if no user is currently interactively logged in, or if a different user is currently interactively logged in.
This is a read-only property.
This property returns the number of profiles. To retrieve the names of the profiles use GetProfileName
This is a read-only property.
This property returns the number of command line parameters passed to SyncBack. The parameters themselves can be retrieved using the SBCmdLineParam function.
This is a read-only property.
This property returns the complete filename of the SyncBack program.
This is a read-only property.
This property returns the complete filename of the script itself. This should not be stored as it may change, e.g. if imported onto another computer then the path may be different. To get just the path the script is in use ScriptPath
This is a read-only property.
This property returns the path (directory) the script itself is in. This should not be stored as it may change, e.g. if imported onto another computer then the path may be different. To get the complete filename of the script use the function ScriptFilename
This is a read-only property.
This property returns a universally unique 32 character long string.
This is a read-only property.
All Content: 2BrightSparks Pte Ltd © 2003-2024