$suiteDb = new SuiteDB(name, [read/write [, timeout[, path]]]);

Creates a new suite database object, optionally opening a non-default target file and optionally making it writeable.

name the name of the test suite to open

read/write boolean set to True if the suite database needs to be writeable or False if it can be readOnly.

timeout the number of seconds to wait for a lock. Defaults to 60 seconds.

path a path to an alternate database (the default is implementation defined).

returns a reference to the suite database object.

Removes everything from the database.

returns true if it succeeded, false if it did not.

returns a path to the file.

$suiteDb->print();
    $suiteDb->print(ID);

returns the string-ified version of the entire database.

profName = $sdb->profName( [ name ] ) ;

Returns the name of the profile associated with this object. This ONLY happens if we are working in profile management mode.

$suiteDb->release() ;

returns the path saved into, or undef if the save failed.

$suiteDb->deleteSession($session);

deletes a session if it is defined.

$suiteDb->deleteSet($name);

deletes a set if it is defined.

@mlists = $suiteDB->multiLists() ;

$suiteDb->session(ID);
    $suiteDb->session(ID, ref);

With an ID parameter, retrieves the data for a specific session.

With an ID and a ref, sets the parameters for a session to ref.

returns the pointer a SuiteDB::Session object that represents the specific session.

The session meta data that is stored in this database includes:

assignedto

to whom this session is assigned (comma separated list).

description

The session description.

numtests

The number of tests.

numUntested

The number of tests still not tested.

isActive

Whether the session is currently active or not.

locked

Is the session locked?

mtime

The last modification time of the session.

summary

The summary of the session.

testset

The test set to which this session is attached.

user

The last user to modify the session.

variable

A hash of all variables defined for the session.

@sessionList = $suiteH->sessionList() ;
    @sessionList = $suiteH->sessionList(set) ;

    # get the list of sessions that have no test set
    @sessionList = $suiteH->sessionList(undef, 1) ;

$setHash = $suiteDb->set(ID);
    $setHash = $suiteDb->set(ID, ref);

With an ID parameter, retrieves the data for a specific set.

With an ID and a ref, sets the parameters for a set to ref.

Adds a lastChangeTime key to the dataset when updating a test set. Returns the pointer to the data for a specific set.

Returns a reference to an object that has test set meta data, including:

numtests

The number of tests selected by the set.

locked

Whether the set is locked or not.

mtime

The last time the set was modified.

summary

The summary description of the test set.

sessions

A reference to a list of associated test sessions.

@setList = $suiteDb->setList( [ setGroup [, children ] ] ) ;

setGroup is an optional testset group name. If provided, only sets within that group are returned. If set to "", then only sets in NO group will be returned.

if the optional children parameter is true, then sets in the setGroup and all child set groups will be returned.

$suiteDb->testMap(UUID);
    $suiteDb->testMap(UUID, ref);

With an UUID parameter, retrieves the data for a specific testcase.

With an UUID and a ref, sets the parameters for a testcase map to ref.

returns the pointer a SuiteDB::TestMap object that represents the specific test case.

The test case meta data that is stored in this database includes:

sessHash

A hash of test sessions - each entry contains

result

The result of running the test.

when

The time when the test was run.

$time = $suiteDb->lastEditUpdate() ;

$time = $suiteDb->lastFolderUpdate() ;

$time = $suiteDb->lastReqEditUpdate() ;

$time = $suiteDb->lastReqFolderUpdate() ;

$time = $suiteDb->lastRunUpdate() ;
    $time = $suiteDb->lastRunUpdate(setName) ;

$time = $suiteDb->lastUserPermUpdate() ;
    $time = $suiteDb->lastUserPermUpdate( timeStamp) ;

Returns the timestamp of the last time the user permission table for this suite was updated. If the table does not exist, returns 0.

$tests = $suiteDb->numReqs() ;

$sessCount = $suiteDb->numSessions( [num] ) ;

$setCount = $suiteDb->numSets( [num] ) ;

$tests = $suiteDb->numTests() ;

$val = $suiteDb->dirtyFlag( [ state ] ) ;

If state is supplied, it is a value to set. When state is 0, the data is NOT dirty. When state is 1, the associated "Run" data was updated, and the data is dirty. When state is 2, the associated "Edit" data was updated and the data is dirty.

Returns undef if the database is not writeable. Otherwise returns the current value of the dirtyFlag state;

$rRef = $suiteDb->results( [ $rRef ] ) ;

$rRef is an optional reference to a results object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$permRef = $suiteDb->userPerms( [ $data ] ) ;

If the optional $data parameter is provided, the data is updated to that hash ref.

Returns a reference to a hash that maps userids to access level numbers.

$vRef = $suiteDb->variables( [ $vRef ] ) ;

