$suite = new Suite();
    $suite = new Suite(suite);
    $suite = new Suite(suite, readWrite);
    $suite = new Suite(suite, readWrite, profName);

suite is the test suite in which we are operating

readWrite is a state flag that indicates whether the object should be writeable. If it is 0, the object and everything it opens will by default be opened read-only. If it is 1, the object and everything it opens will by default be opened in write mode. If it is 2, the suiteDB will be opened in write mode, but child objects will be opened read-only unless explicitly opened in write mode when first requested. This is useful when doing updates to meta-data and a test session, for example. The test database can be opened read-only, but the SuiteDB and specific session need to be writeable. The default value is 0 - read-only.

profName is an optional profile name. The Suite object can be used as an access conduit for various other objects even when managing a profile.

$suite = create Suite(suite, desc, profile);

suite is the test suite to create desc is a description for the suite profile is the name of the profile to use

returns a handle to the newly created suite, or undef if there was an error.

$name = $suite->creator( $name )

name is an optional creator name.

Returns the creator of the test suite, if any.

$path = $suite->path();

$len = $suite->pathLen( $file ) ;

file is the name of a file.

Returns the length of the path to the file.

$suite->Lock() ;

Ensures all the relevant databases are locked in the right order.

$suite->Unlock() ;

Ensures all the relevant databases are unlocked in reverse order to how they were locked.

$dir = $suite->dataDir() ;

$dir = $suite->deletedDir() ;

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

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

$dir = $suite->recycleDir();

$dir = $suite->templateDir() ;

Note that this method calls save on any objects that are attached if those objects are writeable and still dirty

$resH = $suiteH->results( [resH] ) ;

resH is an optional reference to an existing results object.

Returns a reference to a results object for the suite.

This will just sync out the testDB object.

$res = $suite->save();

returns 1 if the save succeeded.

$rRef = $suite->rfields( [ $rRef [, $edit ] ] ) ;

$rRef is an optional reference to a rfields object to use.

$edit is a flag - if set, then the object will be in "edit" mode. Defaults to non-edit mode.

Returns a reference to a rfields object, instantiating one if required.

$rRef = $suite->rundata( [ $sess ] ) ;

$sess is an optional reference to a session object to use.

Returns a list with two references - a hash of testFields and a hash that maps fields to order.

$sRef = $suite->schema( [ $sRef ] ) ;

$sRef is an optional reference to a schema object to use.

Returns a reference to a schema object, instantiating one if required.

$suiteName = $suite->suite( [ name ] ) ;

Returns the name of the current test suite, or undef if we are not operating on a test suite.

$sdb = $suite->suiteDB( sdbh, readwrite );

sdbh is an optional handle to an existing suitedb object. That object will be registered and used from then on if it is provided.

readwrite is a boolean indicating what mode the suiteDB object should be opened in. If not provided, the default is the mode of the Suite object.

Returns a handle to the suite database.

$id = $suite->idFromUUID( uuid );

uuid is a UUID to look up.

Returns the id for the test, or undef if no such test is defined.

$tdb = $suite->testDB( [tdb [, mode] ] ) ;

tdb is an optional reference to an already opened test database.

mode is an optional flag to indicate whether it should be opened in read or write mode. The default is whatever mode the suite was opened in.

Returns a reference to a test database. If one is opened, the Suite object will remember that it needs to be released.

$vars = $suite->variables ( vars );

vars is an optional reference to a variable object. If provided, then that object is used and is saved into the associated suiteDB.

$acctH = $suiteH->accountDB(readwrite);

Returns a handle to an account database.

@sessList = $suite->activeSessions() ;
    @sessList = $suite->activeSessions(set) ;

If the set parameter is supplied, only looks at the sessions in that set. Otherwise looks at all sessions.

$ret = $suite->add(relativePath [, fromCopy ] );

Adds a file or folder at suiteRoot/relativePath to the suite database.

fromCopy is a flag that indicates we are adding as a result of a copy.

Returns 1 on success, 0 on failure.

$newID = $req->allocateID( folder ) ;

folder is a folder within the suite.

