Other functions

The following describes the remaining functions that are available in IBM® Rational® Integration Tester.

Note: 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 Scripting within tests and stubs. All the examples given in the following table are in Legacy, unless specified otherwise.
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.
 
dbUpdate("Logical/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, ...)
 
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. 
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("SC2/OP/iterations/excel.ext",arg0,a,arg1,b)
 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.
Test data sets must be specified by using 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()
 
null()
 Returns a null value, which you can use to set tag values or to compare to a database query result. 
replaceTags(value)
 
result=replaceTags(%%message1%%)
 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])
 
resetTags([^stress\d\d])
 Resets all tags that match a stated pattern to their default values. Use regular expressions to create the pattern that the tags must match.

In the example shown, all tags that begin with the word "stress" followed by two digits, such as %%stress01%%, are reset.

 
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.
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.
 
setTag(tag1,"A")
 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.
 
XMLdbQuery("Logical/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).

 
xpath("%%srcData%%","/resultSet/@rowCount")
 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 illustrated this requirement: 
xpath("<a><b action=\"copy\"/></a>", "a/b")
Assertion functions
Mathematical functions
String functions
Feedback