Logging on to a user database

Once you've created a Session, you can get a list of the accessible databases and must then provide logon credentials to logon to a user database.

About this task

To protect your databases from unauthorized users, you must log on to a database before accessing its records. For hooks, this user authentication is handled automatically by the Rational® ClearQuest® client application. However, external applications must log on programmatically by using the Session object.

To determine which database to log on to, and to perform the log on, follow these steps:

Get a list of the databases associated with a schema repository by calling the GetAccessibleDatabases method of the Session object. This method returns a collection of DatabaseDesc objects, each of which contains information about a single user database.
Use methods of the DatabaseDesc object to get specific database information such as the name of a database or the database set (a schema repository and its associated databases) to which a database belongs.
Log on to a database by calling the UserLogon method of the Session object.

The UserLogon method takes four arguments.

$CQsession->UserLogon(login_name, password, database_name, database_set_name);

All arguments are strings:

login_name
User login name.
password
User password.
database_name
Name of a database within a schema repository.
database_set_name
Name of the database set. If you are using the default, the database_set string can be set to empty ("").

For example:

$CQSession->UserLogon("admin", "", "SAMPL", "");

In the following code example, a user (admin) gets the accessible databases and logs in to a database named perl2:

require CQPerlExt; 
$CQsession = CQSession::Build();  

#Start a session 
$sessionObj = CQSession::Build(); 

#Get a list of accessible databases 
$databases = $sessionObj->GetAccessibleDatabases("MASTR", "admin", ""); 
$count = $databases->Count(); 

$sessionObj->UserLogon("admin", "", "perl2", "");  

#For each accessible database, 
# get database name and login as joe with password gh36ak3: 
for($x=0;$x<$count;$x++)
   { 
     $db = $databases->Item($x); 
     $dbName = $db->GetDatabaseName(); 
     # Logon to the database 
     $sessionObj->UserLogon( "joe", "gh36ak3", $dbName, "" ); 
     #... 
   } 

# You can also ise the GetSessionDatabase method rather than the GetAccessibleDatabases method
$dbDesc = $sessionObj->GetSessionDatabase();  

# The GetSessionDatabase method returns information about the database that is being accessed 
# in the current session. This method differs from the GetAccessibleDatabases method in that it 
# returns the DatabaseDescription object associated with the current session. You can only call
# this method after the user has logged in to a particular database.


print "DB name = ", $dbDesc->GetDatabaseName(), "\n";  
print "DB set name = ", $dbDesc->GetDatabaseSetName(), "\n";  
print "DB connect string = ", $dbDesc->GetDatabaseConnectString(), "\n";  
print "User login name = ", $sessionObj->GetUserLoginName(), "\n";  
print "User full name = ", $sessionObj->GetUserFullName(), "\n";  
print "User email = ", $sessionObj->GetUserEmail(), "\n";  
print "User phone = ", $sessionObj->GetUserPhone(), "\n";  
print "Misc user info = ", $sessionObj->GetUserMiscInfo(), "\n";  
print "User groups: \n";  
$userGroups = $sessionObj->GetUserGroups();  
if (!@$userGroups) 
     {  # Code to handle if no user groups exist 
        print "This user does not belong to any groups\n"; 
     }  
else 
     {  # Print out all groups 
        foreach $groupname (@$userGroups) 
             { print "Group $groupname\n"; }
     }  
CQSession::Unbuild($sessionObj);

Lesson checkpoint

Now that you've learned how to use the Rational ClearQuest API to get a session and log in to a database, you can begin learning how to perform actual Rational ClearQuest client use cases, such as running and creating queries, charts, and reports, and viewing, modifying, and creating records.

< Previous | Next >