$vRef is an optional reference to a VariableSet object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$rRef = $suiteDb->rfields( [ $rRef ] ) ;

$rRef is an optional reference to a requirements field object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

Note that ReqFields uses the Parent base class, so we need to be certain to NOT attempt to serialize that part of the object.

($fieldRef, $orderRef) = $suiteDb->rundata( [ $runRef, $orderRef ] ) ;

$runRef is an optional reference to a testFields hash from TestSession. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$orderRef is an optional reference to a list of defined rundata fields in order. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

Note that unlike other suiteDB caching objects, this one will NOT automatically acquire the data if it is not in the cache.

$sRef = $suiteDb->schema( [ $sRef [, update ] ] ) ;

$sRef is an optional reference to a schema object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$update is a flag. If true, then the cached image is updated even if an sRef is not passed in.

$vset = $suiteDb->dirtyFlag( [ curSet ] ) ;

If curSet is supplied, it is used as a handle to a variable set object for the suiteDB. Otherwise, one is initialized.

Returns a handle to a variable set.

$suiteDB->Lock() ;

Ensures the caches and this database are locked.

$suiteDB->Unlock() ;

Ensures the caches and this database are unlocked.

$fref = $sdb->field( columnName )

columnName is the name of a SQL table column.

Returns a reference to an object that supports (at least) the isDate method.

$tdb->SQL_deleteTestSession(sessNum) ;

Returns nothing.

my $tname = $sdb->SQL_tname;

Returns the name of the table for this object.

$sdb->SQL_updateTestSession(sessNum, hash) ;

sessNum is the ID of the test session to update.

hash is the data to populate the test session record with.

Returns nothing.

SQL_insertMulti(sessNum, sdata, fname );

sessNum is the session number we are updating.

sdata is a reference to the session meta data hash.

fname is the name of the field to populate.

Returns nothing.

$sdb->SQL_createIndices();

Returns nothing.

$sdb->SQL_createTable();

Returns nothing.

$sdb->SQL_makeTables() ;

Returns nothing.

@cols = $suiteDB->SQL_tableDef( tname ) ;

tname is the name of a SQL table

Returns a list item per column, formatted for use in a CREATE statement.

@cols = $suiteDB->SQL_tableFields( tname ) ;

tname is the name of a SQL table.

Returns a list of fields that are used in the table.

my @tlist = $sdb->SQL_tlist();

Returns a list of all tables this object will operate upon.

$sqltype = $sdb->SQL_type(fref)

fref is a reference to a session variable definition.

This is just a thin veneer over the base ApTest::DBI type method, which will interrogate the underlying database and pick the best type. This function ascertains the base ATM type and passes that to the parent method, since Schema fields use a combination of type and style to define the actual "type".

Returns the most likely SQL type to use for the field.

$val = $sdb->SQL_value(fref, value) ;

fref is a reference to a Variable object.

value is the value to use.

Returns a suitable quoted value.

SuiteDB::TestMap - class for manipulating a mapping from tests to sessions.

new - create a new TestMap object

$tmap = new SuiteDB::TestMap(UUID) ;

my $entry = $tmap->entry(sessnum) ;

sessnum is a session number - note that these are NOT stored with leading zeroes.

Returns a reference to the hash entry for this entry, or undef if there is no entry for the session.

$num = $tmap->numEntries() ;

Returns the number of result entries ;

my @list = $tmap->sortedList( direction )

direction is a boolean - false means descending, true means ascending

Returns a list of hash entries sorted in the described order

$tmap->update( $session, $href ) ;

session is the session number to update.

href is a reference to a hash that contains at least a 'result' and a 'when' entry.

DESTROY() - tidy up

SuiteDB::Session - class for manipulating session metadata

new - create a new Session object

$session = new SuiteDB::Session(sessnum) ;

defaultVariable - return a variable OR the default if it is not set

$value = $session->defaultVariable() ;

variable - accessor for variable attributes

$session->variable(varName) ;

refreshable - is the session refreshable?

my $refreshable = $session->refreshable();

resCounter - count for each type of result

my $count = $session->resCounter( resultName ) ;

displaySetName

$dname = $session->displaySetName() ;

checkSession - check if a session passes various filters

my $bool = $sess->checkSession( filtRef ) ;

sesslist - list of sessions (rarely used)
    sessnumLow - low end of range of session numbers
    sessnumHigh - high end of range of session numbers
    users - list of modifying users
    assignees - list of assigned users
    testsets - list of test sets to match
    schedule - schedule settings
    locked - locked or unlocked
    date - the last mod date if it is interesting; also startdate and enddate for range
    run - types of "run"
    VAR_* - session variable selections

DESTROY() - tidy up

SuiteDB::Set - class for manipulating set metadata

new - create a new Set object

$set = SuiteDB::Set->new(setname, hashRef) ;