GetEntityDefOfName

Description

Provides Find Record functionality. Returns the EntitiyDef object for the given record display name. The method requires you to specify the EntityDef type and optionally the EntityDef names in which to search for the display name.

The returned EntityDef type must be checked in order to determine which record type was matched since the entDefNames array allows searches in multiple record types. Also, if ANY_ENTITY is used as the entityDeftype argument, you must determine whether a stateful (REQ_ENTITY) or stateless (AUX_ENTITY) record was returned.

You can call either GetEntityDefOfName or GetEntityDefOfDbId to find out if an entity with the given display name or DBID exists in the user database. Once the EntityDef is known, the entity can be obtained by calling the GetEntity method of the Session object.

To request the record type using its database ID instead of its display name, use GetEntityDefOfDbId .

For more information on display names and unique keys, see Record types Record types .

Syntax

VBScript

session.GetEntityDefOfName(display_name, entitydef_names,entitydef_type ) 

Perl

$session->GetEntityDefOfName(display_name, entitydef_names,entitydef_type); 

Identifier

Description

session

The Session object that represents the current database-access session.

display_name

For stateful (REQ) record types, the display name should be the visible ID of the record (for example, "DEF00013323"). For stateless (AUX) record types, the display name is the unique key fields.

entitydef_names

Identifies the names of the record types to use in searching for the desired record.

For Visual Basic, a Variant containing an array of strings. Each String contains the name of an EntityDef.

For Perl, a reference to an array of strings. Each String contains the name of an EntityDef.

The names of the EntityDefs are used to search for the entity identified by the display name or DbId. This list of EntityDef names is iterated and processed in the order given. If any of the EntityDef names provided in the entDefNames argument is invalid, an exception is thrown that identifies the invalid name. If an empty array value is provided, all EntityDef types defined in the schema are used, with the search order being from most frequently found EntityDef searched first to the least found EntityDef being searched last.

entitydef_type

A Long that identifies an EntityType enumerated constant (REQ_ENTITY, AUX_ENTITY, or ANY_ENTITY). When ANY_ENTITY is used, first the REQ types are checked and if there is no match, the AUX types are checked.

Return value

Returns the EntitiyDef object corresponding to the requested record if the entity is found, or NULL if the entity is not found. Throws an exception if an invalid EntityDef name is included in the entDefNames argument.

Example

Perl

use CQPerlExt; 

 # Build session...
 # Log in...'Session UserLogon method'

 # Determine the array of Entity Def Names for searching...
 eval { $entDefNamesDB = $CQSession->GetEntityDefNames(); };

 # Sort the list of entity def names returned from GetEntityDefNames()
 @entDefNamesDBsorted = sort @$entDefNamesDB;
 $entDefNamesDBsorted = \@entDefNamesDBsorted;
 # EntityDef Names can be supplied by the user. For example:
 # @entDefNamesUser = ($ARG{'EDEF1'},$ARG{'EDEF2'},$ARG{'EDEF3'});
 # $entDefNamesUser = \@entDefNamesUser;
 # if using user supplied EntityDef Names for searching then
 # $entDefNames = $entDefNamesUser;
 # else use all DB EntityDef names for searching:
 $entDefNames = $entDefNamesDBsorted;

 # Call CQSession->GetEntityDefOfName()...
 #my($dName) = substr($ARG{'DATABASE'}.$ARG{'RECORDNAME'}, 5);
 my($dName) = $ARG{'ID'};
 eval { $CQEntityDefOfName = $CQSession->GetEntityDefOfName($dName, $entDefNames, $ARG{'ENTTYPE'}); };
 # exception handling goes here...

 # Get the Entity Def Name of the record...
 eval { $CQEntityDefName =  $CQEntityDefOfName->GetName(); };
 # exception handling goes here...

 # Get entity...