GetEntityDefOfDbId

Description

Provides ‘Find Record’ functionality. Returns the EntitiyDef object for the given record database ID (DBID). The method requires you to specify the EntityDef type and optionally the EntityDef names in which to search for the DBID.

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 displayName 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 display name instead of its database ID, use the GetEntityDefOfName method.

Syntax

VBScript

session.GetEntityDefOfDbId(db_id, entitydef_names,entitydef_type)

Perl

$session->GetEntityDefOfDbId(db_identitydef_names, entitydef_type);

Identifier

Description

session

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

db_id

A Long that is the number used by the database to identify the record for which the EntityDef is to be determined.

The unique id of the record (Entity).

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 displayName 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->GetEntityDefOfDbId()...
my($DbId) = $ARG{'DBID'};
eval { $CQEntityDefOfDbId = $CQSession->GetEntityDefOfDbId($DbId, $entDefNames, $ARG{'ENTTYPE'}); };
# exception handling goes here...

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

# Get entity...