Using Session variables

Session variables are hook variables that are global to the entire logon session. This means you can set the session variable in any type of hook, and read it later on, again in any type of hook. The value persists for the whole session.

Rational® ClearQuest® supports the use of sessionwide variables for storing information. After you create sessionwide variables, you can access them through the current Session object using functions or subroutines, including hooks, that have access to the Session object. When the current session ends, all of the variables associated with that Session object are deleted. The session ends when the user logs out or the final reference to the Session object ceases to exist.

In order to:

• Access sessionwide variables, use the NameValue method of the Session object.
• Create a new variable, pass a new name and value to the NameValue method. If the name is unique, the Session object creates a new entry for the variable and assigns to the variable the value you provide. If the name is not unique, the Session object replaces the previous value with the new value you provide.
• Check whether a variable exists, use the HasValue method of the Session object.

The following example shows how to create a new variable and return its value. This example creates the named variable "Hello" and assigns the value "Hello World" to it.

• Perl example:

  # You can use $session instead of defining
  # $curSession = $entity->GetSession();
  
  $myValue = "Hello World"; 
  
  # Create and set the value of the "Hello" variable
  $session->SetNameValue("Hello", $myValue);
  
  # Get the current value
  $newValue = $session->GetNameValue("Hello");
  
  # Optional
  
  $session->OutputDebugString($newValue);

• VBScript example:

  Dim myValue 
  curSession = GetSession()
  
  myValue = "Hello World" 
  
  ' Create and set the value of the "Hello" variable
  curSession.NameValue "Hello", myValue
  
  ' Get the current value
  Dim newValue
  newValue = curSession.NameValue("Hello")

Consider the following example in VBScript. If you want to find out the current action name in a field validation hook, you can use the GetActionName method, or use a session variable.

In every action initialization hook, the current action is passed in the parameter, actionname. You can set a session variable, called ActionName to the value in actionname with the following code:

set session = GetSession
session.NameValue "ActionName", actionname

Then, in the field validation hook, you can retrieve the current value of the session variable ActionName into actionname with:

set session = GetSession
actionname = session.NameValue("ActionName")
' ...

Using VBScript, you can also store objects in a session variable. Note that you use set to store objects. For example:

set sessionObj.NameValue "Obj", object

or

set sessionObj.NameValue "CalendarHandle", param.ObjectItem

In the above example, param is the parameter to a record script hook and contains an object handle. See NameValue, HasValue, ObjectItem, and Understanding record scripts for more information.