Functions (F-L)

The following chapter provides an overview of functions in alphabetic order from F to L.

F

FileExists

Checks whether the specified file exists.

FileExists( 
 name 
)

This function consists of the following elements:

Element	Description
name	A string that contains the name of the file.
Return	TRUE if the file exists, otherwise FALSE.

Floor

Returns a value that is rounded down to the next whole number.

Floor(
value
)

This function consists of the following elements:

Element	Description
value	A value of the type float.
Return	If value has no decimal places, value is returned. Otherwise, the next lower whole number is delivered. The result has the type integer.

Element

Description

value

A value of the type float.

Return

If value has no decimal places, value is returned. Otherwise, the next lower whole number is delivered.

The result has the type integer.

Format

This method uses the combined .NET formatting to convert the value of an object into its textual representation and to embed this representation in a string.

Format(
[ci,]
fmt,
arg,
[arg]...
)

This function consists of the following elements:

Element	Description
ci	Culture-specific information of the type culture. If this parameter is not set, then the current country settings of the operating system are used.
fmt	A string that contains the formatting string.
arg	The argument to be formatted. You can specify up to 6 arguments.
Return	The formatted result string of the type string.

The fmt parameter consists of none or more text sections which contain none or more indexed placeholders (formatting elements), each of which matches an object in the parameter list of this method. In the formatting process, each formatting element is replaced by the textual representation of the value of the matching object.

The syntax for formatting elements is as follows:

Syntax:

{Index[,Alignment][:Format]}

The curly brackets are mandatory. If you want to enter a single curly bracket as a literal in fmt, it needs to be doubled, i.e. {{ or }}.

Element	Description
Index	A zero-based integer that determines which element in an object list is to be formatted.
Alignment	An optional integer which specifies the minimum width of the area that contains the formatted value. If the length of the formatted value is smaller than Alignment, then the area is padded with spaces. If Alignment is negative, the formatted value in the area is left-aligned. If Alignment is positive, the formatted value in the area is right-aligned. If Alignment is not set, the length of the area is set to the length of the formatted value.
Format	An optional string with formatting identifiers. If Format is not set, a default format is used.

Element

Description

Index

A zero-based integer that determines which element in an object list is to be formatted.

Alignment

An optional integer which specifies the minimum width of the area that contains the formatted value.

If the length of the formatted value is smaller than Alignment, then the area is padded with spaces. If Alignment is negative, the formatted value in the area is left-aligned. If Alignment is positive, the formatted value in the area is right-aligned.

If Alignment is not set, the length of the area is set to the length of the formatted value.

Format

An optional string with formatting identifiers. If Format is not set, a default format is used.

