Functions (W-Z)

The following chapter provides an overview of functions in alphabetic order from W to Z.

W

WriteCSV

Writes the data entered under values into a CSV file. This function is the reverse of ReadCSV().

WriteCSV(
 fileName,
 fieldSeparator,
 [rowSeparator,]
 [encoding],
 [isBOM],
 values
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the CSV file to be written. If the file already exists, it will be overwritten without notification.
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.
encoding	A string that contains the code page to be used. If this parameter is not set, UTF-8 is used.
isBOM	Indicates whether a BOM should be written into the file. If this is TRUE, a BOM is written.
values	A two-dimensional field that contains the strings to be written into the CSV file. The first dimension of the field (the first index) must contain the rows and the second dimension the columns: values[rows_nr][columns_nr]
Return	None.

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.

If values is passed as NULL, then an empty file is written. If individual values in the field values are NULL, these are replaced by an empty string.

WriteCSVFileStream

Creates a CSV file with data read from a two dimensional array.

WriteCSV(
 fileName,
 fieldSeparator,
 [rowSeparator,]
 values
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the CSV file to be written. If the file already exists, it will be overwritten without notification.
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.
values	A two-dimensional field that contains the strings to be written into the CSV file. The first dimension of the field (the first index) must contain the rows and the second dimension the columns: values[rows_nr][columns_nr]
Return	None.

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

WriteDB2Database

Executes an SQL statement on a database. The statement should return a value of the type integer as its result.

WriteDB2Database(
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 value of the type integer. For INSERT or UPDATE statements, this is the number of table rows affected. When calling a saved procedure, the result contains the return value of the procedure. When calling a stored procedure, the result contains the return value of the procedure.

WriteDB2Database() should not be used for SQL statements or saved procedures if these return a table structure. In this case, ReadDB2Database() is better suited.

If an SQL statement does not return a result, then WriteDB2Database() always returns 0.

If WriteDB2Database() is called with a connection string for which no OpenDB2Connection() was previously called, then every WriteDB2Database() 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.

WriteFile

Writes the specified text to the file with the specified name.

WriteFile(
filename,
text,
[encoding],
[isBOM]
)

This function consists of the following elements:

Element	Description
filename	A string that contains the name of the file in which the text is to be written.
text	A string that contains the text to be written.
encoding	A string that contains the code page to be used. If this parameter is not set, UTF-8 is used.
isBOM	Indicates whether a BOM should be written into the file. If this is TRUE, a BOM is written.
Return	None.

If the file with the specified filename already exists, it is overwritten without further confirmation. If the file does not exist, it is created.

If filename and/or encoding is passed as NULL, the function is terminated and an error message displays.

If text is passed as NULL, an empty file is written.

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

WriteFileStream

Appends content to the file with the specified name.

WriteFileStream(
filename,
text
)

This function consists of the following elements:

Element	Description
filename	A string that contains the path and name of the file in which the text is to be written.
text	A string that contains the text to be written.
Return	None.

If the file with the specified filename already exists, it is overwritten without further confirmation. If the file does not exist, it is created.

WriteHanaDatabase

Executes an SQL statement on a database. The statement should return a value of the type integer as its result.

WriteHanaDatabase(
	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 value of the type integer.

WriteHanaDatabase() should not be used for SQL statements or saved procedures if these return a table structure. In this case, ReadHanaDatabase() is better suited.

If an SQL statement does not return a result, then WriteHanaDatabase() always returns 0.

If WriteHanaDatabase() is called with a connection string for which no OpenHanaConnection() was previously called, then every WriteHanaDatabase() 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.

WriteLines

Writes the specified values line by line to the file with the specified name.

This function inserts a line feed in the file after each written value, so that each value appears in a separate line. A file that was created with WriteLines() can usually be read again with ReadLines().

WriteLines(
filename,
values,
[ci,]
[encoding],
[isBOM]
)

This function consists of the following elements:

Element	Description
filename	A string that contains the name of the file in which the values are to be written.
values	A field that contains the values to be written.
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 no culture information is passed or ci is passed as NULL, 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.
isBOM	Indicates whether a BOM should be written into the file. If this is TRUE, a BOM is written.
Return	None.

If the file specified in filename does not exist, it will be created.

If filename and/or encoding is passed as NULL, the function is terminated and an error message displays.

If text is passed as NULL, an empty file is written.

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

WriteLinesFileStream

Appends content to the specified file.

You have to open the file via OpenFileStream() and close it with CloseFileStream(). The lines written will be separated by the separator defined by the NEWLINE variable.

WriteLinesFileStream(
fileName,
lines
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the file in which the values are to be written.
lines	An array that contains the lines that will be appended to the specified file.
Return	None.

If the file specified in filename does not exist, it will be created.

The following example adds three lines to the test.txt file:

NEWLINE = NEWLINE_UNIX;
OpenFileStream("c:\temp\test.txt", FILEMODE_WRITE);
WriteLinesFileStream("c:\temp\test.txt", ["Line 1", "Line 2", "Line 3"]);
CloseFileStream("c:\temp\test.txt");

WriteMaskingStatus

Writes the status of the algorithms that the specified target uses into a file.

WriteMaskingStatus(
	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 written into. A relative path is treated to be relative to the current project's directory. If the specified file already exists, it is overwritten. This must not be NULL or empty.
target	A string that contains the ID of the target whose status you want to write. 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 write.
Return	None.

WriteOdbcDatabase

Executes an SQL statement on a database. The statement should return a value of the type integer as its result.

WriteOdbcDatabase(

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 value of the type integer. For INSERT or UPDATE statements, this is the number of the affected table rows. When calling a saved procedure, the result contains the return value of the procedure.

WriteOdbcDatabase() should not be used for SQL statements or saved procedures, if these return a table structure. In this case, ReadOdbcDatabase() is better suited.

If an SQL statement does not return a result, then WriteOdbcDatabase() returns always 0.

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

WriteOracleDatabase

Executes an SQL statement on a database. The statement should return a value of the type integer as its result.

WriteOracleDatabase(

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 value of the type integer. For INSERT or UPDATE statements, this is the number of the affected table rows. When calling a saved procedure, the result contains the return value of the procedure.

WriteOracleDatabase() should not be used for SQL statements or saved procedures, if these return a table structure. In this case, ReadOracleDatabase() is better suited.

If an SQL statement does not return a result, then WriteOracleDatabase() always returns 0.

If WriteOracleDatabase() is called with a connection string for which no OpenOracleConnection() was previously called, then every WriteOracleDatabase() 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.

WritePersistVars

This function writes the content of the specified persistent variables to the file with the specified name.

WritePersistVars(
filename,
ValueArray variables
)

This function consists of the following elements:

Element	Description
filename	A string that contains the name of the file to which the variables are to be saved. If the name is not absolute, it will be read relative to the project directory.
variables	A field of strings that contain the names of the variables to be saved.
Return	None.

The target file is an XML file with the following structure (elements in blue are variable):

<?xml version="1.0" encoding="utf-8" standalone="yes"?> 
A)	<persisted> 
B)		<variable name="Name" type="Type">Value</variable> 
	</persisted> 

Notes:

A) The root element has the name persisted. Under the root, there can be any number of variable elements.

B) For each persistent variable, there is one variable element. The name and the Tricentis TDM Studio data type of the variable are defined through attributes.

The value is not stored as an attribute, but as element content. This must always be formatted with an invariant culture such as English (US).

For the function to be used successfully, you must first perform a read-out with ReadPersistVars().

When writing, existing files are not updated, but replaced. This means that the file with the specified variable is created new and that any values which were already in the file and which belong to variables with other names, are deleted.

Should a system error occur, the exception is not captured but passed on unchanged to Tricentis TDM Studio.

WritePostgreSqlDatabase

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

WritePostgreSqlDatabase( 
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	An integer that contains the number of rows affected by the execution. When a stored procedure was called, the result contains the return value of the procedure.

WriteSQLiteDatabase

Executes an SQL statement on a database. The statement should return a value of the type integer as its result.

WriteSQLiteDatabase(

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 value of the type integer. For INSERT or UPDATE statements, this is the number of the affected table rows. When calling a saved procedure, the result contains the return value of the procedure.

WriteSQLiteDatabase() should not be used for SQL statements or saved procedures, if these return a table structure. In this case, ReadSQLiteDatabase() is better suited.

If an SQL statement does not return a result, then WriteSQLiteDatabase() always returns 0.

If WriteSQLiteDatabase() is called with a connection string for which no OpenSQLiteConnection() was previously called, then every WriteSQLiteDatabase() 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.

WriteSqlServerDatabase

Executes an SQL statement on an SQL Server database. The statement should return a value of the type integer as its result.

WriteSqlServerDatabase(

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 value of the type integer. For INSERT or UPDATE statements, this is the number of the affected table rows. When calling a saved procedure, the result contains the return value of the procedure.

WriteSqlServerDatabase() should not be used for SQL statements or saved procedures, if these return a table structure. In this case, ReadSqlServerDatabase() is better suited.

If an SQL statement does not return a result, then WriteSqlServerDatabase() returns always 0.

If WriteSqlServerDatabase() is called with a connection string for which no OpenSqlServerConnection() was previously called, then every WriteSqlServerDatabase() 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.

WriteWebSphereMQMessage

Writes the given message into the given queue.

WriteWebSphereMessage(
	queueName,
	messageString
)		

This function consists of the following elements:

Element	Description
queueName	A string with the name of the queue.
messageString	A string that contains the message.

Example:

1 WriteWebSphereMessage(
	"QUEUE1",
	"This is a Test Message”
);

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.

WriteXMLElements

Writes data to an XML file. The file must already exist - it will not be created.

WriteXMLElements(
fileName,
[Namespaces]
xPath,
values,
writeType,
randomize
)

This function consists of the following elements:

Element	Description
fileName	A string that contains the name of the XML file to be written to.
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 written.
values	Contains the values to be written. If this field is empty, nothing will be written. If values is passed as NULL, an empty file is generated. If individual values within the field are NULL, these are replaced by an empty string.
writeType	The content type to be written. This must be one of the constants defined in the table below.
randomize	If this is set to TRUE, the values from the values field are picked and written randomly. If the argument is FALSE, the values from values are processed sequentially. If values contains fewer values than there are elements to be written, processing is not aborted but starts again at the first value. If randomize is passed as NULL, then it is interpreted to have the value FALSE.
Return	None.

The following table contains the constants you can use for writeType:

Value	Constant	Meaning
0	WRITEXML_ATTR	Writes attribute values.
1	WRITEXML_TEXT	Writes text to the referenced elements. Special characters such as & or < are not masked.
2	WRITEXML_XML	Writes an XML structure to the referenced elements. Special characters such as & or < are not masked.

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

Y

Year

Returns the year from the specified date.

Year(
time
)

This function consists of the following elements:

Element	Description
time	A value with the data type time.
Return	The year, with the data type integer (1 – 9999).

Z

ZipCreateDir

Creates a new directory in an archive file.

ZipCreateDir(
zipFileName,
dirName
)

This function consists of the following elements:

Element	Description
zipFileName	A string that contains the file name of the archive to be edited. If the archive does not exist, it will be created automatically.
dirname	A string that contains the name of the directory to be created.
Return	None.

If zipFileName or dirName are passed as NULL, the function is terminated with an error message.

The same behavior occurs if dirName is passed as an empty string.

ZipExtract

Extracts all files and directories from the specified archive.

ZipExtract(
zipFileName,
targetPath,
overwriteFiles,
[password]
)

This function consists of the following elements:

Element	Description
zipFileName	A string that contains the file name of the archive.
targetPath	A string that contains the name of the directory into which the extracted files and directories will be copied.
overwriteFiles	A logical value that specifies whether any existing files in targetPath should be overwritten or not. If NULL is passed, this will be interpreted as FALSE.
password	A string that contains the password to decrypt the zip file. If you leave the password as NULL, the file is not decrypted. This parameter is optional.
Return	None.

If zipFileName and/or targetPath are passed as NULL, the function is terminated with an error message.

The same behavior occurs if targetPath is passed as an empty string.

ZipInsertDir

Copies the specified (file system) directory into the specified archive.

ZipInsertDir(
	zipFileName,
	dirName,
	[zipPath],
	[outputSegmentSize,
	password]
)

This function consists of the following elements:

Element	Description
zipFileName	A string that contains the name of the archive. If the archive does not exist, it will be created automatically.
dirname	A string that contains the name of the directory to be inserted.
zipPath	A string that contains the name of the directory in the archive, into which the dirName directory will be copied. If you do not enter a zipPath, the dirName directory will be copied into the root directory of the archive. If NULL is passed, this will be interpreted as an empty string.
outputSegmentSize	Splits the resulting ZIP file into several parts with the given size in Bytes if this is not NULL. The minimum size of a part is 65,536 Bytes.
password	The password to protect the resulting ZIP file. If this is NULL, the file is not protected.
Return	None.

If zipFileName and/or dirName are passed as NULL, the function is terminated with an error message.

ZipInsertFile

Copies the specified file into the specified archive.

ZipInsertFile(
	zipFileName,
	fileName,
	[zipPath],
	[outputSegmentSize,
	password]
)

This function consists of the following elements:

Element	Description
zipFileName	A string that contains the name of the archive. If the archive does not exist, it will be created automatically.
fileName	A string that contains the name of the file to be inserted.
zipPath	A string that contains the name of the directory in the archive into which the file will be copied. If you do not enter a zipPath, the file will be copied into the root directory of the archive. If NULL is passed, this will be interpreted as an empty string.
outputSegmentSize	Splits the resulting ZIP file into several parts with the given size in Bytes if this is not NULL. The minimum size of a part is 65,536 Bytes.
password	The password to protect the resulting ZIP file. If this is NULL, the file is not protected.
Return	None.

If zipFileName and/or dirName are passed as NULL, the function is terminated with an error message.

The same behavior occurs if an empty string is passed.

ZipInsertFiles

Copies the specified files into the specified archive.

ZipInsertFiles(
	zipFileName,
	fileNames,
	[zipPath],
	[outputSegmentSize,
	password]
)		

This function consists of the following elements:

Element	Description
zipFileName	A string that contains the name of the archive. If the archive does not exist, it will be created automatically.
fileNames	A field that contains the names of the files to be inserted.
zipPath	A string that contains the name of the directory in the archive into which the files will be copied. If you do not enter a zipPath, the files will be copied into the root directory of the archive. If NULL is passed, this will be interpreted as an empty string.
outputSegmentSize	Splits the resulting ZIP file into several parts with the given size in Bytes if this is not NULL. The minimum size of a part is 65,536 Bytes.
password	The password to protect the resulting ZIP file. If this is NULL, the file is not protected.
Return	None.

If zipFileName and/or dirName are passed as NULL, the function is terminated with an error message.

The same behavior occurs if an empty string is passed.