FireNamedHook

Description

Executes a named hook (record script) of this record's EntityDef Object.

You can use this method to execute a record script at runtime. Record scripts are routines you define and are specific to a particular record type. You can use record scripts in conjunction with form controls or you can call them from other hooks. You define record hooks using HCL Compass Designer. The syntax for record scripts is as follows:

Function EntityDefName_RecordScriptName(param)
   ' param as Variant 
   ' EntityDefName_RecordScriptName as Variant 

   ' Hook program body 
End Function 

You cannot use this method to execute a field or action hook of a record. Neither can you execute a global hook, except indirectly from the record script.

You can call this method on an Entity object regardless of whether or not it is editable. However, if your script attempts to modify the Entity object, either your code or the hook code must first call EditEntity method to make the Entity object editable.

If your script accepts any parameters, put all of the parameters in a single Variant (for Visual Basic) and specify that Variant in param. The script must be able to interpret the parameters passed into it. Upon return, the script can similarly return a Variant with any appropriate return values.

For Perl, you can include multiple parameters by concatenating simple string values with a non-printing character as a separator (such as newline). This String can then be decoded with the built-in split operator.

Syntax

VBScript

entity.FireNamedHook scriptName, param 

Perl

$entity->FireNamedHook(scriptName, param); 

Identifier

Description

entity

An Entity object representing a user data record. Inside a hook, if you omit this part of the syntax, the Entity object corresponding to the current data record is assumed (VBScript only).

scriptName

A String containing the name of the hook to execute.

param

For Visual Basic, a Variant containing the parameters you want to pass to the hook.For Perl, a String containing the parameters you want to pass to the hook.

Return value

A String indicating the status of calling the hook. If the hook executes successfully, this method returns an empty string (""), otherwise the returned string contains a description of the error.

Examples

VBScript

' Execute the hook "MyHook" with the specified parameters

Dim params(1) 

params(0) = "option 1" 

params(1) = "option 2" 

returnValue = entity.FireNamedHook("MyHook", params) 

Perl

# Execute the hook "MyHook" with the specified parameters

$params = "option 1\noption 2";

$returnValue = $entity->FireNamedHook("MyHook",$params);



# In the hook, split them like this:

my $param = shift;

my @params = split '\n', $param;