Returns the next available numeric ID for this folder. If inRequirements() is true, then operates in the requirements tree, otherwise operates in the test case tree. If the style of the associated ID field is "autonumber" then a suite-wide number is used. Otherwise, a per-folder number is used.

Returns undef if the folder does not exist.

path = $suite->allocateRemoved( inRequirements ) ;

Returns the next folder that can be created in the deleted tree.

$res = $suite->copyFile(oldFile, newFile, fromFolder);

oldFile is the path to the original file.

newFile is the path where the copy should be placed.

fromFolder is a boolean indicating if we are operating under copyFolder already. This is passed to source control operations.

Returns the name of the new file, or undef on failure.

$res = $suite->copyFolder(old, new, callBack);

old is the old folder name.

new is the new folder name.

All files and folders under old are copied into new. All appropriate source control operations are also performed.

Returns 0 on failure, and non-zero on success.

$boolean = $suite->checkSession(sessId) ;

Returns true if a session sessId exists in the suite.

$boolean = $suite->checkSet(setName) ;

Returns true if a set setName exists in the suite.

$newSessH = $suite->copySession(desc, oldSessId[, clear[, user[, updateSet [,setName] ]]]);

desc - a new description for the copy

oldSessId - the session ID to copy

clear - a boolean indicating whether to clear out any accumulated data in the new session

user - the userName of the copier (defaults to Framework::username())

updateSet - boolean to indicate whether the parent set should be told of its new child or not. Useful if we are actually copying to a new set.

setName - The real set name to use.

Creates a new test session, updates test database to reflect the session usage, and returns the handle to the newly created session.

returns undef if the creation fails.

Returns a list of sessions copied.

$suiteH->copySetGroup(oldGroup, newGroup, sessions [, callBack ] ) ;

sessions is a string that says what to do with sessions that are in copied test sets:

no dont copy sessions at all

clear copy but clear the sessions of rundata

results copy only the results

notes copy only notes

assignedto copy only assignments

all copy all data

callBack is an optional reference to a function that will be called with progress messages.

Returns a reference to a list of test sessions created as a result of the copy.

Returns undef if the oldGroup was not defined or the newGroup already exists.

$newHandle = $sh->copySuite("newname", copysets, copysessions, clear, dbmFlag, callback, copyReports);

newname is a name for the new test suite.

copysets is true if test sets are to be copied.

copysessions is true if test sessions are to be copied.

clear is "no" if the results of sessions should not be cleared.

dbmFlag is true if the data should be saved in dbm format. Otherwise it is saved in an architecture neutral "Dump" format.

callback is an optional reference to a function that will be called with progress messages.

copyReports is an optional boolean. If true, custom report definitions are copied as well. Defaults to false.

doSQL is an optional boolean. If true, then the SQL store will be updated against the new copy after the copying is complete. Defaults to false.

copySearches is an optional boolean. If true, then the saved searches will also be copied. Defaults to false.

acctDB is an optional handle to an account database. This will be handed to the newSuite object for use in synchronizing.

copyPermissions is an optional boolean. If true, then the access permissions will also be copied. Defaults to true.

newSuiteH is an optional reference to a new suite object. If this is passed in, then the tests and requirements will not be copied, but all the other items may be as requested.

returns the handler to the newly created suite, or undef of the suite cannot be copied.

$res = $suite->copyRequirement(oldreq, newreq) ;

oldreq is the name of the old requirement file.

newreq is the name for the new requirement file.

Note that if the requirements are in autonumber mode, then the new name is really used just for its path, and a name is allocated.

Returns the new name if the copy succeeded. undef if it failed.

$res = $suite->copyTestCase(oldcase, newcase) ;

oldcase is the name of the old test case file.

newcase is the name for the new test case file.

Note that if the tests are in autonumber mode, then the new name is really used just for its path, and a name is allocated.

Returns the new name if the copy succeeded. undef if it failed.

$newSessId = $suite->createSession(setId, name, desc, user, useSet, testCases, requirements);

setId - the set in which to create the session if setID is actually a HANDLE to a set object, use that set.

name - the name for the session

