Test Script Services Reference

prevnext

Datapool Class


During testing, it is often necessary to supply an application with a range of test data. Thus, in the functional test of a data entry component, you may want to try out the valid range of data, and also to test how the application responds to invalid data. Similarly, in a performance test of the same component, you may want to test storage and retrieval components in different combinations and under varying load conditions.

A datapool is a source of data stored in a Rational project that a test script can draw upon during playback, for the purpose of varying the test data. You create datapools from TestManager, by clicking Tools > Manage > Datapools. For more information, see the datapool chapter in the Rational TestManager User's Guide. Optionally, you can import manually created datapool information stored in flat ASCII Comma Separated Values (CSV) files, where a row is a newline-terminated line and columns are fields in the line separated by commas (or some other field-delimiting character).


Applicability

Commonly used with TestManager and QualityArchitect.


Summary

Use the datapool methods listed in the following table to access and manipulate datapools within your scripts. These are static methods of class TSSDatapool.

Method Description
close() Closes a datapool.
columnCount() Returns the number of columns in a datapool.
columnName() Returns the name of the specified datapool column.
fetch() Moves the datapool cursor to the next row.
open() Opens the named datapool and sets the row access order.
rewind() Resets the datapool cursor to the beginning of the datapool access order.
rowCount() Returns the number of rows in a datapool.
search() Searches a datapool for the named column with a specified value.
seek() Moves the datapool cursor forward.
value() Retrieves the value of the specified datapool column.


TSSDatapool.close()

Closes a datapool.


Syntax

int close()

Return Value

This exits with one of the following results:


Comments

Only one open datapool at a time is supported. A close() is thus required between intervening Oopen() calls. For a script that opens only one datapool, close() is optional.


Example

This example opens the datapool custdata with default row access and closes it.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
int retVal = dp.close();

See Also

open()


TSSDatapool.columnCount()

Returns the number of columns in a datapool.


Syntax

int columnCount ()

Return Value

On success, this method returns the number of columns in the open datapool.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Example

This example opens the datapool custdata and gets the number of columns.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
int columns = dp.columnCount();

TSSDatapool.columnName()

Gets the name of the specified datapool column.


Syntax

String columnName (int columnNumber)

Element Description
columnNumber A positive number indicating the number of the column whose name you want to retrieve. The first column is number 1.


Return Value

On success, this method returns the name of the specified datapool column.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Example

This example opens a three-column datapool and gets the name of the third column.

TSSDatapool dp = New TSSDatapool;
dp.open ("custdata");
if (dp.fetch())
	 String colName = dp.columnName(3);

TSSDatapool.fetch()

Moves the datapool cursor to the next row.


Syntax

boolean fetch()

Return Value

This method returns true (success) or false (end-of-file).


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

This call positions the datapool cursor on the next row and loads the row into memory. To access a column of data in the row, call value().

The "next row" is determined by the assessFlags passed with the open call. The default is the next row in sequence. See open().

After a datapool is opened, a fetch() is required before the initial row can be accessed.

An end-of-file (TSS_EOF) condition results if a script fetches past the end of the datapool, which can occur only if access flag TSS_DP_NOWRAP was set on the open call. If the end-of-file condition occurs, the next call to value() throws an exception.


Example

This example opens datapool custdata with default (sequential) access and positions the cursor to the first row.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
boolean retVal = dp.fetch();

See Also

open(), seek(), value()


TSSDatapool.open()

Opens the named datapool and sets the row access order.


Syntax

void open(String name, int accessFlags, TSSNamedValue[] 
overrides)
void open(String name)

Element Description
name The name of the datapool to open. If accessFlags includes TSS_DP_NO_OPEN, no CSV datapool is opened; instead, name refers to the contents of overrides specifying a one-row table. Otherwise, the CSV file name in the Rational project is opened.
accessFlags Optional flags indicating how the datapool is accessed when a script is played back. Specify at most one value from each of the following categories:
  1. Specify the sequence in which datapool rows are accessed:

    TSS_DP_SEQUENTIAL - Physical order (default)

    TSS_DP_RANDOM - Any order, including multiple access or no access

    TSS_DP_SHUFFLE - Access order is shuffled after each access

  2. Specify what happens after the last datapool row is accessed:

    TSS_DP_NOWRAP - End access to the datapool (default)

    TSS_DP_WRAP - Go back to the beginning

  3. Specify whether the datapool cursor is shared by all virtual testers or is unique to each:

    TSS_DP_PRIVATE - Virtual testers each work from their own sequential, random, or shuffle access order (default)

    TSS_DP_SHARED - All virtual testers work from the same access order

  4. TSS_DP_PERSIST specifies that the datapool cursor is persistent across multiple script runs. For example, with a persistent cursor, if the row number after a suite run is 100, the first row accessed in a subsequent run is numbered 101. Cannot be used with TSS_DP_PRIVATE. Ignored if used with TSS_DP_RANDOM.

  5. TSS_DP_REWIND specifies that the datapool should be rewound when opened. Ignored unless used with TSS_DP_PRIVATE.

  6. TSS_DP_NO_OPEN specifies that, instead of a CSV file, the opened datapool consists only of column/value pairs specified in a local array overrides[].

overrideCount The number of columns in array overrides. Must be greater than 0 if access flag TSS_DP_NO_OPEN is specified; otherwise, must be 0.
overrides A local, two-dimensional array of column/value pairs, where overrides[n].name is the column name and overrides[n].value is the value returned by value() for that column name. See TSSNamedValue for the implementation of this argument's data type.


