Functions (R-V)

The following chapter provides an overview of functions in alphabetic order from R to V.

R

Rand

Returns a random number.

Rand(
[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 min is not set and this value is smaller than 1, then the function always returns the value 0. 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 integer. The generated value will be 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 min is not set and this value is smaller than 1, then the function always returns the value 0.

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 integer. The generated value will be 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 Rand() returns a different value. Multiple calls return a sequence of values with an even distribution in the range [min - max].

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

In this example, the value of the random number will be in the range between -100 and 499 inclusive.

Integer RandNum = Rand(-100, 500);

RandSeed

Initializes the random number generator.

RandSeed(
seed
)

This function consists of the following elements:

Element	Description
seed	The start value. Data type is integer.
Return	None.

If the random number generator is initialized with a particular number before the processing of tasks (e.g. in the task variables), then the functions Rand(), FRand(), DRand() and SRand() always generate the same number of random numbers.

In order to generate different sequences every time the task is executed, RandSeed() should be initialized with the start value 0. In this case, the system time is used as the start value.

ReadCSV

Reads a CSV file into a multidimensional field. This function is the reverse of WriteCSV().

ReadCSV(
 fileName,
 fieldSeparator,
 [rowSeparator,]
 hasHeader,
 [encoding]
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the CSV file to be read.
fieldSeparator	The character that is used as a field separator in the CSV file. If an empty string is passed, the function converts this into a semicolon ; as the field separator.
rowSeparator	The string that is used as a row separator in the CSV file. If this argument is not set, the string for a line feed on the system that Tricentis TDM Studio runs under will be used. Under Windows, this is a combination of a carriage return and a line feed character.
hasHeader	Specifies whether the CSV file has a header that should be read. If the parameter is not passed or passed as NULL, the header is also read by default.
encoding	A string that contains the code page to be used. If this parameter is not set, UTF-8 is used.
Return	A two-dimensional field of strings that contains all the rows and fields in the CSV file. Empty rows in the CSV file are ignored in the read process, and they are not present in the result.

The result is a two-dimensional field, the first dimension of which contains the rows. If, for example, you wanted to access the content of the first column in the third row, the result would have to be indicated as follows:

Array csv = ReadCSV("data.csv", ";", FALSE, "windows-1252");

string z3s1 = csv[2][0];

The code page string is one of the names registered for code pages under IANA.org.

If fileName or encoding is passed as NULL, the execution of the function is terminated and an error message displays.

If fieldSeparator is passed as NULL, the behavior is the same as when an empty string is passed.

If rowSeparator is passed as NULL, the behavior is the same as when rowSeparator is not passed at all.

ReadCSVFileStream

Creates an array with data read from a specified CSV file. The file has to be opened with OpenFile and closed with CloseFile.

ReadCSV(
 fileName,
 fieldSeparator,
 [rowSeparator,]
 hasHeader,
 ignoreFirstLine, 
numberOfLines
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the CSV file to be read.
fieldSeparator	A string that is used as a field separator in the CSV file. If an empty string or NULL is passed, the function converts this into a semicolon ; as the field separator.
rowSeparator	A string that is used as a row separator in the CSV file. If this argument is not set, the string for a line feed on the system that Tricentis TDM Studio runs under is used. Under Windows, this is a combination of a carriage return and a line feed character.
ignoreFirstLine	A boolean that specifies whether the CSV file has a header row. If the parameter is set to true, the header row is not imported into the array.
numberOfLines	A string that contains the number of lines to read from.
Return	A two-dimensional field of strings that contains all the rows and fields in the CSV file. Empty rows in the CSV file are ignored in the read process, and they are not present in the result.

ReadDatabaseRow

Retrieves a record from the reader for the query.

ReadDatabaseRow(
connectionString,
statement
)

This function consists of the following elements:

Element

Description

connectionString

A string in which the connection string for the database connection is specified.

If this is NULL, processing terminates with an error message.

statement

A string that contains the SQL statement to be executed.

If this is NULL, processing terminates with an error message.

Return

A field that contains the returned data. If no reader was opened, then an empty field is returned.

ReadDatabaseRows

Retrieves a specified number of records from the reader for the query.

ReadDatabaseRows(
connectionString,
statement,
recordCount
)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified. If this is NULL, processing terminates with an error message.
statement	A string that contains the SQL statement to be executed. If this is NULL, processing terminates with an error message.
recordCount	An integer that specifies the number of records to be retrieved.
Return	A field that contains the returned data. If no reader was opened, then an empty field is returned.

ReadDB2Database

Executes an SQL statement on a DB2 database. The statement returns a table structure as its result.

ReadDB2Database(
connectionString,
statement
)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadDB2Database() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadDB2Database():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

If we further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadDB2Database(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
endfor

If ReadDB2Database() is called with a connection string for which no OpenDB2Connection() was previously called, then every ReadDB2Database() call implicitly creates a new connection (and also closes it again). The DB2 connection pool may impose restrictions with regard to the maximum number of DB2 connections.

The functions for DB2 databases are not included in projects by default. They are provided in the installation directory and can be added to a given project as an external function directory.

ReadFile

Reads the content of the file with the specified name.

ReadFile( 
 filename, 
 [encoding]
)

This function consists of the following elements:

Element	Description
filename	A string that contains the name of the file to be read.
encoding	A string that contains the code page to be used. If this parameter is not set, UTF-8 is used.
Return	A string that contains the content of the specified file.

The code page string is one of the names registered for code pages under IANA.org.

ReadHanaDatabase

Executes an SQL statement on a Hana database. The statement returns a table structure as its result.

ReadHanaDatabase(
	connectionString,
	statement
)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadHanaDatabase() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadHanaDatabase():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

If we further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadHanaDatabase(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
endfor

If ReadHanaDatabase() is called with a connection string for which no OpenHanaConnection() was previously called, then every ReadHanaDatabase() call implicitly creates a new connection (and also closes it again). The Hana connection pool may impose restrictions with regard to the maximum number of Hana connections.

The functions for Hana databases are not included in projects by default. They are provided in the installation directory and can be added to a given project as an external function directory.

ReadLines

Reads the content of the file with the specified name line by line.

ReadLines( 
 filename, 
 valueType, 
 [ci,]
 [encoding]
)

This function consists of the following elements:

Element	Description
filename	A string that contains the name of the file to be read.
valueType	The data type into which the read lines will be converted. Possible entries of the type integer are shown in the table below.
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.
encoding	A string that contains the code page to be used. If this parameter is not set, UTF-8 is used.
Return	A field that contains the lines that were read. The data type of the elements in the field depends on valueType.

You can use the following settings for ReadLines():

Value	Constant	Result data type
0	READ_INTEGER	integer
1	READ_FLOAT	float
2	READ_BOOLEAN	boolean
3	READ_TIME	time
4	READ_STRING	string

This function reads a file line by line. By definition, a line is a string of characters that ends with a carriage return (\r), a line feed (\n), or a carriage return followed by a line feed.

The code page string is one of the names registered for code pages under IANA.org.

ReadLinesFileStream

Reads a number of lines from the specified file.

ReadLinesFileStream( 
 filename, 
 numlines 
)

This function consists of the following elements:

Element	Description
filename	A string that contains the path and name of the file to be read.
numlines	A string that contains the number of lines to read from the file. When you set this parameter to -1, all lines of the file are read.
Return	An array containing one line per field.

Element

Description

filename

A string that contains the path and name of the file to be read.

numlines

A string that contains the number of lines to read from the file.

When you set this parameter to -1, all lines of the file are read.

Return

An array containing one line per field.

ReadMaskingStatus

Restores a target's status, which you have written into a file with WriteMaskingStatus().

ReadMaskingStatus(
	filePath,
	target,
	[variables])

This function consists of the following elements:

Element	Description
filePath	A string with the path to the file that the status is read from. A relative path is treated to be relative to the current project's directory. This must not be NULL or empty.
target	A string that contains the ID of the target whose status you want to restore. This is the same ID as the one that was specified by a previous call to ConfigureTarget(). This must not be NULL or empty.
variables	An array of strings that contain the names of the variables to read.
Return	None.

ReadOdbcDatabase

Executes an SQL statement on a database. The statement should have a table structure as its result.

ReadOdbcDatabase(

connectionString,

statement

)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadOdbcDatabase() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadOdbcDatabase():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

Let us further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadOdbcDatabase(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
Endfor

Every call to ReadODBCDatabase() with a connection string not already passed to OpenODBCConnection() results in an opening of a new connection which is closed within ReadODBCDatabase(). There might be limitations for the number of connections originating from the ODBC-connection pooling.

ReadOracleDatabase

Executes an SQL statement on an Oracle database. The statement returns a table structure as its result.

ReadOracleDatabase(

connectionString,

statement

)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadOracleDatabase() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadOracleDatabase():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

If we further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadOracleDatabase(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
endfor

If ReadOracleDatabase() is called with a connection string for which no OpenOracleConnection() was previously called, then every ReadOracleDatabase() call implicitly creates a new connection (and also closes it again). The Oracle connection pool may impose restrictions with regard to the maximum number of Oracle connections.

The functions for Oracle databases are not included in projects by default. They are provided in the installation directory and can be added to a given project as an external function directory.

ReadPersistVars

This function reads the variable values in the specified file and assigns them to the specified variables.

ReadPersistVars(
fileName,
ValueArray variables
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the file from which the variable values will be read. If the name is not absolute, it will be read relative to the project directory.
variables	A field of strings which contains the names of the variables to be set.
Return	None.

Element

Description

fileName

A string that contains the name of the file from which the variable values will be read.

If the name is not absolute, it will be read relative to the project directory.

variables

A field of strings which contains the names of the variables to be set.

Return

None.

If a variable is not found in the file, then this variable will not be modified. In this case a trace message is issued as a warning. The same applies if the file does not exist or the file format is incorrect (e.g. root element is not called persisted or file does not contain valid XML).

Another call of the function is not possible without writing first with WritePersistVars(). Otherwise, the processing is terminated with an error message.

ReadPostgreSqlDatabase

Opens a new PostgreSQL connection and executes an SQL statement for reading. Only new connections are closed.

 ReadPostgreSqlDatabase( 
connectionString,
statement,
[timeout]
)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
timeout	An integer that specifies the timeout value in seconds. If you don't specify any value, the query times out after 30 seconds.
Return	Contains an array of the read table rows, or no result if no lines were read.

ReadSAPTable

Reads SAP tables via a generic user function.

ReadSAPTable(
	connectionString,
	[protocol,]
	tableName,
	columns,
	[filter,]
	[numRecords]
)

This function consists of the following elements:

Element	Description
connectionString	A string that contains the connection used to connect to SAP. This is the same as the values in a previous call to OpenSAPConnection().
protocol	An integer value that indicates the protocol to use. If no value is specified, the system uses SAP_RFC. The valid values are: SAP_RFC: uses the classical RFC protocol to open a SAP connection (librfc32.dll). SAP_NWRFC: uses the Netweaver protocol to open a SAP connection. This argument is ignored if a connection for the specified connection string is already established via OpenSAPConnection() and not closed yet. If no connection is currently open, this function opens a temporary connection that uses the specified protocol.
tableName	A string that contains the name of the SAP table to read. If this is NULL, empty, or the table does not exist, the function exits with an error.
columns	An array that contains strings with the names of the columns to read. If this is NULL, empty, or if one of the columns does not exist, the function exits with an error.
filter	A string that contains the filter to use. The syntax of the filter is similar to SQL. If this is NULL or empty, no filter is used.
numRecords	The maximum number of records to return. If this is less than 1, all available records that match the filter (if specified) are returned.
Returns	A 2-dimensional array that contains all read records of the specified table that matches the filter (if specified). The returned array is empty if no record matches the filter (if specified) or if the table is empty. The sequence of read values in the returned array is identical to the sequence of columns specified in columns.

The following example reads 10 rows from the specified columns of the specified table with the specified filter and writes the lines into the log:

string myConnectionString = "...";
array result = ReadSAPTable(myConnectionString, "MAKT", "MATNR", "MAKTX", "SPRAS = 'EN'", 10);

for integer i = 0 to Length(result) - 1 do
	array line = result[i];
	Trace(TRACELEVEL_INFO, Format("MATNR: {0}, MAKTX: {1}", line[0], line[1]);
endfor

ReadSQLiteDatabase

Executes an SQL statement on an SQLite database. The statement returns a table structure as its result.

ReadSQLiteDatabase(

connectionString,

statement

)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadSQLiteDatabase() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadSQLiteDatabase():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

If we further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadSQLiteDatabase(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
endfor

If ReadSQLiteDatabase() is called with a connection string for which no OpenSQLiteConnection() was previously called, then every ReadSQLiteDatabase() call implicitly creates a new connection (and also closes it again). The SQLite connection pool may impose restrictions with regard to the maximum number of SQLite connections.

ReadSqlServerDatabase

Executes an SQL statement on an SQL Server database. The statement should have a table structure as its result.

ReadSqlServerDatabase(

connectionString,

statement

)

This function consists of the following elements:

Element	Description
connectionString	A string in which the connection string for the database connection is specified.
statement	A string that contains the SQL statement to be executed.
Return	A two-dimensional field that contains the returned table rows.

ReadSqlServerDatabase() always returns a field as its result. If the SQL statement returns an empty table, then the result is a field which has no elements (the function Length() returns 0).

For each row returned by the SQL statement, the resulting field contains a further element of the type array. This contains the result columns.

Let us assume, for example, that the following SQL statement is executed via ReadSqlServerDatabase():

SELECT PK_ID, NAME FROM NAMETABLE

This returns a field, the second dimension of which contains two elements each.

Let us further assume that two numbers are returned, then the column contents of these rows can be accessed as follows (assuming that PK_ID returns an integer and NAME returns a string):

array result = ReadSqlServerDatabase(conString, sqlStatement);
for integer i = 0 to Length(result) do
	Trace(TRACELEVEL_INFO, Format("PK_ID: {0}", result[i][0]));
	Trace(TRACELEVEL_INFO, Format("NAME: {0}", result[i][1]));
Endfor

If ReadSqlServerDatabase() is called with a connection string for which no OpenSqlServerConnection() was previously called, then every ReadSqlServerDatabase() call implicitly creates a new connection (and also closes it again). The SQL Server connection pool may impose restrictions with regard to the maximum number of SQL Server connections.

ReadWebSphereMQMessage

Reads a message from the given queue.

ReadWebsphereMessage(
	queueName
)

This function consists of the following element:

Element	Description
queueName	A string with the name of the queue.

Example:

1 String Message = ReadWebsphereMessage("QUEUE1");

The Websphere MQ functions are not included in projects by default. They are provided in the installation directory and can be added to a given project as an external function directory.

ReadXMLAttributes

Gets a map that contains the attributes as name-value-pairs of the nodes that are specified in xPath.

ReadXMLAttributes(
fileName,
[Namespaces]
xPath
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the XML file to read.
namespaces	An array with the namespaces to define. Each entry has to be a string in the format prefix=namespace. The prefix is the prefix that is used in xPath. No namespaces will be defined if this is empty or NULL.
xPath	A string that contains the XPath to identify the nodes where to get the attributes from.
Return	A map that contains the names and values of the read attributes.

This function terminates with an error if an invalid value or NULL is passed for fileName or xPath.

ReadXMLElements

Reads data from an XML file.

ReadXMLElements(
fileName,
[Namespaces]
xPath,
readType
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the XML file to be read.
namespaces	An array with the namespaces to define. Each entry has to be a string in the format prefix=namespace. The prefix is the prefix that is used in xPath. No namespaces will be defined if this is empty or NULL.
xPath	A string that contains the XPath expression that specifies the elements to be read.
readType	The content type to be read. This must be one of the constants defined in the table below.
Return	A field that contains the read-in values as strings. The content of the strings depends on the data that were read and the setting for readType. If xPath refers to a single element, then the result contains exactly one string. If xPath references several elements, then the result contains the contents of all found elements. If no elements are found, then the result is empty (a field of the length 0).

You can define one of the following constants for readType:

Value	Constant	Meaning
0	READXML_ATTR	Reads attribute values.
1	READXML_TEXT	Reads the contents of the referenced elements as text. In the course of this, masks such as & or < are converted to their original characters.
2	READXML_XML	Reads the contents of the referenced elements as an internal XML structure. Masks such as & or < are not converted to their original characters.

This function terminates with an error if an invalid value or NULL is passed for fileName, xPath, and/or readType.

ReceiveMessage

ReceiveMessage(
path,
wait
)

This function consists of the following elements:

Element	Description
path	A string that contains the name of the message queue from which a message will be read.
wait	A Boolean value that specifies whether the system should wait for a message or not. If the parameter is set to TRUE, then the function blocks processing until a message is available.
Return	A string which contains the message that was read. This is empty if the message was empty or if no message was received.

Names of message queues are described under the function CreateMessageQueue().

Remove

Removes the specified number of elements from source, if source is a field or string.

Removes the association with the specified key, if source is an associative array.

Remove(
source,
[pos,
count]
[key]
)

This function consists of the following elements:

Element	Description
source	A string or a field from which elements are to be removed.
pos	A value of the type integer which contains the zero-based index within source, starting from which elements will be removed, if source is a field or a string. If this value is smaller than 0 or greater than/equal to the length of source, then an unchanged copy of source is returned.
count	A value of the type integer that sets the number of elements to be removed. If this value is smaller than -1, or if pos + count is greater than the length of source, then all elements starting from pos are removed.
key	The key of the association, which should be removed from source, if source is an associative array.
Return	A copy of source in which the specified number of elements may have been removed. If source or one of the other parameters (if specified) contain the value NULL, then source returns the original value.

Replace

Replaces all occurrences of what with with in source.

Replace(
source,
what,
with
)

This function consists of the following elements:

Element	Description
source	A string or a field in which elements are to be replaced.
what	The elements which will be replaced. If source is a field, then this is a single value of any type. If source is a string, then this must also be a string.
with	The replacement elements. If source is a field, then this is a single value of any type. If source is a string, then this must also be a string.
Return	A copy of source in which all elements that match what have been replaced by with. If source has the value NULL, the original value is returned.

ResetDataPool

Resets the data pool that is identified by the specified ID.

Once you have configured a data pool, each call to Mask() gets the same data from the pool. To get new data from the pool, you need to call ResetDataPool() from a template. This is not necessary if you use the default SQLite pool (POOL_STD_SQLITE) with AUTORESET set to TRUE.

ResetDataPool(
	configId,
	[filter])

This function consists of the following elements:

Element	Description
configId	A string that contains the ID that identifies the configured pool to reset. This is the same value that was given to ConfigureDataPool() as second argument. This must not be NULL or empty.
filter	A string that contains an additional filter to use. The next provided record matches this filter. The syntax of the filter depends on the used pool. For POOL_STD_SQLITE the filter must be a SQL expression that is valid for SQLite databases but without the introductory WHERE clause. If this parameter is NULL or empty, no additional filter is used.
Return	None.

Element

Description

configId

A string that contains the ID that identifies the configured pool to reset.

This is the same value that was given to ConfigureDataPool() as second argument.

This must not be NULL or empty.

filter

A string that contains an additional filter to use. The next provided record matches this filter.

The syntax of the filter depends on the used pool. For POOL_STD_SQLITE the filter must be a SQL expression that is valid for SQLite databases but without the introductory WHERE clause.

If this parameter is NULL or empty, no additional filter is used.

Return

None.

Root

Calculates the root of value.

Root(
value,
root
)

This function consists of the following elements:

Element	Description
value	A value of the type integer or float for which the root is to be calculated.
root	A value of the type integer or float that specifies the root to be calculated.
Return	The root of value, with the type float.

Round

Rounds the specified value to the given number of digits.

Round(
value,
[digits]
)

This function consists of the following elements:

Element	Description
value	A value of the type float that is to be rounded.
digits	Number of decimal places in the range between 0 and 15 that the value should be rounded to. If this argument is not set, 0 will be used. If the value is outside the range, it is automatically adjusted so that it falls into the range.
Return	A value of the type float that was rounded up or down.

Element

Description

value

A value of the type float that is to be rounded.

digits

Number of decimal places in the range between 0 and 15 that the value should be rounded to.

If this argument is not set, 0 will be used. If the value is outside the range, it is automatically adjusted so that it falls into the range.

Return

A value of the type float that was rounded up or down.

Example:

Float f = Round(1.234567, 3);

Trace(TRACELEVEL_INFO, f);

Return:

1.235

S

Second

Returns the second from the specified time.

Second(
time
)

This function consists of the following elements:

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

SendMessage

Writes a message to the message queue with the specified name.

SendMessage(
path,
message
)

This function consists of the following elements:

Element	Description
path	A string that contains the name of the message queue into which a message will be written.
message	A string which contains the message to be written.
Return	None.

Names of message queues are described under the function CreateMessageQueue().

Sin

Returns the sine of the specified angle. This function is the reverse of the function ArcSin().

Sin(
value
)

This function consists of the following elements:

Element	Description
value	An angle in degrees of the type integer or float.
Return	The sine of value.

Split

Splits a string into individual parts which are separated by the selected separator character. This function is the reverse of the function Join().

Split(
text,
separator
)

This function consists of the following elements:

Element	Description
text	A string that contains the text to be separated.
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 field that contains the different components of text.

Element

Description

text

A string that contains the text to be separated.

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 field that contains the different components of text.

Sqrt

Returns the square root of the specified value.

Sqrt(
value
)

This function consists of the following elements:

Element	Description
value	A number of the type float.
Return	The square root of value. The result has the type float.

SRand

Generates a string of random length that consists of randomly selected characters.

SRand(
[minLength,]
maxLength,
mask
)

This function consists of the following elements:

Element	Description
minLength	A value of the type integer which specifies the minimum length for the generated string. If this parameter is not set, the minimal length of 0 is used.
maxLength	A value of the type integer which specifies the maximum length for the generated string.
mask	A string which contains a mask that defines the allowed characters in the generated string. The mask is of the same kind as the one passed to MkSet() to generate a set of characters.
Return	A string with a randomly generated length in the range [minLength – maxLength] that contains randomly selected characters from the character set defined by mask.

The returned string is a so-called pseudo-random string. This means that the string is not actually random, but generated.

Every subsequent call of SRand() returns a different value.

The random number generator is initialized with a start value by the function RandSeed(). An identical start value always generates the same sequence of strings.

StartProcess

Starts the program with the name specified in cmd.

StartProcess(
cmd,
[args,]
[wait,
[silent]]
)

This function consists of the following elements:

Element	Description
cmd	The name of the program to be executed. If the name does not contain a path, then the specified program must be in the current working directory or in one of the directories defined in the environment variable PATH.
args	Optional command line arguments that will be passed to the program. If this argument is not specified, no arguments are passed to the process.
wait	A Boolean value that specifies whether to wait until the termination of the specified program before it is started. If this is set to TRUE, then StartProcess() blocks processing until the program is terminated. If this argument is not specified, there is no waiting time for the process.
silent	A truth value that specifies whether the application is started in the background (i.e. without opening a window). If this argument is not set, no window will be suppressed.
Return	The result of the type integer that the executed program has returned. If wait is set to FALSE, then the result is always 0.

Str

Converts the specified value to a string. This function is the reverse of MkTime() for a time.

Str(
value,
[format,]
[ci]
)

This function consists of the following elements:

Element	Description
value	The value to be converted. It can have any data type.
format	An optional formatting specification. This is the same kind of specification that is used after the colon in the function Format(). If the parameter is not set, a default format is used. This is dependent on the culture-specific information specified in ci. The same behavior occurs if format is passed as NULL.
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. If ci is passed as NULL, the current country setting of the operating system is used.
Return	A string that contains the formatted value. If value is passed as NULL, an empty string is returned.

SubStr

Extracts part of the specified string.

SubStr(
source,
start,
count
)

This function consists of the following elements:

Element	Description
source	A string from which a part is to be extracted.
start	The zero-based index of the type integer of the first character to be extracted. If this value is smaller than 0 or greater than/equal to the length of source, then an empty string is returned.
count	The number of characters to be extracted, with the type integer. If this value is -1 or if start + count is greater than the length of the string, then the whole string starting from the index pos is returned.
Return	A string that contains the extracted characters.

T

Tan

Returns the tangent of the specified angle. This function is the reverse of the function ArcTan()

Tan(
value
)

This function consists of the following elements:

Element	Description
value	An angle in degrees of the type integer or float.
Return	The tangent of value.

ToscaTDSAddData

To add a single record to the Tosca Test Data Service, use the function as follows:

ToscaTDSAddData(
uri,
category,
consumed,
datamap
[token]
)

This function consists of the following elements:

Element	Description
uri	A string with the full URI of the Tosca TDS. Must not be null or empty.
category	A string with the name of the TDS category that the data should be added to. Must not be null or empty.
consumed	A boolean value that defines whether the data should be marked as consumed.
datamap	A map of string key value pairs, that hold the data to be added. The keys are the column names of the targeted TDS, the values are the respective values that are added in the new TDS record. Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	A string that contains the unique identifier of the inserted record.

To add multiple records to the Tosca Test Data Service, use the function as follows:

ToscaTDSAddData(
uri,
category,
consumed,
data
[token]
)

This function consists of the following elements:

Element	Description
uri	A string with the full URI of the Tosca TDS. Must not be null or empty.
category	A string with the name of the TDS category that the data should be added to. Must not be null or empty.
consumed	A boolean value that defines whether the data should be marked as consumed.
data	An array of maps of string key value pairs, that hold the data to be added. The keys are the column names of the targeted TDS, the values are the respective values that are added in the new TDS record. Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	An array of strings that contain the unique identifiers of the inserted records in the same order in which the records are specified in data.

ToscaTDSChangeData

Changes a data record that already exists in the Tosca Test Data Service.

ToscaTDSChangeData(
uri,
category,
id,
consumed,
datamap
[token]
)

Element	Description
uri	A string with the full URI of the Tosca TDS. Must not be null or empty.
category	A string with the name of the TDS category the data should be added to. Must not be null or empty.
id	A string that contains the ID of the record you want to change. Must not be null or empty.
consumed	A boolean value that defines whether the data should be marked as consumed or not.
datamap	A map of string key value pairs that hold the data you want to add. The keys are the column names of the targeted TDS. The values are the values that are added in the new TDS record. Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.

ToscaTDSConsumeData

Consumes a data record in a Tosca Test Data Service.

ToscaTDSConsumeData( 
uri, 
category, 
[filterOrId]
[token]
)

Element	Description
uri	A string with the full URI of the Tosca Test Data Service. Must not be null or empty.
category	A string with the name of the TDS category that contains the record. Must not be null or empty.
filterOrId	A string with a filter or identifier that indicates which function you want to call. Possible values: ID: use the universally unique identifier (UUID) to identify a record and consume it Filter: use a MongoDB like filter query that narrows down the data area of the record, e.g. "{'FirstName' : 'John'}", "{'value' : {'$gt' : '123456'}}". Null: consume the last record within the given category
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	An array of maps with all retrieved data. If a request returns no result, the function returns an empty array.

ToscaTDSConsumeDataWithToken

Sets the Consume attribute on the records in a specified category in Tosca Test Data Service.

ToscaTDSConsumeDataWithToken( 
uri, 
category 
token
)

Element	Description
uri	A string with the full URI of the Tosca Test Data Service. Must not be null or empty.
category	A string with the name of the TDS category that contains the record(s). Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token.
Return	An array of maps. The keys are the column names of the targeted Tosca Test Data Service. The values are the values that are set to be consumed in the specified Tosca Test Data Service category. If a request returns no result, the function returns an empty array.

ToscaTDSCreateRepository

To simply create a repository in Tosca Test Data Service, use the function as follows:.

ToscaTDSCreateRepository( 
uri, 
name, 
location,  
type
[link]
[token]
)

Element	Description
uri	A string with the full URI of the Tosca Test Data Service. Must not be null or empty.
name	A string that contains the name of the new repository. Must not be null or empty.
location	A string that defines the location of the new repository. The default path is %PROGRAMDATA%\Tricentis\TestDataService[REPOSITORYNAME].db. You must enter a valid path depending on the repository type: If you use SQLite, ensure that the path is valid and ends with the extension .db. If you use InMemory, the path has to end with the [REPOSITORYNAME] which matches the parameter name. A full location is not required, just enter the name of the repository.
type	Enter a number that defines the repository type. Enter one of the following values: 1: uses SQLite, the repository is persistent 0: uses InMemory, the repository is not available after a restart Must not be null or empty.
link	Optionally, enter the direct link to the repository in the format http://host:port/testservice.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	None.

To create a repository in Tosca Test Data Service including a description, use the function as follows:.

ToscaTDSCreateRepository( 
uri, 
name, 
location, 
description, 
type
[link]
[token]
)

Element	Description
uri	A string with the full URI of the Tosca Test Data Service. Must not be null or empty.
name	A string that contains the name of the new repository. Must not be null or empty.
location	A string that defines the location of the new repository. The default path is %PROGRAMDATA%\Tricentis\TestDataService[REPOSITORYNAME].db. You must enter a valid path depending on the repository type: If you use SQLite, ensure that the path is valid and ends with the extension .db. If you use InMemory, the path has to end with the [REPOSITORYNAME] which matches the parameter name. A full location is not required, just enter the name of the repository.
description	A string with a description of the new repository.
type	Enter a number that defines the repository type. Enter one of the following values: 1: uses SQLite, the repository is persistent 0: uses InMemory, the repository is not available after a restart Must not be null or empty.
link	Optionally, enter the direct link to the repository in the format http://host:port/testservice.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	None.

ToscaTDSDeleteCategory

Deletes a category from a Tosca Test Data Service repository.

ToscaTDSDeleteCategory( 
uri, 
category
{{[ignoreErrorNotExist]}}
[token]
)

Element	Description
uri	A string that contains the URI of the Tosca Test Data Service. Must not be null or empty.
category	A string that contains the category that you want to remove. Must not be null or empty.
ignoreErrorNotExist	Set this parameter to true, to ignore 404 errors that indicate a non-existent repository. The default value is false.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	None.

ToscaTDSDeleteData

Removes an existing data record from a Tosca Test Data Service repository.

ToscaTDSDeleteData(
uri,
category,
id
[token]
)

Element	Description
uri	A string that contains the URL of the repository that you want to remove the record from. Must not be null or empty.
category	A string that contains the category that you want to remove the record from. Must not be null or empty.
id	A string that contains the ID of the record you want to change. Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.

ToscaTDSDeleteRepository

Completely removes a repository from a Tosca Test Data Service. The function first deletes the data stored in the repository and then the repository itself.

ToscaTDSDeleteRepository( 
uri, 
name
[ignoreErrorRepoNotExist]
[token]
)

Element	Description
uri	A string with the URI of the Tosca Test Data Service. Must not be null or empty.
name	A string that contains the name of the repository. Must not be null or empty.
ignoreErrorRepoNotExist	Set this parameter to true, to ignore 404 errors that indicate a non-existent repository. The default value is false.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	None.

ToscaTDSEmptyRepository

Deletes all records and categories in a Tosca Test Data Service repository. The repository remains for future use.

ToscaTDSEmptyRepository( 
uri, 
name
[token]
)

Element	Description
uri	A string with the URI of the Tosca Test Data Service. Must not be null or empty.
name	A string that contains the name of the repository. Must not be null or empty.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	None.

ToscaTDSGetData

Gets data from a specific Tosca Test Data Service category.

ToscaTDSGetData(
uri, 
category, 
(id,|
considerConsumedObjects, 
[limit], 
[offset], 
[filter]
[token]
)

Element	Description
uri	A string with the full URI of the Tosca Test Data Service. Must not be null or empty.
category	A string that contains the category that you want to get the record from. Must not be null or empty.
id	The universally unique identifier (UUID).
considerConsumedObjects	Indicates if the function returns a consumed record. Set the parameter to true to return a consumed object.
limit	A limit for the amount of returned data. Enter a value greater than 0. This parameter is optional. If you set no limit, the system gets all available data.
offset	The offset from which you want to start. Enter a value that is equal to or greater than 0. The default value is 0. This parameter is optional.
filter	A string that contains the filter to use. The syntax of the filter is similar to MongoDB, e.g. "{'FirstName' : 'John'}", "{'value' : {'$gt' : '123456'}}". This parameter is optional.
token	A string that contains the Tosca Test Data Service authentication token. This parameter is optional.
Return	An array of maps with all retrieved data. If a request returns no result, the function returns an empty array.

TotalDays

Returns the number of days between time1 and time2. If time2 is not set, 01/01/0001 00:00:00.000 is used.

TotalDays(
time1,
[time2]
)

This function consists of the following elements:

Element	Description
time1	A time value of the type time.
time2	A time value of the type time. If this value is missing, 01/01/0001 00:00:00.000 is used.
Return	A value of the type float that shows the number of days. Negative values are possible.

Example 1:

Time time1 = MkTime(10, 00, 12, 354);

TRACE(TRACELEVEL_INFO, TotalDays(time1));

Return:

0,416809652777778

Example 2:

Time time1 = MkTime(2001, 01, 03, 10, 00, 00);

Time time2 = AddDays(time1, 2);

TRACE(TRACELEVEL_INFO, TotalDays(time1, time2));

Return:

TotalHours

Returns the number of hours between time1 and time2. If time2 is not set, 01/01/0001 00:00:00.000 is used.

TotalHours(
time1,
[time2]
)

This function consists of the following elements:

Element	Description
time1	A time value of the type time.
time2	A time value of the type time. If this value is missing, 01/01/0001 00:00:00.000 is used.
Return	A value of the type float that shows the number of hours. Negative values are possible.

Example 1:

Time time1 = MkTime(10, 30, 00);

TRACE(TRACELEVEL_INFO, TotalHours(time1));

Return:

10,5

Example 2:

Time time1 = MkTime(2001, 01, 03, 00, 00, 00);

Time time2 = MkTime(2001, 01, 05, 12, 00, 00);

TRACE(TRACELEVEL_INFO, TotalHours(time1, time2));

Return:

TotalMilliseconds

Returns the number of milliseconds between time1 and time2. If time2 is not set, 01/01/0001 00:00:00.000 is used.

TotalMilliseconds(

time1,

[time2]

)

This function consists of the following elements:

Element	Description
time1	A time value of the type time.
time2	A time value of the type time. If this value is missing, 01/01/0001 00:00:00.000 is used.
Return	A value of the type float that shows the number of milliseconds. Negative values are possible.

Example 1:

Time time1 = MkTime(00, 30, 30, 003);

TRACE(TRACELEVEL_INFO, TotalMilliseconds(time1));

Return:

1830003

Example 2:

Time time1 = MkTime(2001, 01, 03, 00, 30, 30, 003);

Time time2 = AddMilliseconds(zeit1, 300);

TRACE(TRACELEVEL_INFO, TotalMilliseconds(time1, time2));

Return:

300

TotalMinutes

Returns the number of minutes between time1 and time2. If time2 is not set, 01/01/0001 00:00:00.000 is used.

TotalMinutes(

time1,

[time2]

)

This function consists of the following elements:

Element	Description
time1	A time value of the type time.
time2	A time value of the type time. If this value is missing, 01/01/0001 00:00:00.000 is used.
Return	A value of the type float that shows the number of minutes. Negative values are possible.

Example 1:

Time time1 = MkTime(01, 30, 30);

TRACE(TRACELEVEL_INFO, TotalMinutes(time1));

Return:

90,5

Example 2:

Time time1 = MkTime(00, 30, 30);

Time time2 = MkTime(03, 00, 30);

TRACE(TRACELEVEL_INFO, TotalMinutes(time1, time2));

Return:

150

TotalSeconds

Returns the number of seconds between time1 and time2. If time2 is not set, 01/01/0001 00:00:00.000 is used.

TotalSeconds(

time1,

[time2]

)

This function consists of the following elements:

Element	Description
time1	A time value of the type time.
time2	A time value of the type time. If this value is missing, 01/01/0001 00:00:00.000 is used.
Return	A value of the type float that shows the number of seconds. Negative values are possible.

Example 1:

Time time1 = MkTime(00, 00, 30, 500);

TRACE(TRACELEVEL_INFO, TotalSeconds(time1));

Return:

30,5

Example 2:

Time time1 = MkTime(00, 00, 30);

Time time2 = MkTime(00, 30, 30);

TRACE(TRACELEVEL_INFO, TotalSeconds(time1, time2));

Return:

1800

Trace

Writes the specified message to the active logs.

Trace(
level,
value
)

This function consists of the following elements:

Element

Description

level

The error level of the message. Possible error levels that can be issued are:

TRACELEVEL_ERROR
TRACELEVEL_WARNING
TRACELEVEL_INFO
TRACELEVEL_DEBUG1
TRACELEVEL_DEBUG2
TRACELEVEL_DEBUG3

value

Any value that contains the message to be output.

Return

None.

The error level determines whether the message is output or not. Which messages are written to which logs is specified in the options (see chapter "Generation / Tracing").

Trim

Removes all spaces from the beginning and/or the end of the specified string. Apart from spaces, any non-printing characters such as line feeds or tabs are also removed.

Trim(
str,
where
)

This function consists of the following elements:

Element

Description

str

A string from which leading and/or trailing spaces are to be removed.

where

The position at which spaces are to be removed. The possible values for this parameter are:

TRIM_START: removes all spaces from the beginning of the string
TRIM_END: removes all spaces from the end of the string
TRIM_BOTH: removes all spaces from the beginning and the end of the string

Return

A string that contains a copy of str in which any spaces have been removed, starting at the position specified in where.

U

UniqueFileName

Generates a file name that is unique within the specified directory.

UniqueFileName( 
 path, 
 fileName 
)

This function consists of the following elements:

Element	Description
path	A string that contains the directory within which the file name has to be unique.
filename	A string that contains the file name to be made unique.
Return	A string that contains a file name which is unique in the directory specified in path.

If the specified directory already contains a file with the name specified in filename, then an incremental number is added to filename until the filename is unique.

If path or fileName are passed as NULL, the function call is terminated and an error message displays.

UpdateConsistencyDatabase

To change the values of a complete target in the target's consistency database, use the following function.

UpdateConsistencyDatabase(
	target,
	targetId,
	values)

Element	Description
target	A string that contains the ID of the target whose values you want to change. This is the same that was specified via ConfigureTarget(). This must not be NULL or empty.
targetId	A string that contains the ID of the record whose values you want to change. This is the same that was used in a previous call of Mask(). This must not be NULL or empty.
values	A map of strings that contains the names of the fields (the keys) and the values (values) to write. This map should be the result of a previous call to Mask(). This must not be NULL.
Return	None.

To change the value of a specified field in the target's consistency database, use the following function.

UpdateConsistencyDatabase(
	target,
	field,
	orgValue,
	newValue)

Element	Description
target	A string that contains the ID of the target whose values you want to change. This is the same that was specified via ConfigureTarget(). This must not be NULL or empty.
field	A string that contains the field of the target you want to change. This must not be NULL or empty.
orgValue	The original value of any type. This must be the same as the original value that was given to a previous call Mask(). This must not be NULL.
newValue	A string that contains the new value you want to write into the consistency database.
Return	None.

Upper

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

Upper(
str,
[ci]
)

This function consists of the following elements:

Element

Description

str

A string that contains the text to be converted.

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

V

Val

Converts the specified string into a number. This function is the reverse of Str() for a number.

Val(
number,
[ci]
)

This function consists of the following elements:

Element

Description

number

A string that contains a sequence of digits to be converted to a number.

Culture-specific information of the type culture.

If this parameter is not set, then the current country settings of the operating system are used.

If no culture information is passed or ci is passed as NULL, the current country settings of the operating system are used.

Return

If the string specified in number contains a decimal separator, then the returned number has the type float. Otherwise it has the type integer.

If number is passed as NULL, the function is terminated and an exception is thrown.

ValidXML

Checks an XML file for a match with an XSD file.

ValidXML(
 xmlFileName,
 xsdFileNames
)

This function consists of the following elements:

Element	Description
xmlFileName	A string that contains the name of the XML file to be checked.
xsdFileNames	An array of strings that contains the names of the XSD files to use for validation.
Return	TRUE, if the content of the specified XML file matches the schemes in the specified XSD files. Otherwise FALSE.

If xmlFileName is passed as NULL, the execution of the function is terminated and an error message displays. If the field xsdFileNames contains NULL values, these will be ignored.

Values

Returns all values of the associative array source.

Values(
source
)

This function consists of the following elements:

Element	Description
source	Associative array whose values will be returned.
Return	An array with all values of the associative array.

This example describes the use of the Values function:

// Create associative array and fill with values:
Map m = CreateMap();
m = Insert(m,"Germany","Berlin");
m = Insert(m,"Austria","Wien");
m = Insert(m,"Spain","Madrid");
// Save all values in an array:
Array k = Values(m);
// Output of a value:
Trace(TRACELEVEL_INFO, k[0]);	// In this case the output will be "Berlin"

VarExists

Checks whether a variable with the specified name has already been defined.

VarExists(
name,
global
)

This function consists of the following elements:

Element

Description

name

A string that contains the name of the variable whose existence which will be checked.

global

A Boolean value that specifies the area for the variable check.

If this value is TRUE, then only globally defined variables are searched (project or task variables that were not defined with private, or variables in templates that were defined with public).

If the value is FALSE, then variables that are only valid in the current area are also searched.

Return

TRUE, if the variable is defined in the specified area. Otherwise FALSE.

The function VarExists() can be used to prevent a template from trying to access an as of yet undefined variable.

Let us assume, for example, that a template is used in more than one task. Let us further assume that the variable specialHandling is defined in some but not all of these tasks. In this case, you could add the following condition to the template to ensure that it can be used in all tasks:

	if VarExists("specialHandling") then
		// Insert the special handling here.
	endif