desc - the long description for the session

user - the userName of the copier (defaults to Framework::username())

useSet - boolean. Should the set be used to populate the session?

testCases - an arrayref of test case UUIDs to create a session from

requirements - an arrayref of requirement UUIDs to create a session from

Creates a new test session, updates test database to reflect the session usage, and returns the handle to the newly created session.

Can specify testCases or requirements but not both. Specifying either forces useSet to be 0.

returns undef if the creation fails.

$setH = $suite->createSet(name, desc, user);

name - the name for the set

desc - the long description for the set

user - the userName of the copier (defaults to Framework::username())

Creates a new test set, updates test database to reflect the set usage, and returns the handle to the newly created set.

returns undef if the creation fails.

$result = $suite->createSetGroup(name, desc, user);

name - the name for the set group

desc - the long description for the set group

user - the userName of the copier (defaults to Framework::username())

Creates a new test set group and stores its description.

Returns 1 on success, 0 on failure.

$numCreated = $suite->createRequirementsFromTests(sess, fieldMap [, $callBack ] ) ;

sess is a reference to a TestSession object with test cases to create against.

fieldMap is a reference to a hash mapping requirement field names to test case field names. During requirement creation, matching fields will be populated with data from the source test case.

callBack is a reference to a function to call periodically to track creation progress. The default is no function.

Returns the number of requirements created. Note that if there is already a requirement that references the test case, it will be skipped.

$numCreated = $suite->createTestsFromRequirements(reqColl, fieldMap [, $byDir [, $callBack ] ] ) ;

reqColl is a reference to a ReqCollection object with requirements to create against.

fieldMap is a reference to a hash of req fields and the names of test case fields they should populate.

byDir is an optional flag indicating whether a directory should be created for each requirement, or only a single test case. The default is false.

callBack is a reference to a function to call periodically to track creation progress. The default is no function.

Returns the number of test cases created. Note that if there is already a test case that references the requirement, it will be skipped.

$res = $suite->searchTest(name, rules) ;

name is the name of the test case.

rules is a reference to a hash of field names, each of which contains a search pattern and a replacement pattern.

Returns 1 if the test case matched, 0 if it did not, and undef if the test case was not available.

$suite->testCase(name);

name is the name of the test case

returns a handle to a test case object

$locked = $suite->testLocked(test) ;

test is the path to a test in the suite.

Returns true if this test is "locked".

$suite->updateSuiteDB() ;

Ensures the metadata about the test suite is up to date in the suiteDB. Note that this is only SOME of the meta data, since things like the schema are cached in suiteDB by their editors.

Returns undef if there is no SuiteDB associated with this session, 0 if the update failed, and 1 if it succeeded.

$res = $suite->updateTest(name, rules) ;

name is the name of the test case.

rules is a reference to a hash of field names, each of which contains a search pattern and a replacement pattern.

Returns 1 if the test case was changed, 0 if it was not, and undef if the test case was not available.

$hRef = $suiteH->userHash() ;

Returns a reference to a hash of data mapping user IDs to full names.

@ulist = $suite->userList( [alevel] ) ;

alevel is an optional access level. The default is the lowest level that still gives access.

Returns a list of userids that have the requested access level or better.

@ulist = $suite->userPerms( ) ;

Returns a hash of userids with access to this suite, and their access level.

$sessAryRef = $suite->removeGroup( group [, callBack ] ) ;

group is the name of a group to remove.

callBack is an optional reference to a function that will be called with progress messages.

Returns a reference to a list of removed sets and sessions, or undef if there was an error.

$suite->deleteSession(sess [user [, updateSet]]);

sess is the session to remove

user is an optional user name - defaults to the current user.

updateSet is a flag that indicates whether the corresponding set should also be updated. This defaults to true.

The session folder and all its data are moved into the deleted files tree for later cleanup.

returns 1 if successful, undef if not.

$result = $suite->deleteSet($set) ;

Removes the set named $set, as well as all of its sessions. Actually moves it into the deletedDir tree for later removal when things are cleaned up.

Returns 1 on success, undef on failure.

