trigger validateKey

System trigger that defines the procedural checks to validate a modified primary or candidate key.

Declaration: trigger validateKey
Applies to:

Entity

Activation: Activated during explicit or validation:
  • Explicitly, by a validation statement (validate, validateocc, or validatekey).
  • Implicitly, during a store statement.
  • Implicitly, prior to the leaveModifiedKey trigger.
  • If the Validate property is True (for candidate keys).
Default behavior: If no ProcScript is present in this trigger, there is no action; $status, $keyvalidation, and $keycheck are set to 0.
Behavior upon completion: If $status is less than zero, validation is considered to have failed and the entity-level error trigger is activated.

Description

The validateKey trigger defines the procedural checks that are done to validate a modified primary or candidate key.

Validation is performed only if the key is marked as modified ($keymod is 1) and still requires validation ($keyvalidation is 1), or if $keycheck is 1.

Because the validation statements (validatefield, validatekey, validateocc, and validate) activate the validation triggers (validate and validateKey), these statements should be used with caution within the validation triggers.

Use the function $curkey to determine the key for which the validateKey trigger was activated.

Note:  If you have more than one constraint which might cause the validateKey trigger to fail, you can return a unique (negative) value for each constraint in $status, then use the function $dataerrorcontext in the error trigger to determine the particular value of $status that activated the error trigger.

Example: Validating Keys and Error Handling

The following example uses the $curkey function to perform specific validation for each key and otherwise reports the error and context using $procerror and $procerrorcontext. 

trigger validateKey

selectcase $curkey
   case 1 ;perform validation for the primary key
   ...
   case 2 ;perform validation for candidate key #2
...
   case 4 ;perform validation for candidate key #4
...
   elsecase
      message "Error %%$procerror occurred at %%$procerrorcontext"
      message "Context: %%$dataerrorcontext"
endselectcase
end; validateKey

Validating Keys and Error Handling 2

trigger validateKey 
  findkey $entname, $curkey
  selectCase $status
    Case 0 ; key not found
      if ($foreign & SomeCondition) ; not allowed key in up entity
       return(-1)
      endif
    Case 1 ; key found on Component
      ...
  endSelectCase
  return(0)
end; validateKey

When a negative return value occurs in the validateKey trigger, the error trigger for the entity is activated with $error of 0147. You could update the error trigger as follows: 

trigger error
  selectcase $error
  case 0147; key validation failed
    message "This is not allowed"
    return -1
  elsecase
    message $text("%%$error")
  endselectcase
end; error

Related Topics