LoadPartialEntity
Description
Loads just part of a record.The LoadPartialEntity API (Application Programming Interface) method can be used to load just part of a record. Performance can be improved by skipping the extra Structured Query Language (SQL) statements to retrieve the field data for certain field types. The field types that can be excluded in this way are reference list, attachment list, and history.
Syntax
Perl
$session.LoadPartialEntity(entDefName, displayName, list);
$session.LoadPartialEntityByDbId(entDefName, dbId, list);
- Identifier
- Description
- entDefName
- The type name of the entity to be partially loaded.
- displayName
- The display name of the entity to be partially loaded.
- list
- Controls what fields are excluded.
- dbID
- The dbid of the entity to be partially loaded.
The entDefName , displayName, and dbID parameters are used to identify the record type and display name or DBID of the record to be loaded. These parameters are the same as for the GetEntity and GetEntityByDbId APIs. The list parameter contains a sequence of directives that are used to control what fields will, or will not, be loaded. Only some field types can be excluded when loading the record.
The list must contain field names or type directives. A type directive is used to exclude, or include, all fields of a specified type. The list is processed in order. Once a type directive is processed, the subsequent field names must name fields of that type.
Type Directives
A type directive is a string value that begins with either '+' or '-' followed by a field type designation. The designation can be either numeric or a string name. A special value of "all" is accepted to designate all field types. The numeric value is accepted because the HCL Compass API definition (in CQPerlExt.pm) only defines numeric values for field types. See examples below. The string name of the field type matches the name of the API constant, but without the "CQ_" prefix, and it is not case sensitive.
A leading '+' or '-' means that all fields of the given type will be included, or excluded. These type directives establish a mode for the field names to follow. The names are taken as the opposite of the mode established for the field type. Those names are considered as exceptions to the rule established for the field type. If more than one type directive is given for a particular field type, only the last one will have any effect. Since each type directive says to either include or exclude all fields of that type, it will override any directive for that type and the associated field names for that type that came before it.
Examples
For example, the following two list items cause the load to exclude all reference list fields except for the "SubTasks" field:
"-$CQPerlExt::CQ_REFERENCE_LIST", # exclude all reference list fields
"SubTasks" # ... but do load field "SubTasks"
This is the equivalent of a specification using the string name for the field type:
"-Reference_List", # exclude all reference list fields
"SubTasks" # ... but do load field "SubTasks"
The following is an example of when a script needs to check if the next action to be performed on a record is past due. The check requires only two fields that represent that condition:
"-all", # exclude all fields
"Status", # ... but do load field "Status"
"DueDate" # ... and field "DueDate"
The following example is for a case where only attachment fields are needed. Using "-all" excludes all fields that can be excluded, and the next entry makes sure that all attachment fields are loaded.
"-all", # exclude all fields
"+$CQPerlExt::CQ_ATTACHMENT_LIST" # ... but include all attachment lists
More details about special directives, error handling, and how the loaded entity is shared, can be found in the technote How to Improve Performance for Perl Scripts that Load Records.