FORM_SUCCESS Built-in
Description
Returns the outcome of the action most recently performed during the current Runform session.
Outcome
|
Returned Value
|
success
|
TRUE
|
failure
|
FALSE
|
fatal error
|
FALSE
|
Syntax
FUNCTION FORM_SUCCESS;
Built-in Type unrestricted function
Return Type:
BOOLEAN
Enter Query Mode yes
Parameters
None.
Usage Notes
- Use FORM_SUCCESS to test the outcome of
a Built-in to determine further processing within any trigger. To get the
correct results, you must perform the test immediately after the action executes.
That is, another action should not occur prior to the test. "Another
action" includes both Built-ins and PL/SQL assignment statements. If
another action occurs, FORM_SUCCESS may
not reflect the status of the Built-in you are testing, but of the other,
more recently executed action.
- FORM_SUCCESS should not be used to test
whether a COMMIT_FORM or POST
Built-in has succeeded. Because COMMIT_FORM
may cause many other triggers to fire, when you evaluate FORM_SUCCESS
it may not reflect the status of COMMIT_FORM
but of some other, more recently executed Built-in. A more accurate technique
is to check that the SYSTEM.FORM_STATUS
variable is set to QUERY after the operation
is done.
- On Microsoft Windows, when using HOST
to execute a 16-bit application, the FORM_SUCCESS
Built-in will return TRUE whether the application
succeeds or fails. This is a Microsoft a Win32 issue. 32-bit applications
and OS commands will correctly return TRUE
if executed sucessfully and FALSE if failed.
Invalid commands will return FALSE.
FORM_SUCCESS Examples
/*
** Built-in: FORM_SUCCESS
** Example: Check whether the most-recently executed Built-in
** succeeded.
*/
BEGIN
/*
** Force validation to occur
*/
Enter;
/*
** If the validation succeeded, then Commit the data.
**
*/
IF Form_Success THEN
Commit;
IF :System.Form_Status <> 'QUERY' THEN
Message('Error prevented Commit');
RAISE Form_Trigger_Failure;
END IF;
END IF;
END;
Related topics
About Evaluating the Success or Failure of Built-ins
FORM_FAILURE Built-in
FORM_FATAL Built-in