SBSystem

<< Click to Display Table of Contents >>

Navigation:  Using SyncBackPro > Technical Reference > Scripting >

SBSystem

Previous pageReturn to chapter overviewNext page

 

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.

 

 

function CRC32(Filename);

 

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

 

 

function DecodeString(Str);

 

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

 

 

function DecryptString(Str);

 

Str: The string to decrypt

 

Return value: The decrypted string

 

This function decrypts a string that has been previously encrypted with the EncryptString function.

 

 

function EncodeString(Str);

 

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

 

 

function EncryptString(Str);

 

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 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

 

 

function GetProfileName(Idx);

 

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.

 

 

function GMTToLocal(GMTTime);

 

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.

 

 

function IsFolder(Filename);

 

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 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.

 

 

function LocalToGMT(GMTTime);

 

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.

 

 

function MD5(Filename);

 

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 CRC32

 

 

function OpenBrowser(URL);

 

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

 

 

function OpenFile(Filename);

 

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

 

 

function Ping(HostnameOrIP);

 

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);

 

 

function SHA1(Filename);

 

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 MD5

 

 

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

 

 

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 Say(ToSay);

 

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).

 

For example:

 

SBSystem.Say('2 bright sparks rock my world');

 

 

procedure Sleep(Seconds);

 

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

 

 

Property LanguageCode

 

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.

 

 

Property NoDesktop

 

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.

 

 

Property ProfileCount

 

This property returns the number of profiles. To retrieve the names of the profiles use GetProfileName

 

This is a read-only property.

 

 

Property SBCmdLineParamsCount

 

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.

 

 

Property SBFilename

 

This property returns the complete filename of the SyncBack program.

 

This is a read-only property.

 

 

Property ScriptFilename

 

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.

 

 

Property ScriptPath

 

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.

 

 

Property UniqueID

 

This property returns a universally unique 32 character long string.

 

This is a read-only property.

 

 

 

 

 

All Content: 2BrightSparks Pte Ltd © 2003-2017