$keycheck

Indicate whether a specified primary or candidate key should be validated.

$keycheck(Entity, KeyNumber)

$keycheck(Entity, KeyNumber) = Expression

set | reset  $keycheck(Entity, KeyNumber)

Example: $keycheck("CUSTOMER", 1)= 1

Parameters

Parameters
Parameter Data Type Description
Entity String Entity name
KeyNumber Numeric Key identifier; the value will be truncated to form an integer.
  • 1, the primary key
  • 2, 3, 4, and so on, the number that identifies a candidate key that has been defined for Entity.

Return Values

Values returned in $keycheck
Value Meaning
0 Key checking is not enabled.
1 Key checking is currently enabled.

 

Values returned in $status when a value is assigned to $keycheck
Value Meaning
"" Key checking could not be enabled because an error occurred. $procerror contains the exact error.
1 key checking was successfully enabled.

If an error occurs, $procerror contains a negative value that identifies the exact error.

Values of $procerror Commonly Returned Following this Function
Value  Error constant Meaning
-1102 <UPROCERR_ENTITY> The entity name provided is not a valid name or the entity is not present in the component structure.
-1104 <UPROCERR_KEY> The specified key is not valid; for example, the key number was out of range.
-1128 <UPROCERR_NOT_A_KEY> The specified key is an index.

Use

Allowed in all component types, except self-contained Reports.

Description

The $keycheck function returns a value that indicates whether the developer intends for validation to be carried out for the specified key the next time that it can occur. If $keycheck indicates that validation is demanded, the validation is performed regardless of whether validation is actually required. (Validation is required when both $keymod and $keyvalidation are 1, indicating that the key has been modified, but has not yet been validated.)

Validation can occur when the user leaves all fields of the key (for example, with ^NEXT_FIELD, ^PREV_FIELD, or a mouse click); when an explicit validation statement is encountered (for example, validatekey); or when a store statement is encountered. It includes syntax checks on the fields comprising the key, activation of the validateKey trigger, and, in forms only, activation of the leaveModifiedKey trigger. After validation completes, $keycheck is set to 0.

You can also use $keycheck as the target in the left-hand side of an assignment. Set $keycheck to 1 to require checking for the specified key; set it to 0 to let Uniface take responsibility for validation. For example: 

$keycheck = !$keycheck

Because $keycheck is essentially a Boolean function, when Expression evaluates to a non-zero value, $keycheck becomes 1.

Checking for Keys

The following example shows this function being used in the getFocus trigger of an entity: 

trigger getFocus
   $keycheck(CUST_NUMBER.CUSTOMER, 1)= 1 ; check of primary key needed
   set $keycheck(CUST_NUMBER.CUSTOMER, 2) ; check of candidate key needed
end; getFocus

Related Topics