findkey
Check if the key value of an entity exists.
findkey {Entity,KeyNumber}
Example: findkey $entname, 1
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| Entity | String | Name of the Entity where the key is to be located. |
| KeyNumber | Number | Value that identifies the key to be
located; whole (integer) number; the value will be truncated to form an integer.
|
Return Values
| Value | Description |
|---|---|
-1
|
An error occurred. $procerror contains the exact error. |
0
|
Primary or candidate key, KeyNumber, of Entity does not exist. |
1
|
Primary or candidate key,
KeyNumber, of Entity already exists in the component.
$result contains the occurrence number. |
2
|
Primary or candidate key, KeyNumber, of Entity already exists in the database. |
| Value |
Error constant |
Meaning |
|---|---|---|
-2 through
-12 |
<UIOSERR_*>
|
Errors during database I/O. |
-16 through
-30 |
<UNETERR_*>
|
Errors during network I/O. |
-1128
|
<UPROCERR_NOT_A_KEY>
|
The key number specified is an index. |
-1102
|
<UPROCERR_ENTITY>
|
The entity name provided is not a valid name or the entity is not painted on the component. |
-1104
|
<UPROCERR_KEY>
|
The key number provided is not valid; for example, the key number was out of range. |
Use
Allowed in all component types.
Description
The findkey statement checks whether the values of the fields that make up the specified KeyNumber in Entity exist, either in the component or in the database. No validation is performed; only a check for the existence of the key.
Unlike the retrieve/o statement, which provides additional functionality such as repositioning and recovering removed occurrences, findkey only checks for the existence of a key.
The findkey statement is especially useful in the validateKey trigger, while retrieve/o should be used in the leaveModifiedKey trigger. The findkey statement checks for existence of a specified key, referred to by its key number, while retrieve/o looks for the ‘first’ complete key, using the order in which the keys are defined. This means that retrieve/o only works for candidate keys if the primary key data is not available.
If the arguments are omitted, findkey looks for the primary key of the current entity. This is equivalent to the following statement:
findkey $entname, 1
The following example uses the findkey statement:
findkey $entname, $NEWKEYVALUE$
