Test Script Services |
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).
Use the datapool functions listed in the following table to access and manipulate datapools within your scripts.
TSSDatapoolClose()
Closes a datapool.
TSSDatapoolColumnCount()
Returns the number of columns in a datapool.
TSSDatapoolColumnName()
Returns the name of the specified datapool column.
TSSDatapoolFetch()
Moves the datapool cursor to the next row.
TSSDatapoolOpen()
Opens the named datapool and sets the row access order.
TSSDatapoolRewind()
Resets the datapool cursor to the beginning of the datapool access order.
TSSDatapoolRowCount()
Returns the number of rows in a datapool.
TSSDatapoolSearch()
Searches a datapool for the named column with a specified value.
TSSDatapoolSeek()
Moves the datapool cursor forward.
TSSDatapoolValue()
Retrieves the value of the specified datapool column.
s32TSSDatapoolClose
(s32dpid
)
dpid
The ID of the datapool to close. Returned by TSSDatapoolOpen().
This function exits with one of the following results:
TSS_OK
. Success.
TSS_NOSERVER.
No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
This example opens the datapool custdata
with default row access and closes it.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
s32 retVal = TSSDatapoolClose
(dpid);
Returns the number of columns in a datapool.
s32TSSDatapoolColumnCount
(s32dpid
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
On success, this function returns the number of columns in the specified datapool. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This example opens the datapool custdata
and gets the number of columns.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
s32 columns = TSSDatapoolColumnCount
(dpid);
Gets the name of the specified datapool column.
char *TSSDatapoolColumnName
(s32dpid
, s32columnNumber
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
columnNumber
A positive number indicating the number of the column whose name you want to retrieve. The first column is number 1.
On success, this function returns the name of the specified datapool column. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier or column number is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This example opens a three-column datapool and gets the name of the third column.
char *colName;
s32 dpid = TSSDatapoolOpen("custdata",0,0,NULL);
if (dpid > 0)
if (TSSDatapoolFetch(dpid) == TSS_OK)
colName = TSSDatapoolColumnName
(dpid,3);
Moves the datapool cursor to the next row.
s32TSSDatapoolFetch
(s32dpid
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
This function exits with one of the following results:
TSS_OK.
Success.
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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 TSSDatapoolValue()
.
The "next row" is determined by the assessFlags
passed with the open call. The default is the next row in sequence. See TSSDatapoolOpen()
.
After a datapool is opened, a TSSDatapoolFetch()
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 TSSDatapoolValue()
results in a runtime error.
This example opens datapool custdata
with default (sequential) access and positions the cursor to the first row.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
s32 retVal = TSSDatapoolFetch
(dpid);
TSSDatapoolOpen()
, TSSDatapoolSeek()
, TSSDatapoolValue()
Opens the named datapool and sets the row access order.
s32TSSDatapoolOpen
(char *name
, u32accessFlags
, s32overrideCount
, NamedValue *overrides
)
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:
TSS_DP_SEQUENTIAL
- Physical order (default)
TSS_DP_RANDOM
- Any order, including multiple access or no access
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
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
.
TSS_DP_REWIND
specifies that the datapool should be rewound when opened. Ignored unless used with
TSS_DP_PRIVATE
.
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 TSSDatapoolValue() for that column name. Unless access flag TSS_DP_NO_OPEN is present, specify as NULL
.
On success, this function returns a positive integer indicating the ID of the opened datapool. The function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The accessFlags
argument is or results in an invalid combination.
TSS_NOTFOUND
. No datapool of the given name
was found.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
If the accessFlags
argument is specified as 0, 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:
The NamedValue
data type is defined as follows:
typedef struct { char *Name; char *Value; } NamedValue;
This example opens the datapool named custdata
, with a modified row access.
s32 dpid = TSSDatapoolOpen
("custdata",TSS_DP_SHUFFLE |
TSS_DP_PERSIST,0,NULL);
Resets the datapool cursor to the beginning of the datapool access order.
s32TSSDatapoolRewind
(s32dpid
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
This function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
The datapool is rewound as follows:
DP_SEQUENTIAL
, TSSDatapoolRewind()
resets the cursor to the first record in the datapool file.
DP_RANDOM
or DP_SHUFFLE
, TSSDatapoolRewind()
restarts the random number sequence.
DP_SHARED
, TSSDatapoolRewind()
has no effect.
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.
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.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
{
TSSDatapoolSeek (dpid,2);
TSSDatapoolRewind
(dpid);
};
Returns the number of rows in a datapool.
s32TSSDatapoolRowCount
(s32dpid
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
On success, this function returns the number of rows in the specified datapool. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This example opens the datapool custdata
and gets the number of rows in the datapool.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
s32 rows = TSSDatapoolRowCount
(dpid);
Searches a datapool for a named column with a specified value.
s32TSSDatapoolSearch
(s32dpid
, s32keyCount
, NamedValue *keys
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
keycount
The number of columns in
keys
.
keys
An array containing values to be searched for.
This function exits with one of the following results:
TSS_OK.
Success.
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
When a row is found containing the specified values, the cursor is set to that row.
The NamedValue
data type is defined as follows:
typedef struct { char *Name; char *Value; } NamedValue;
This example searches the datapool custdata
for a row containing the column named Last
with the value Doe
:
NamedValue toFind[1];
toFind[0].Name = "Last";
toFind[0].Value = "Doe";
s32 dpid = TSSDatapoolOpen("custdata",0,0,NULL);
if (dpid > 0)
if (TSSDatapoolFetch(dpid) == TSS_OK)
s32 rowNumber = TSSDatapoolSearch
(dpid,1,toFind);
Moves the datapool cursor forward.
s32TSSDatapoolSeek
(s32dpid
, s32count
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
count
A positive number indicating the number of rows to move forward in the datapool.
This function exits with one of the following results:
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The datapool identifier is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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 TSSDatapoolValue()
.
The meaning of "forward" depends on the accessFlags
passed with the open call; see TSSDatapoolOpen()
. This call is functionally equivalent to calling TSSDatapoolFetch()
count
times.
An end-of-file (TSS_EOF) error results if cursor wrapping is disabled (by access flag TSS_DP_NOWRAP
) and count
moves the access row beyond the last row. If TSSDatapoolValue()
is then called, a runtime error occurs.
This example opens the datapool custdata
with the default (sequential) access and moves the cursor forward two rows.
s32 dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid > 0)
TSSDatapoolSeek
(dpid, 2);
TSSDatapoolFetch()
, TSSDatapoolOpen()
, TSSDatapoolValue()
Retrieves the value of the specified datapool column in the current row.
char * TSSDatapoolValue
(s32 dpid
, char *columnName
)
dpid
The ID of the datapool. Returned by TSSDatapoolOpen().
columnName
The name of the column whose value you want to retrieve.
On success, this function returns the value of the specified datapool column in the current row. The function exits with one of the following results:
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_INVALID
. The specified columnName
is not a valid column in the datapool.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This call gets the value of the specified datapool column from the current datapool row, which has been loaded into memory either by TSSDatapoolFetch()
or TSSDatapoolSeek()
.
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.
This example retrieves the value of the column named Middle
in the first row of the datapool custdata
.
char *colVal;
s32 dpid = TSSDatapoolOpen("custdata",0,0,NULL)
if (dpid > 0)
if (TSSDatapoolFetch(dpid) == TSS_OK)
colVal = TSSDatapoolValue
("Middle");
TSSDatapoolFetch()
, TSSDatapoolOpen()
, TSSDatapoolSeek()
Rational TestManager Extensibility Reference | Rational Software Corporation |
Copyright (c) 2003, Rational Software Corporation | http://www.rational.com support@rational.com info@rational.com |