Other functions

All database functions require an ID (connectionId) that represents the logical connection to be used. The ID is the fully qualified name of a previously configured database in the following format: Logical/nodeName. The value of nodeName is the path to the database connection. To determine this value, locate the database object in the Test Factory view and note the folder structure where it is located.

For more information, see Database resources, connections, and bindings.
Note: Functions can be written in Legacy Script Language or in ECMAScript. For details, see Scripts within tests and stubs. All the examples given in the following table are in Legacy, unless otherwise specified.
Table 1. Function description
Function Example Description 
dbQuery(connectionId, query)
connectionId
The project path of the logical database resource you want to query. For example, "Acct/JDBC/SQL". Note that the "Logical/" prefix is not used.
query
The SQL statement to run against the selected database.
 
dbQuery("Acct/JDBC/SQL","SELECT * FROM credits")
 Runs a SQL query against a configured database, returning the value from the first column of the first row of the result set. The function is typically used to request singular elements of data. 
dbUpdate(connectionId, updateSQL)
connectionId
The full path of the logical database resource you want to update. For example, Logical/MyProject/Accounting/JDBC/SQL-Accounts.
updateSQL
The SQL statement to run against the selected database.
 Legacy: 
dbUpdate("Accounting/JDBC/SQL-Accounts","UPDATE Persons SET Acct='Savings' WHERE LastName='Taylor' AND FirstName='Robert'")
ECMAScript: 
dbUpdate("Accounting/JDBC/SQL-Accounts", "UPDATE Persons SET Acct='Savings' WHERE LastName='Taylor' AND FirstName='Robert'")
 Runs an update-based SQL statement against a configured database, returning the number of rows that are affected by the statement. 
join(delimiter, expr, expr, ...)
 Legacy: 
join(;,2,3,4)
ECMAScript: 
join(';',2,3,4);
 Combines the listed arguments into a single string by using the specified delimiter. For example, join(;,2,3,4) returns 2;3;4. You can use the function to store a list of values into a single tag. 
logToConsole(role, message)
role
The role for the log message, which must be Info, Warning, or Error. The role parameter is not case sensitive. The role defaults to Info if any other value is specified.
message
The message to log to the console, which can be any string. 
logToConsole("Info","this is a log message")

This function writes a specified output message to the console. Logging an Error message gives the overall test a fail status, but subsequent test steps are executed as the logic of the test requires.

The number of Information, Warning, and Error messages generated by the logToConsole function are totaled in a "Logging summary" message at the end of the test.

 
lookupTD(dataSetPath,[keyColumn,matchValue,]* resultColumn,<defaultValue>)
datasetPath
The project path (string) to the test data set to search.
keyColumn
The column name to match against.
matchValue
The value in keyColumn to find. Additional pairs of columns and values can be specified to create AND logic.
resultColumn
The column from which to take the result, in the row where the value is matched.
defaultValue
The value to return if no match is found.
 
lookupTD("CustomerService/CheckOperation/TestData","customerID","3","customerName","John","customerAddress","notFound")
 Provides keyed access to a data set. This function works the same way as the Lookup Test Data test action, except that matching results are returned to the function rather than mapped to a tag.
If you have test data sets of differing type but with the same name, such as File and Database, they must be specified by including the proper extension, according to the following data set types:
.dbt
Database data
.ext
Excel data
.fst
Directory data
.sit
File data
 
now(simpleDateFormat)
 
now("MM/dd/yyyy")
 Returns the current time in the specified date and time pattern. For more information, see Formatting and parsing date-time patterns. The output of the function can be used in two ways:
  • In other actions, such as in a log action to be sent to the console
  • Stored for use by other actions within the test
 
null()
Legacy: 
null()
ECMAScript: 
null;
 Returns a null value, which you can use to set tag values or to compare to a database query result. 
print([tags,value])
Note: Applies only to ECMAScript.
tags
Using the keyword tags as a parameter, prints the complete list of tags with their values to the test console.
value
Prints the string literal or the value of the tag to the test console.
 
print(tags)
print("Override the default value with New value")
print(variable)
 Print the value or the complete list of tags to the test console. 
replaceTags(value)
 Legacy: 
setTag(result,replaceTags(%%aTag3%%))
 Replaces tags that are used in other tags with their value in the current tag store. The contents of the tag (by using the replaced values) can then be stored in a new tag.
For example, consider the following tags and their default values:
  • %%tag1%% = A
  • %%tag2%% = B
  • %%tag3%% = %%tag1%% comes before %%tag2%%
  • replaced = replaceTags(%%tag3%%)

The value of %%replaced%% is "A comes before B".

 
resetTags([tagNamePattern])
tagNamePattern
The name pattern is an optional regular expression used to match one or more tag names. If the pattern is omitted, all tags are reset.

It is not possible to use this function to reset global tag values as it is not clear what value to reset to. The tag's starting value might be inherited from the previous test, or from the default value.

Legacy


resetTags()
resetTags(^stress\d\d)
resetTags(stress\d\d)
resetTags(stress02)
resetTags(%%variable%%)

ECMAScript