If the value of fmt is Thank you for your purchase of {0:####} copies of Tricentis TDM Studio. and arg is a number with the value 123, the following is returned:

Thank you for your purchase of 123 copies of Tricentis TDM Studio.

If the value of fmt is My dog has {0,-8:G} fleas. and arg is a number with the value 42 , then the following is returned (spaces are shown as underscores):

My dog has 42______ fleas.

Please see msdn.microsoft.com/en-us/library/system.string.format(VS.80).aspx for detailed information about formatting.

FRand

Returns a random number.

FRand(
[min,
max]
)

This function consists of the following elements:

Element	Description
min	Defines the lower threshold of the range for the random number. If this argument is not set, 0 will be used as the lower threshold. If min is negative, then max can also be negative. If min is greater than max, then the values for min and max are swapped before a random number is generated.
max	Defines the upper threshold of the range for the random number. If this argument is not set, 1 will be used as the upper threshold. If min is greater than max, then the values for min and max are swapped before a random number is generated.
Return	A randomly generated number of the type float. The generated value is in the range [min – max].

Element

Description

min

Defines the lower threshold of the range for the random number. If this argument is not set, 0 will be used as the lower threshold.

If min is negative, then max can also be negative. If min is greater than max, then the values for min and max are swapped before a random number is generated.

max

Defines the upper threshold of the range for the random number. If this argument is not set, 1 will be used as the upper threshold.

If min is greater than max, then the values for min and max are swapped before a random number is generated.

Return

A randomly generated number of the type float. The generated value is in the range [min – max].

The returned value is a so-called pseudo-random number. This means that it is not actually random but generated.

Every subsequent call of FRand() returns a different value. Multiple calls return a sequence of values with an equal distribution within the range [min – max).

The RandSeed() function initializes the random number generator with a start value. An identical start value always generates the same sequence of random numbers.

Example:

Integer RandNum = FRand(-100.00, 500.00);

The value of the random number will be in the range between -100.0 and approximately 500 - 0,5 * 10-324.

FtpCreateDirectory

Creates a directory on a FTP server.

FtpCreateDirectory(
uri, 
username, 
password,
directoryName
)

This function consists of the following elements:

Element	Description
uri	A string with the network path of the directory to create. Must not be NULL or empty.
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
directoryName	A string with the name of the directory to create. Must not be NULL or empty.
Return	TRUE if the directory was created successfully, otherwise FALSE.

FtpDeleteDirectory

Deletes a directory from a FTP server.

FtpDeleteDirectory(
uri, 
username, 
password
)

This function consists of the following elements:

Element	Description
uri	A string with the network path of the directory to remove. Must not be NULL or empty.
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
Return	TRUE if the directory was deleted successfully, otherwise FALSE.

FtpDeleteFile

Removes a file from a FTP server.

FtpDeleteFile( 
uri, 
username, 
password 
)

This function consists of the following elements:

Element	Description
uri	A string with the network path of the file to remove. Must not be NULL or empty.
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
Return	TRUE if the file was removed successfully, otherwise FALSE.

FtpGetFile

Copies a file from a FTP server to a local destination.

FtpGetFile( 
username, 
password, 
ftpSourceFilePath, 
targetFile 
)

This function consists of the following elements:

Element	Description
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
sourcePath	A string with the URI of the source file. Must not be NULL or empty.
targetFile	A string with the path of the target file. Must not be NULL or empty.
Return	None.

FtpGetFileNames

Gets a list of file names from the FTP server.

FtpGetFileNames(
uri, 
username,
password
)

This function consists of the following elements:

Element	Description
uri	A string with the network path of the FTP server. Must not be NULL or empty.
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
Return	A list of file names from the specified directory.

FtpPutFile

Copies a file to the destination directory of the FTP server.

FtpPutFile( 
uri,
username,
password,
sourcePath
)

This function consists of the following elements:

Element	Description
uri	A string with the URI of the destination directory. Must not be NULL or empty.
username	A string that contains the user name to log in.
password	A string that contains the password of the user.
sourcePath	A string with the path of the file to copy. Must not be NULL or empty.
Return	TRUE if the data transfer was successful, otherwise FALSE.

G

GetEnvVar

Returns the value of the environment variable with the specified name.

GetEnvVar(
variableName,
)

This function consists of the following elements:

Element	Description
variableName	A string containing the name of the environment variable.
Return	A string containing the content of the environment variable. NULL is returned if the environment variable does not exist.

Example:

String winSystemRoot = GetEnvVar("SystemRoot");

Result:

"C:\Windows"

GetFileNames

Returns a field with all the files that the directory contains.

GetFileNames(
 dirName,
 recursive,
 [filter]
)

This function consists of the following elements:

Element	Description
dirName	A string that contains the path of the directory to be evaluated.
recursive	Determines whether the specified directory should be searched recursively.
filter	A string that contains a filter expression, according to which the found file names are filtered. The * character can be used as a wildcard.
Return	A one-dimensional field that contains all the file names found with their absolute paths.

The call returns all the files in the specified directory. This is located under the project directory.

Array FileNames = GetFileNames(#.\output#, false);

This call uses the filter parameter, so that only files with the extension .xml are returned.

Array FileNames = GetFileNames(#.\output#, false, "*.xml");

The next example returns all files that begin with Input. and have the extension .xls.

Array FileNames = GetFileNames(#.\output#, false, "Input.*.xls");

GetFileTimestamp

Returns the timestamp of a file.

GetFileTimestamp(
 filePath,
 attributeType        
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name and path of the file in question.
attributeType	A string that determines which timestamp should be returned. See the table below for constants.
Return	A date and a time of the type time. If the file does not exist, then FILETIME_INVALID is returned.

The following constants are defined for file times:

Value	Constant	Meaning
0	FILETIME_CREATED	Has the type time and contains the date and time of the file creation.
1	FILETIME_ACCESSED	Has the type time and contains the date and time of the last file access.
2	FILETIME_MODIFIED	Has the type time and contains the date and time of the last file modification.
01.01.1601 00:00:00	FILETIME_INVALID	The result that is returned when the specified file does not exist. The value shown here is in UTC. It will be calculated at runtime as local time, according to the configured time zone.

From Windows Vista onwards, the timestamp for the last file access is not updated any more. In this case it will be identical to the creation date.

Example:

time values = GetFileTimestamp(#@MISCDIR@\Datei.txt#, FILETIME_CREATED);

Trace(TRACELEVEL_INFO, values);

Return:

8/19/2014 11:12:28 AM

GetFileTimestamps

Returns all the timestamps of a file. This includes creation, last access and last modification.

GetFileTimestamps(
 filePath,
)

This function consists of the following elements:

Element	Description
filePath	A string that contains the name and path of the file in question.
Return	A field that contains the timestamps. The values can be extracted from the field using the constants listed in the table below. If the file does not exist, then the elements of the array show FILETIME_INVALID.

Element

Description

filePath

A string that contains the name and path of the file in question.

Return

A field that contains the timestamps. The values can be extracted from the field using the constants listed in the table below.

If the file does not exist, then the elements of the array show FILETIME_INVALID.

The following constants are defined for file times:

Value	Constant	Meaning
0	FILETIME_CREATED	Has the type time and contains the date and time of the file creation.
1	FILETIME_ACCESSED	Has the type time and contains the date and time of the last file access.
2	FILETIME_MODIFIED	Has the type time and contains the date and time of the last file modification.
01.01.1601 00:00:00	FILETIME_INVALID	The result that is returned when the specified file does not exist. The value shown here is in UTC. It will be calculated at runtime as local time, according to the configured time zone.

From Windows Vista onwards, the timestamp for the last file access is not updated any more. In this case it will be identical to the creation date.

Example:

Map timestamps = GetFileTimestamps(#@MISCDIR@\Datei.txt#);

Trace(TRACELEVEL_INFO, timestamps[FILETIME_CREATED]);

Return:

8/19/2014 11:12:28 AM

GetNumLines

Returns the number of lines in the specified file.

GetNumLines(
 filePath
)

This function consists of the following elements:

Element	Description
filePath	A string that contains the path of the file to be evaluated.
Return	An integer that represents the number of lines.

For instance, sample file Test.txt has the following content:

This is line 1

This is line 2

This is line 3

The following call evaluates the number of lines in the file Test.txt and returns this as a message:

Integer numberlines = GetNumLines("Test.txt");

Trace(TRACELEVEL_INFO, #Number of lines: @numberlines@#);

Return:

Number of lines: 3

Hour

Returns the hour from the specified time.

Hour(
time
)

This function consists of the following elements:

Element	Description
time	A time with the data type time.
Return	The hour, with the data type integer (0 – 23).

I

IIf

Checks the specified condition and returns a result of either trueValue or falseValue.

IIf(
condition,
trueValue,
falseValue
)

This function consists of the following elements:

Element	Description
condition	A logical value that contains the result of a condition.
trueValue	The value that will be returned if condition is TRUE. The type of this value must be the same as the type of falseValue.
falseValue	The value that will be returned if condition is FALSE. The type of this value must be the same as the type of trueValue.
Return	trueValue if condition is TRUE, otherwise falseValue. The return has the same type as trueValue and falseValue.

This function offers a shortcut for constructions like the following:

IF i < 5 THEN
         b = -1;
 ELSE
         b = 1;
 ENDIF

Among other things, this allows the use of conditions in text blocks:

data = #result: @IIf(i < 5, -1, 1)@#;

However, there is a difference between a condition with the conventional IF and the IIf function: In a conventional condition, only one block of statements will ever be executed, whereas with IIf, both statements are always executed.

Insert

Inserts element at the specified position into source, if source is a string or a field.

Inserts a new key-value pair into source, if source is an associative array.

Insert(
source,
[pos,
element]
[key,
value]
)

This function consists of the following elements:

Element	Description
source	The source into which element is inserted. This can be a string or a field. If this value is NULL, the function is terminated and an error message displayed.
pos	The zero-based index of the type integer at which element is inserted, if source is a field or a string. If this value is NULL, -1 or if it is greater or equal to the length of source, then element is appended to source.
element	If source is a string, then element must also be a string. If element is a field, then source can be a single value of any data type or another field. In this case, all elements contained in element are inserted into source.
key	The key to be inserted into source, if source is an associative array.
value	The value to be linked with key.
Return	If source is a string, then a string is returned. This string is a copy of source into which the characters contained in element have been inserted. If source is a field, then a field is returned. This field is a copy of source into which element has been inserted.

source is not modified by Insert(). Instead, a new string, field or associative array is generated which contains the new data.

InsertDatabaseRow

Inserts a record into an internal database table. The table must have been created in advance, for example using CreateSqlServerTable.

InsertDatabaseRow(
connectionString,
tableName,
values
)

This function consists of the following elements:

Element	Description
connectionString	A connection string that was used to create the table.
tableName	A string that contains the name of the database table.
values	A one-dimensional or associative field that contains the values to be inserted. The order of the columns is determined by the creation of the internal table.
Return	None.

Example:

string connectionString = "Server=1.2.3.4;User ID=user;Password=pwd";
OpenSqlServerConnection(connectionString);
Map newRow = CreateDB2Table(connectionString, "table", ["Vorname", "Nachname"]);
newRow["Vorname"] = "Alexander";
newRow["Nachname"] = "Maier";
InsertDatabaseRow(connectionString, "table", newRow);
BulkWriteSqlServerDatabase(connectionString, "table");

InsertRange

Inserts an element at the specified position into the source.

InsertRange(
source,
pos,
element
)

This function consists of the following elements:

Element	Description
source	The source into which element is inserted. This can be a string or a field. If this value is NULL, the function is terminated and an error message displayed.
pos	The zero-based index of the type integer at which element is inserted, if source is a field or a string. If this value is NULL, -1 or if it is greater or equal to the length of source, then element is appended to source.
element	If source is a field, then element can be a single value of any data type that is inserted into source. If element is a field, all elements contained therein are inserted into source.
Return	A field is returned which is a copy of source and into which element has been inserted.

source is not modified by InsertRange(). Instead, a new field is generated which contains element.

IsNULL

Determines whether the specified value contains a database NULL.

IsNULL(
value
)

This function consists of the following elements:

Element	Description
value	The value to be checked. This can be of any type.
Return	TRUE if value is NULL; otherwise FALSE is returned.

Example:

Boolean result = IsNULL(DBValue);

IsOfType

Checks if the specified value has the specified data type.

IsOfType(
value,
type
)

This function consists of the following elements:

Element	Description
value	The value to be checked.
type	One of the values from the table below.
Return	TRUE, if value is of the type type. Otherwise FALSE.

You can use one of the following values as type:

Value	Constant	Identified data type
1	TYPE_INTEGER	integer
2	TYPE_FLOAT	float
4	TYPE_BOOLEAN	boolean
8	TYPE_STRING	string
16	TYPE_TIME	time
32	TYPE_ARRAY	array
64	TYPE_CULTURE	culture

IsValidDate

Checks whether the specified values describe a valid date.

IsValidDate(
year,
month,
day
)

This function consists of the following elements:

Element	Description
year	The year. Data type is integer.
month	The month. Data type is integer.
day	The day. Data type is integer.
Return	TRUE, if year, month, and day form a valid date. Otherwise FALSE.

IsValidTime

Checks whether the specified values describe a valid time.

IsValidTime(
hour,
minute,
second,
[milliSecond]
)

This function consists of the following elements:

Element	Description
hour	The hour. Data type is integer.
minute	The minute. Data type is integer.
second	The second. Data type is integer.
milliSecond	The millisecond. Data type is integer.
Return	TRUE, if hour, minute, second, and milliSecond form a valid time. Otherwise FALSE.

J

Join

Joins several strings to a new string and separates them by using the specified separator character. This function is the reverse of the Split() function.

Join(
strings,
separator
)

This function consists of the following elements:

Element	Description
strings	A one-dimensional field that contains the strings to be joined.
separator	The character that will be used as a separator. If this field is empty, a semicolon will be used by default. If separator contains more than one character, only the first character will be used as the separator.
Return	A string that contains all the strings from strings, each separated by separator characters.

Element

Description

strings

A one-dimensional field that contains the strings to be joined.

separator

The character that will be used as a separator.

If this field is empty, a semicolon will be used by default. If separator contains more than one character, only the first character will be used as the separator.

Return

A string that contains all the strings from strings, each separated by separator characters.

K

Keys

Returns all keys of the associative array source.

Keys(
source
)

This function consists of the following elements:

Element	Description
source	An associative array, whose keys shall be returned.
Return	A field containing all keys of the associative array.

This example describes the usage of the function for a specific use case:

// Create the associative array and insert values:
Map m = CreateMap();
m = Insert(m,"Germany","Berlin");
m = Insert(m,"Austria","Wien");
m = Insert(m,"Spain","Madrid");
// Save all the keys in an array:
Array k = Keys(m);
// Output of one key-value:
Trace(TRACELEVEL_INFO, k[0]);	// In this specific case, the output is "Germany".

KeysAndValues

Returns all key-value pairs of the associative array as a two dimensional field.

KeysAndValues(
source
)

This function consists of the following elements:

Element	Description
source	The associative array, whose key-value pairs shall be returned.
Return	Two dimensional field containing all key-value pairs of source.

This example describes the usage of the function for a specific use case:

// Create an associative array and insert values:
Map m = CreateMap();
m = Insert(m,"Germany","Berlin");
m = Insert(m,"Austria","Wien");
m = Insert(m,"Spain","Madrid");
// Save the result in an array:
Array k = KeysAndValues(m);
// Output the key-value pairs as a test:
Trace(TRACELEVEL_INFO, k[0][0]);	// Returns "Germany" as key.
Trace(TRACELEVEL_INFO, k[0][1]);	// Returns "Berlin" as value.

L

LastDayOfMonth

Returns the specified time for which the day value is set to the last day of the respective month.

LastDayOfMonth(
time
)

This function consists of the following elements:

Element	Description
time	The time for which the day will be set to the last day of the respective month.
Return	The new time with the day set to the last day of the month.

Length

Returns the number of elements or characters contained in value.

Length(
value
)

This function consists of the following elements:

Element	Description
value	A string, or an associative array or a field. If value is NULL, then 0 is returned.
Return	If value is a string, the number of characters in the string is returned. If value is a field, the number of elements in the field is returned. If value is an associative array, the number of key-value pairs in value is returned. The returned value has the type integer.

Element

Description

value

A string, or an associative array or a field. If value is NULL, then 0 is returned.

Return

If value is a string, the number of characters in the string is returned.

If value is a field, the number of elements in the field is returned.

If value is an associative array, the number of key-value pairs in value is returned.

The returned value has the type integer.

Link

Gets a value from a field of a configured target.

This function is useful only in conjunction with a masking target configuration.

Link(
target,
field)

This function consists of the following elements:

Element	Description
target	A string that identifies the name of the target where to get the value from. This target must be configured by ConfigureTarget().
field	A string that identifies the name of the field where to get the value from.
Return	Link as a string.

Element

Description

target

A string that identifies the name of the target where to get the value from.

This target must be configured by ConfigureTarget().

field

A string that identifies the name of the field where to get the value from.

Return

Link as a string.

Example:

In this example, in the target T1 forename2 gets the same value as forename, and in target T2 email gets a local part that is built from the values used for forename and surname in T1.

string tc1 =#
forename = RSTRING, MASK:"A-Z", MAXLEN:10
forename2 = VALUE, VALUE:Dynamic(##Link("T1", "forename")##)
surname = RSTRING, MASK:"A-Z", MAXLEN:10
#;
 
string tc2 =#
email = MY_EMAIL, LOCAL:Dynamic(##Link("T1", "forename") + "." + Link("T1", "surname")##), MAXLEN:50
#;

Log

Returns the natural logarithm (based on e) of value.

Log(
value
)

This function consists of the following elements:

Element	Description
value	A value of the type integer or float.
Return	The natural logarithm of value. This value has the type float.

Log10

Returns the logarithm based on 10 of value.

Log10(

value

)

This function consists of the following elements:

Element	Description
value	A value of the type integer or float.
Return	The logarithm based on 10 of value. This value has the type float.

Lower

Converts all upper case letters in the specified string to lower case.

Lower(
str,
[ci]
)

This function consists of the following elements:

Element	Description
str	A string that contains the text to be converted.
ci	The culture-specific information to be used for recognizing which characters are to be converted. If this parameter is not set, then the current country settings of the operating system are used.
Return	A copy of str in which all letters appear in lower case.