Test Script Services Reference

prevnext

Datapool Commands


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).


Summary

Use the datapool commands listed in the following table to access and manipulate datapools within your scripts.

Command Description
DatapoolClose Closes a datapool.
DatapoolColumnCount Returns the number of columns in a datapool.
DatapoolColumnName Returns the name of the specified datapool column.
DatapoolFetch Moves the datapool cursor to the next row.
DatapoolOpen Opens the named datapool and sets the row access order.
DatapoolRewind Resets the datapool cursor to the beginning of the datapool access order.
DatapoolRowCount Returns the number of rows in a datapool.
DatapoolSearch< Searches a datapool for the named column with a specified value.
DatapoolSeek Moves the datapool cursor forward.
DatapoolValue Retrieves the value of the specified datapool column.


DatapoolClose

Closes a datapool.


Syntax

tsscmd DatapoolClose dpid

Element Description
dpid The ID of the datapool to close. Returned by DatapoolOpen.


Return Value

This command exits with one of the following results:


Example

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

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolClose dpid

See Also

DatapoolOpen


DatapoolColumnCount

Returns the number of columns in a datapool.


Syntax

columns = `tsscmd DatapoolColumnCount dpid` 

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.


Return Value

On success, this command returns the number of columns in the specified datapool. The command exits with one of the following results:


Example

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

dpid = `tsscmd DatapoolOpen custdata`
columns = `tsscmd DatapoolColumnCount dpid`

DatapoolColumnName

Gets the name of the specified datapool column.


Syntax

columnName = `tsscmd DatapoolColumnName dpid columnNumber`

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.
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 command returns the name of the specified datapool column. The command exits with one of the following results:


Example

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

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch dpid
colName = `tsscmd DatapoolColumnName dpid 3`

DatapoolFetch

Moves the datapool cursor to the next row.


Syntax

tsscmd DatapoolFetch dpid

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.


Return Value

This command exits with one of the following results:


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 DatapoolValue.

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

After a datapool is opened, a DatapoolFetch is required before the initial row can be accessed.

An end-of-file condition results if a script fetches past the end of the datapool, which can occur only if access flag NOWRAP was set on the open call. If the end-of-file condition occurs, the next call to DatapoolValue results in a runtime error.


Example

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

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch dpid

See Also

DatapoolOpen, DatapoolSeek, DatapoolValue


DatapoolOpen

Opens the named datapool and sets the row access order.


Syntax

dpid =`tsscmd DatapoolOpen [-access accessFlags] name 
[colname=value...]`

Element Description
name The name of the datapool to open. If accessFlags includes NO_OPEN, no CSV datapool is opened; instead, name refers to the specified name/value pairs 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:

    SEQUENTIAL - Physical order (default)

    RANDOM - Any order, including multiple access or no access

    SHUFFLE - Access order is shuffled after each access

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

    NOWRAP - End access to the datapool (default)

    WRAP - Go back to the beginning

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

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

    SHARED - All virtual testers work from the same access order

  4. 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 PRIVATE. Ignored if used with RANDOM.

  5. REWIND specifies that the datapool should be rewound when opened. Ignored unless used with PRIVATE.

  6. NO_OPEN specifies that, instead of a CSV file, the opened datapool consists only of specified column/value pairs.

colname=value ... Optionally, a list of one or more column/value pairs, where colname is the column name and value is the override value to be returned by DatapoolValue for that column name.
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 DatapoolValue for that column name.


Return Value

On success, this command returns a positive integer indicating the ID of the opened datapool. The command exits with one of the following results:


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

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


Example

This example opens the datapool named custdata, with a modified row access.

dpid = `tsscmd DatapoolOpen -a SHUFFLE -a PERSIST custdata`

See Also

DatapoolClose


DatapoolRewind

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


Syntax

tsscmd DatapoolRewind dpid

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.


Return Value

This command exits with one of the following results:


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.

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolSeek dpid 2
tsscmd DatapoolRewind dpid

DatapoolRowCount

Returns the number of rows in a datapool.


Syntax

rows = `tsscmd DatapoolRowCount dpid` 

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.


Return Value

On success, this command returns the number of rows in the specified datapool. The command exits with one of the following results:


Example

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

dpid = `tsscmd DatapoolOpen custdata`
rows = `tsscmd DatapoolRowCount dpid`

DatapoolSearch

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


Syntax

tsscmd DatapoolSearch dpid column=value [...]

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.
column=value One or more column/value pairs to be searched for.


Return Value

This command exits with one of the following results:


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:

dpid = `tsscmd DatapoolOpen custdata`
rowNumber=`tsscmd DatapoolSearch dpid Last=Doe`

DatapoolSeek

Moves the datapool cursor forward.


Syntax

tsscmd DatapoolSeek dpid count

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.
count A positive number indicating the number of rows to move forward in the datapool.


Return Value

This command exits with one of the following results:


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 DatapoolValue.

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

An end-of-file error results if cursor wrapping is disabled (by access flag NOWRAP) and count moves the access row beyond the last row. If DatapoolValue is then called, a runtime error occurs.


Example

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

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolSeek dpid 2

See Also

DatapoolFetch, DatapoolOpen, DatapoolValue


DatapoolValue

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


Syntax

value = `tsscmd DatapoolValue dpid columnName`

Element Description
dpid The ID of the datapool. Returned by DatapoolOpen.
columnName The name of the column whose value you want to retrieve.


Return Value

On success, this command returns the value of the specified datapool column in the current row. The command exits with one of the following results:


Comments

This call gets the value of the specified datapool column from the current datapool row, which has been loaded into memory either by DatapoolFetch or DatapoolSeek.

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 NO_OPEN access flag, the returned value comes from an override list provided with the open call.

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.

dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch dpid
colVal = `tsscmd DatapoolValue dpid Middle`

See Also

DatapoolFetch, DatapoolOpen, DatapoolSeek

prevnext


The Command Line Interface to Rational Test Script Services Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com