resetTags()
resetTags("stress[0-9][0-9]")
resetTags("stress[0-9][0-9]")
resetTags("stress02")
resetTags(variable)
Resets all tags that match a stated pattern to their default values. Use regular expressions to create the pattern that the tags must match.
  • The first example resets all tags.
  • The second example resets all tags that begin with the word stress followed by only two digits.
  • The third example resets all tags that contain the word stress followed by at least two digits.
  • The fourth example resets the tag with the name stress02.
  • The fifth example resets the tags with a name that matches the pattern stored in the tag %%variable%%.
 
settlementDate ("startDate", days <Int +/->, "holidayFilename" 
[, "dateFormat" <default="yyyyMMdd">])
startDate
The starting date, specified as a string value that contains a formatted date.
days <Int +/->
A positive or negative value (indicated with "+" or "-") that defines the number of days after or before startDate.
holidayFilename
The full path to a simple text file that contains a list of dates to ignore, separated by the newline character. If the file pathname is not qualified, the default directory is the Rational® Integration Tester installation directory. All functions that can take a filename must include the full location of the file, which can be specified as a local or UNC path.
dateFormat
An optional argument that defines the format to be used for startDate, dates in holidayFilename, and the date that is returned by the function. The format "yyyyMMdd" is the default.
 
settlementDate ("20140101", +60, "UK_holidays.txt")
 Determines a working date that is a defined number of days from a start date. The function counts working days only, ignoring weekends and holidays according to the local calendar. Holidays are configured by using a simple text file that contains a list of dates. 
setTag(tagName,value)
tagName
The name of an existing tag whose value is to be set.
 ECMAScript: 
setTag("mine", "new value");
mine="new value"
 Replaces the contents of an existing tag with a function, expression, or constant specified by "value". You can also do this by using the store operation functionality from within the Function action. The specified tag must already exist.

Do not include beginning and ending percent signs (%%).

 
textFileContent(path)
 
textFileContent("C:\MyData\users.txt")
 Reads and returns the contents of a text file in a specified location. The file contents can be stored in a tag for use in other phases of the test.

The full location of the file can be specified as a local or UNC path.

 
validateDTD(xml, [dtdURL_1, ..., dtdURL_n] )

validateXSD(xml, [schemaURL_1, ..., schemaURL_n] )

validateXSD( %%doc%%, file:///c:\Schemas\example.xsd )
 Determine whether an XML document (xml) is valid in terms of the provided schemas (dtdURL or schemaURL).
The functions behave differently depending on context:
  • If called from within a function action, they return the textual output from the validation process.
  • If called from within a decision action, the output is merged into a boolean result so that an appropriate path can be chosen.
 
XMLdbQuery(connectionId, query)
  • connectionId- The full path of the logical database resource you want to query (for example, Logical/MyProject/Accounting/JDBC/SQL-Accounts).
  • query- The SQL statement to run against the selected database.
 Legacy: 
XMLdbQuery("Users/JDBC/SQL-People","SELECT person, age FROM users")
ECMAScript: 
XMLdbQuery("Users/JDBC/SQL-People","SELECT person, age FROM users");
 Runs a query-based SQL statement against a configured database. The result set of this query is then encoded as XML and provided as the return value from the function.
The XML fragment that is returned conforms to the following schema:
<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <xs:element name="resultSet">
  <xs:complexType>
   <xs:sequence>
    <xs:element name="columns">
     <xs:complexType>
      <xs:sequence>
       <xs:element maxOccurs="unbounded" name="column">
        <xs:complexType>
         <xs:attribute name="name" type="xs:string" use="required" />
         <xs:attribute name="type" type="xs:string" use="required" />
        </xs:complexType>
       </xs:element>
      </xs:sequence>
     </xs:complexType>
    </xs:element>
    <xs:element maxOccurs="unbounded" name="row">
     <xs:complexType>
      <xs:sequence>
       <xs:any minOccurs="0" />
      </xs:sequence>
     </xs:complexType>
    </xs:element>
   </xs:sequence>
   <xs:attribute name="rowCount" type="xs:decimal" use="required" />
  </xs:complexType>
 </xs:element>
</xs:schema>
The example shown returns the following output:
<?xml version="1.0" encoding="UTF-8"?>
<resultSet rowcount="2">
  <columns>
    <column name="person" type="string">
    <column name="age" type="number">
  </columns>
  <row>
    <person>John</person>
    <age>33</age>
  </row>
  <row>
    <person>Helen</person>
    <age>31</age>
  </row>
</resultSet>
 
xpath(xml, xpath)

Example:

For example, (detailed previously).

 Legacy: 

xpath(%%srcData%%,"/resultSet/@rowCount")
xpath(%%srcData%%,"/resultSet/columns")
ECMAScript: 

xpath(srcData,"/resultSet/@rowCount")
xpath(srcData, "/resultSet/columns")
Returns the result of performing an XPath query (xpath) on some XML source that is to be validated (xml). you can get the same result by using the store operation functionality from within the Function action.

The example shown returns the number of rows that are provided in the output from the execution of an xmlDbQuery() function.

Rational® Integration Tester uses the XPATH 2.0 draft standard. Therefore, the fully qualified node name, including the namespace, must be used when matching nodes.

If attributes are included in the XML, the XML must be quoted and the quotes that surround the attribute must be escaped. The following example illustrates this requirement: 
xpath("<a><b action=\"copy\"/></a>", "a/b")