$desc = $suite->description( $desc )

desc is an optional description to save.

Returns the description for the test suite, if any.

$output = $suite->dirList( exclude, excludeDeep, skipLocked, incRecyc ) ;

exclude is an exact match pattern to exclude.

excludeDeep is a matter that a directory name must start with to be excluded.

skipLocked is a flag. If true, locked folders are not returned.

incRecyc is a flag. If true, foldes in the recycle tree are also included. Defaults to false.

Returns a list of folders, customized based upon the parameters passed in. Note that this method relies upon folderList, which in turn uses the inRequirements flag to learn what mode we are in.

$name = $suite->displayID( $filePath, noPath, asText, onclick ) ;
    $name = $suite->displayID( $dirPath, isReq, noPath, asText, onclick ) ;

filePath is the path to a file.

dirPath is the path to a folder. If this is a path to a folder, an additional parameter specifies whether it is a requirement folder or not.

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false.

asText is an optional boolean flag that indicates whether the content should be emitted as text only, or if it is intended for markup use. It defaults to false (markup use).

onclick is an optional javascript function that can take the UUID as a parameter. If supplied, the returned name will be wrapped in an "span" element and passed the path.

Returns the name associated with the object pointed to by path.

If in requirements mode, then this is a path relative to the requirements directory of the suite. Otherwise it is a path relative to the test cases of the suite.

$count = $suite->cleanLandfill( [ callBack, [ ignoreReferences ] ] ) ;

callBack is an optional reference to a callBack function. If provided, the callBack will be invoked periodically with progress messages.

ignoreReferences is a boolean that indicates whether files that are referenced from other, active areas of the system should be removed or not. The default is false - referenced files are NOT removed.

This method examines all files that are in the "Deleted" area and permanently removes them from the system. Files that are referenced from test sessions, test sets, active requirements, or active test cases are NOT removed unless ignoreReferences is true.

Returns the number of items permanently removed.

$suite->emptyTrash() ;

Permanently removes the files and folders in the $recycleDir tree. In reality, copies them into a the $deletedDir tree first so that they continue to be available for test sessions unless the system configuration setting saveTrash is set to 0, in which case the files are actually removed.

Returns nothing.

$fdbH = $suite->filterDB( [fdbH [, writable] ]) ;

fdbH is an optional handle to an already open filterDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a FilterDB object.

@list = $suite->folderList( [ dir ] ) ;

dir is an optional directory within the tree from which to start. If not provided, this defaults to the top level.

Returns a list of folders in user-defined order. Note that this method switches between the test and requirements trees based upon the inRequirements setting.

$locked = $suite->folderLocked(dir) ;

dir is a directory in the suite.

Returns true if this directory is "locked". A directory is locked if it or any of its parents is locked. A directory is unlocked if it or any of its parents are explicitly unlocked.

$fname = $suite->fullname(user, includeID) ;

Returns the fullname or the userID in parens if the fullname is not found. If user is a comma separated list, returns the fullnames of all users in the list.

my $count = $suiteH->maxSession() ;

Returns the highest numbered session in the suite.

$time = $suite->lastEditUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to tests in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

$time = $suite->lastFolderUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to tests in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

$time = $suite->lastReqEditUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to requirements in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

$time = $suite->lastReqFolderUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to requirements in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

$time = $suite->lastRunUpdate( [ stamp ] ) ;

Returns the timestamp of the last run status change in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

$time = $suite->lastUserPermUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to the user permissions list in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

@flist = $suite->lockedFilesAndFolders( dir );

Returns an entry per file that is locked within and beneath the directory "dir" in the suite. If dir is undefined or "", then it is the top of the suite. In any case, files in the recycle bin are silently ignored.

@slist = $suite->lockedSetsAndSessions( [ setGroup ] )

setGroup is an optional setGroup folder within the set list.

Returns a list of setGroups, sets, and sessions that are locked.

$status = $suite->lockFolder( dir, cascade )

dir is the name of a directory within the suite.

cascade says whether to do child folders or not.

Locks the folder, any test cases therein, and optionall any child folders.