Exceptions

These methods may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

If the accessFlags argument is specified as 0 or omitted, the rows are accessed in the default order: sequentially, with no wrapping, and with a private cursor. If multiple accessFlags are specified, they must be valid combinations as explained in the syntax table.

If accessFlags specified with open() contradict those specified with the datapool configuration section (see Appendix A), the open() call fails with TSS_INVALID. Otherwise, the two sets of access flags are combined.

If you close and then reopen a private-access datapool with the same accessFlags and in the same or a subsequent script, access to the datapool is resumed as if it had never been closed.

A test script executed by TestManager can open only one datapool at a time.

If multiple virtual testers access the same datapool in a suite, the datapool cursor is managed as follows:

An exception is thrown if open() is called more than once (for a given instance of the class) without an intervening close() call. The exception message is "open was called without closing the previously opened Datapool". A call to TSSException.getReturnValue() in the catch block identifies the datapool that was already open when the call was made.


Example

This example opens the datapool named custdata. The datapool configuration statements, which may occur anywhere in the script, name the datapool and set the default row access.

TSSDatapool dp = new TSSDatapool();
dp.open("custdata");
...
public static class DatapoolConfig extends DatapoolInfo {
        public DatapoolConfig() {
            setDatapoolName("custdata");
            setDatapoolAccessFlags(TSS_DP_WRAP |
                                   TSS_DP_SEQUENTIAL |
                                   TSS_DP_SHARED);
        }
    }

See Also

close()


TSSDatapool.rewind()

Resets the datapool cursor to the beginning of the datapool access order.


Syntax

void rewind()


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The datapool is rewound as follows:

At the start of a suite, datapool cursors always point to the first row.

If you rewind the datapool during a suite run, previously accessed rows are fetched again.


Example

This example opens the datapool custdata with default (sequential) access, moves the access to the second row, and then resets access to the first row.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
dp.seek(2);
dp.rewind();

TSSDatapool.rowCount()

Returns the number of rows in a datapool.


Syntax

int rowCount()

Return Value

On success, this method returns the number of rows in the open datapool.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Example

This example opens the datapool custdata and gets the number of rows in the datapool.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
int rows = dp.rowCount();

TSSDatapool.search()

Searches a datapool for a named column with a specified value.


Syntax

void search (TSSNamedValue[] keys)

Element Description
keys An array containing values to be searched for. See TSSNamedValue for the implementation of this argument's data type.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

When a row is found containing the specified values, the cursor is set to that row.


Example

This example searches the datapool custdata for a row containing the column named Last with the value Doe:

TSSNamedValue[] toFind = new TSSNamedValue[1];
toFind[0] = new TSSNamedValue();
toFind[0].name = "Last";
toFind[0].value = "Doe";
TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
if (dp.fetch())
	 dp.search(toFind);

TSSDatapool.seek()

Moves the datapool cursor forward.


Syntax

void seek(int count)

Element Description
count A positive number indicating the number of rows to move forward in the datapool.


Return Value


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

This call moves the datapool cursor forward count rows and loads that row into memory. To access a column of data in the row, call value().

The meaning of "forward" depends on the accessFlags passed with the open call; see open(). This call is functionally equivalent to calling fetch() count times.

In addition to throwing an exception on error, this method returns a Boolean status indicator where false indicates end-of-file (TSS_EOF). A script can check for this condition.

If a script fetches past the end of the datapool (as a result of TSS_DP_NOWRAP being set), the next call to TSSDatapool.value() throws an exception.


Example

This example opens the datapool custdata with the default (sequential) access and moves the cursor forward two rows.

TSSDatapool dp = new TSSDatapool();
dp.open("custdata");
dp.seek(2);

See Also

fetch(), open(), value()


TSSDatapool.value()

Retrieves the value of the specified datapool column in the current row.


Syntax

DatapoolValue value(String columnName)

Element Description
columnName The name of the column whose value you want to retrieve.


Return Value

On success, this method returns the value of the specified datapool column in the current row.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

This call gets the value of the specified datapool column from the current datapool row, which has been loaded into memory either by fetch() or seek().

By default, the returned value is a column from a CSV datapool file located in a Rational datastore. If the datapool open call included the TSS_DP_NO_OPEN access flag, the returned value comes from an override list provided with the open call.

Datapools store all data as strings. As a consequence, a retrieved value that is not really a string must be converted. To facilitate conversions, the class DatapoolValue wraps the value returned by TSSDatapool.value() and the following conversion methods are provided.

This method Generates
booleanValue() The boolean representation of the datapool value.
byteValue() The byte representation of the datapool value.
charValue() The character representation of the datapool value.
doubleValue() The double representation of the datapool value.
floatValue() The float representation of the datapool value.
getBigDecimal() The BigDecimal representation of the datapool value.
intValue() The int representation of the datapool value.
longValue() The long representation of the datapool value.
shortValue() The short representation of the datapool value.
toString() The String representation of the datapool value.


Example

This example retrieves the value of the column named Middle in the first row of the datapool custdata.

TSSDatapool dp = new TSSDatapool();
dp.open("custdata");
if (dp.fetch()==true)
	 phonebook.queryPerson(dp.value("Middle").toString());
	 // queryPerson method expects a String parameter

See Also

fetch(), open(), seek()

prevnext


Rational Test Script Services for Java Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com