Performance considerations for using hooks

HCL Compass supports the use of either VBScript and Perl for writing your custom hook code. However, there are performance and functional trade-offs that should be considered when choosing the scripting language and the types of operations to use in hooks. Although this is not an exhaustive discussion on the topic, the following guidelines should be applied to any schema modifications.

  • HCL Compass Web

    For any HCL Compass systems that are supporting a mix of client platforms, there are performance benefits of using New HCL Compass Web.

    • Version 2003.06.13 and later

      New HCL Compass Web can be deployed on Windows™, the UNIX™ system, or Linux™ systems.

    • Version 2003.06.12 and earlier

      Any HCL Compass Windows client, including the HCL Compass Web server, can execute hooks written in either VBScript or Perl. However, the HCL Compass clients for the UNIX system or Linux can execute only Perl scripts. Therefore, if a HCL Compass deployment requires any clients for the UNIX system or Linux, hooks must be written in Perl.

  • Database Access

    Accessing the database is typically the most time consuming operation a hook performs. Examples of operations that require database access are:

    • LoadEntity and GetEntity operations

      Retrieving an entity (record) requires at least one query of the database for the primary record, plus one query for each REFERENCE_LIST field. Entities are retrieved explicitly through Session methods such as GetEntity or LoadEntity, but can also be retrieved implicitly by accessing the field value of a REFERENCE field. The following example implicitly loads the entity referred to by the product field, and then retrieves the value of the component field from the loaded product record:

      
      $component = $entity->GetFieldValue("product.component")->GetValue();
      

      The time to load an entity is determined by the complexity of the schema, primarily by the number of reference list fields in the selected entity. In many instances, if only a subset of an entity's fields are required, it is more efficient to query for those field values instead of retrieving the entire entity.

    • Queries

      Although more efficient than retrieving entire entity records, queries still require database access, and therefore have an impact on your overall schema performance. Every effort should be made to minimize the number of database round-trips. For instance, rather than running the same query multiple times at various locations in the hook code, a query can be executed once, and the ResultSet values can be cached in a Session variable (for VBScript). Also, retrieve only the fields that are essential for each record. Avoid specifying multiline text fields in query result sets, as this requires an additional database round-trip for each multiline text field to be retrieved.

    • Choice lists with the Recalculate Choice List option set

      When you choose the Recalculate Choice List option in the properties of a choice list, the hook code required to repopulate the valid list of choices is executed each time any other field of the record changes value. This has the potential to cause a large amount of unnecessary query traffic to and from the database. A more efficient method to ensure that the choice list is valid is to determine the other fields that can affect the values in this choice list, and force the choice list to be recalculated only when those field values change.

      For example, if you are collecting data in an Automobile record you might have a field for the Manufacturer of the automobile, and another field for the Model. The valid list of choices for the Model field depends only on the Manufacturer selected. The inefficient method of ensuring that the choice list for the Model field is always valid is to select Recalculate Choice List for this field. Instead, you can write a field value changed hook for the Manufacturer field that invalidates the choice list for the Model field. See the InvalidateFieldChoiceList example for more information on using this method.

  • Cascading Hooks

    Cascading hooks are caused by having several dependent or nested relationships between fields. Consider the automobile Manufacturer and Model dependency discussed earlier in this section. Extending that example, suppose that after a Model is selected, the list of valid choices for Body Style or Color or Engine could change. It is easy to see how changing one field value on a form could cause a cascade of hooks to be executed and re-executed for the other fields. The depth of these nested field relationships should be minimized, and care should be taken in the implementation of the schema in order to avoid unnecessary or redundant execution of hook code. For examples, see the GetFieldStringValues method and other related methods.

  • AdminSession objects

    Getting AdminSession objects has an impact on performance and there may be alternatives for retrieving data. For example, rather than using the AdminSession object and underlying User object and Group object methods to retrieve user or group information, you can create queries for User and Group records (stateless record types) that are in a user database.

    If you must use an AdminSession object, you can cache it in a Session variable (VBScript only) instead of creating new AdminSession objects for each login, or hook invocation that requires it. For Perl, you can store a collection of strings and then parse them. Additionally, if the data you retrieve through the AdminSession object is not changing, then you can cache the data as values in Session variables (NameValue pairs).
    Note: When you are finished with the session, you should clear the session variable that stored the cached object.