Returns 1 on success, 0 on any failure (like no permission).

$suite->lockReq(reqname) ;

Locks the requirement.

$status = $suite->lockSetGroup( group, cascade )

group is the name of a set group within the suite.

cascade says whether to do child folders or not.

Locks the folder, any sets therein, and optionally any child folders.

Returns 1 on success, 0 on any failure (like no permission).

$sessRef = $suite->lockSet(setName, sessions) ;

setName is the name of a set to lock.

sessions is a boolean. If true then sessions in the set are locked as well. Defaults to false.

Returns an array reference to the list of locked sessions. Returns undef if there was an error.

$suite->lockTest(testname) ;

Locks the test case.

$status = $suite->unlockFolder( dir, cascade )

dir is the name of a directory within the suite.

cascade is a boolean that indicates whether to perform the operation on subfolders. Default is false.

Unlocks the folder, any folders therein, and any test cases therein.

Returns 1 on success, 0 on any failure (like no permission).

$suite->unlockReq(requirement) ;

Unlocks the requirement.

$status = $suite->unlockSetGroup( group, cascade )

group is the name of a set group within the suite.

cascade says whether to do child folders or not.

Locks the folder, any sets therein, and optionally any child folders.

Returns 1 on success, 0 on any failure (like no permission).

$sessRef = $suite->unlockSet(setName, sessions) ;

setName is the name of a set to unlock.

sessions is a boolean. If true then sessions in the set are locked as well. Defaults to false.

Returns an array reference to the list of locked sessions. Returns undef if there was an error.

$suite->unlockTest(testname) ;

Unlocks the test case.

$res = $suite->newFolder(name) ;

name is the name of the folder to create.

Creates the folder, possibly also creating intervening folders as needed. Uses the internal add operator to ensure that each folder is added to the source control system if there is one.

Returns 1 on success, 0 on failure.

$ref = $suite->openRequirementByName(name, writeable) ;

name is the name of a requirement case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the requirement object.

$ref = $suite->openRequirementByUUID(UUID, writeable) ;

UUID is the UUID of a requirement to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the requirement object. Returns undef if the requirement is not available.

$collPtr = $suite->openRequirementCollection(name, readWrite);

name - the collection to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the collection cannot be opened. Returns a pointer to the collection if successful.

$sessPtr = $suite->openSession(sessId, readWrite);

sessId - the session to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the session cannot be opened. Returns a pointer to the session if successful.

$setPtr = $suite->openSet(setName, readWrite);

setName - the set to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the set cannot be opened. Returns a pointer to the set if successful.

$ref = $suite->openTestCase(name, writeable) ;

name is the name of a test case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the test case object.

$ref = $suite->openTestCaseByUUID(UUID, writeable) ;

UUID is the UUID of a test case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the test case object.

$res = $suite->canRename(oldname, newname) ;

oldname is the name of the item to move.

newname is the new name for the item.

If the item to move is a folder, then find the longest item in the folder to set an upper bound.

Returns true if the rename will work. Returns false if it would not.

$res = $suite->canRecycle(name);

Name is the name of the item to recycle.

Returns true if it can be recycled, and false if not.

$state = $suite->isNumbered() ;

Uses the inRequirements state to determine which schema to query.

$state = $suite->isOutline() ;

Uses the inRequirements state to determine which schema to query.

$state = $suite->isRecycling( [ state ] ) ;

state is an optional parameter to set the state.

Returns true if we are in the middle of a recycle operation, and false if not.

$res = $suite->recycled(name) ;

Returns true if the file is in the recycle bin, and false if it is not.

$res = $suite->recycleFolder(name) ;

name is the name of the folder to recycle.

Places the folder into the "trash", possibly renaming it if there is a conflict by adding a numeric suffix to the name.

Note that when source control is enabled, some special operations have to take place:

First - it is NOT possible to get here if source control is enabled and there is no removeFolder operation. The option to remove a folder will simply not appear in the UI.

If there is a source control renameFolder operation, that is used.

If not, use copyFolder to move the tree over, then use removeFolder to wipe the original.

$status = $suite->recycleFile(file);

