Record scripts

Record scripts are a generic form of hook that are called in response to an event on a form or from other hooks. You can write a script that performs custom behavior in the context of a record. The scripts run in the context of the currently selected record. A record-script subroutine is specific to one record type.

Typically, record scripts are used to implement an action that is performed in response to a click event on a push button or on a context menu item that is associated with a particular field on a form. For example, a record script can send data about the current record to another system.

You can run a record script in three ways:

• Associate a record script with a form control, either a button or a context menu.
• Use an action. Create a Record_script_alias action and associate it with a record script. When the user selects the action, the record script runs immediately. To update the current record from within such a script, begin an action in the script by using the Rational ClearQuest API EditEntity method in the session object.
• Call a record script from within another script or hook by using the Rational ClearQuest API FireNamedHook method in the entity object.

The following example shows the Visual Basic record script syntax:

 Function RecordName_HookName(param) 
   ' param As Variant 
   ' RecordName_HookName As Variant 
   ' ...
 End Function 
 

When calling a record script from another hook, the parameter you pass into the hook is a Variant that contains the appropriate data. If the hook returns information to the calling hook, return that information in a Variant.

When associated with a form control, the parameter passed into the method contains an instance of the EventObject class. This instance contains information about the event that caused the hook to be called. (See Form control events.) Rational ClearQuest software does not expect a return value from record scripts when they are associated with form controls. A non-null return value from a record hook is interpreted as an error and can be viewed in a message box by the Rational ClearQuest client.

Record scripts can be associated with push buttons, text fields, and lists. When associated with a button, clicking the button causes the hook to run. When associated with text fields and list-related controls, the hook is added to the context menu for the control.

You can also associate a record script with an action whose type is RECORD_SCRIPT_ALIAS. This association allows you to put a custom button on the Action menu of a Rational ClearQuest form.