file is the file to recycle.

Places the file in the recycle bin, possibly renaming it to avoid a conflict.

$res = $suite->removeFile(name[, fromFolder]);

name - the name to remove

fromFolder - flag to indicate we were called from removeFolder.

Updates the test database and performs any source control operations if necessary. Note that if the item being removed is NOT in the recycle area already, it is automatically "recycled" by performing a recycleFile operation.

returns 1 if the remove succeeded, otherwise returns 0.

$res = $suite->rename(oldname, newname[, origname]);

oldname - the original name newname - the new name origname - a name to use in messages instead of oldname

Updates the test database and performs any source control operations if necessary.

Note that if autonumbering by folder is enabled, and the rename is not into the trash, then the target name is really advice on the folder, and the new file name will be auto-allocated.

Returns the new file name if the rename succeeded, otherwise returns undef.

The origname argument is used in bulk renames where in auto-outlined suites the displayID of oldname may not be correct.

$res = $suite->rename(oldname, newname [ , callBack ] );

oldname - the original name

newname - the new name

callBack - an optional reference to a function through which to report progress.

emptyingTrash - an optional flag that indicates the rename is just to empty the trash. Test / requirement counts are not adjusted in this case.

Recurses through the tree renaming the components in a folder.

returns 1 if the rename succeeded, otherwise returns 0.

Returns 1 on success.

Returns undef if the oldset was not defined or the newset already exists.

$suiteH->renameSetGroup(oldGroup, newGroup) ;

Returns 1 on success.

Returns undef if the oldGroup was not defined or the newGroup already exists.

$status = $suite->renumberTree( nameField [, callback [, folder, recursive] ] );

nameField is the name of a field into which to copy the basename of the ID of the file IFF the file did not have a numeric name to start with.

callback is an optional reference to a function that will be called as each folder is processed.

folder is an option folder to start renumbering from - only legal when numbering is by folder.

recursive is an optional flag to indicate that by folder renumbering should do this folder and all child folders.

renumberTree will walk the tree in the current user-defined order, renaming the files to be sequential. The walk is breadth first, so files in parent folders will have lower numbers than files in child folders when in suite-wide numbering mode.

Note that renumber is a transaction. It will tie up the various databases for its entire execution. It should only be called as a management option, and only when the system is quiescent.

Returns 1 on success, 0 on failure.

$rdbH = $suite->reportDB( [rdbH [, writable] ]) ;

rdbH is an optional handle to an already open reportDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a reportDB object.

$state = $suite->reqActive() ;

Returns true if requirements are in use by this test suite, and false if they are not. Note that the overarching configuration setting ATMConfig::useRequirements takes precedence using the following rules:

If useRequirements is 0, then requirements are OFF everywhere.

    If useRequirements is 1, then requirements are ON everywhere.

    If useRequirements is -1, then each suite has its own setting, with
    the default setting being OFF if there is no suite-specific setting.

$reqH = $suite->reqDB( [reqdb [, mode] ] ) ;

$path = $suite->reqDir( [subdir] ) ;

subdir is an optional directory within the requirements tree.

Returns the path to the requirements directory. If there was no REQUIREMENTS tree in the suite, silently creates one.

$locked = $suite->reqLocked(req) ;

req is the path to a requirement in the suite.

Returns true if this requirement is "locked".

$sdbH = $suite->searchDB( [sdbH [, writable] ]) ;

sdbH is an optional handle to an already open searchDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a SearchDB object.

@sessList = $suite->sessionList();
    @sessList = $suite->sessionList(set) ;
    @sessList = $suite->sessionList(undef, noSet) ;

If called with a set parameter, only returns the sessions in that set. If called with the noSet parameger, only returns the sessions that are associated with no test set.

If the set is unavailable, returns undef.

$state = $suite->sessLocked(sessNum);

state = 1 if locked, 0 if unlocked. Returns undef if the session is not found.

$desc = $suite->groupDesc( setGroup ) ;

Returns the description for a setGroup, if any. If setGroup is "" or "/", returns the description of the test suite.

@list = $suite->groupList( [ setGroup ] ) ;

Returns a list of group names. If the optional setGroup parameter is provided, then returns the list of group names that are within THAT group.

$locked = $suite->groupLocked(group) ;

Returns true if the group is locked, false otherwise.

@setList = $suite->setList( [$setGroup] ) ;

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

Returns an array of set names.

$state = $suite->setLocked(setName);

state = 1 if locked, 0 if unlocked. Returns undef if the set is not found.

$res = $suite->sync(refresh [, doSQL [, callBack ] ]);

refresh = 1 if the sessions should all be refreshed against the database too.

doSQL is a boolean - set to true if the SQL datastores should be updated as well. Defaults to true.

callBack is a reference to a function that will get called each time a new folder is traversed. The default is that there is no function. If a function reference is supplied, that function will be called with a single parameter; the name of the folder being traversed.

Updates the test database, ensuring that all the test files in the tree are included. Accesses the source control update method, so if there is source control enabled, it will synchronize from the source tree as well.

Ensures that the information in the SuiteDB is also up to date, polling the test sessions for their meta data.

returns -1 if the sync failed, otherwise returns the number of test cases (and requirements) sync'd into the database.

$state = $suite->inRequirements( boolean ) 

boolean is optional parameter to set the state. Defaults to false.

Returns the previous state.

$avail = $suite->isAvailable(operation);

Where operation is one of those operations defined in the config.pl file for source control.

Returns 1 if the operation is available, 0 if it is not.

$suite->updateReqID(name, req) ;

name is the name of the requirement to update.

req is an optional reference to a Requirement object. If one is not provided, it will be opened.

Ensures the id field matches its current location in the tree.

$suite->updateTcID(name, test) ;

name is the name of the test case to update.

test is an optional reference to a test case object for that test. If one is not provided, it will be opened.

Ensures the test case id field matches its current location in the tree.

$tableHash = $suiteH->SQL_allTables( deep ) ;

deep is an optional parameter that causes a two level hash to be returned. In this case, the top level hash is the master table name, and it contains a hash of all the tables related to that master table.

Returns a hash of table definitions. The key is the name of the table, and the value is a hash of table fields and their declarations.

Returns undef if SQL is not active for the suite.

$hashRef = $suite->SQL_getInfo() ;

Returns a reference to a hash of interesting setting values indexed by setting name. The settings retrieved include:

maxColumnsInTable
    maxColumnNameLength
    maxTableNameLength

Returns undef if SQL is not active for the suite.

$state = $suiteH->SQL_isConsistent() ;

Returns true if the SQL store is active, ready, and its table definitions are the same as what ApTest Manager things they ought to be.

$rdy = $suiteH->SQL_ready() ;

    $rdy = $suiteH->SQL_ready( [ rdyState [, actState ] ] ) ;

rdyState sets the readiness state.

actState sets the active state.

Returns the current readiness of the suite to work with its defined SQL store. Optionally sets the state.

$suiteH->SQL_renameTestCase(UUID, new)

UUID is the uuid if the test case.

new is the new "id" for the test case.

All tables that reflect the "id" in addition to the "atm_id" of a test case will be updated.

$suiteH->SQL_sync( [ callback ] ) ;

callback is a reference to an optional callback function that will get called periodically with progress messages.

SQL_sync will initialize and rebuild all tables in a related SQL datastore against the data already in the Test Suite databases. Note that this is NOT the same as a traditional "sync" operation.

$tdb->SQL_deleteSuiteInfo() ;

Returns nothing.

my $tname = $suiteH->SQL_tname;

Returns the name of the master table for this object.

$suiteH->SQL_updateSuiteInfo() ;

Updates the suiteInfo, accounts, and authentication tables.

Returns nothing.

$sdb->SQL_createTable();

Returns nothing.

$sdb->SQL_makeTables() ;

Returns nothing.

@cols = $suite->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 = $suite->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. Note that the Suite object is funny, since it uses a static collection of tables. If there are multiple suites sharing a SQL datastore, all those suites will put the data in the same tables. This only works because the table columns in this instance do not vary by suite.

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