raise exception(1) — Commands
Digital
NAME
RAISE EXCEPTION − a statement that raises an exception in a task
SYNOPSIS
[<label-name>:] RAISE EXCEPTION
{ CLASS { <class-identifier> | <class-number> } |
CODE { <message-identifier> | <message-number> }
[ IN { <message-group-uuid> | <message-group-name> } ]
} [ WITH ROLLBACK TRANSACTION ] ;
PARAMETERS
•label-name
An internal unqualified identifier associated with the statement, for use in flow control operations.
•class-identifier
One of the standard, predefined exception classes. The exception classes and their equivalent class-number values are:
FATAL-TIMEOUT-FAULT -1 ENV-INVOCATION-ERROR 1
FATAL-EXECUTION-FAULT -2 TXN-FAILURE-ERROR 2
AP-INVOCATION-FAULT -3 AP-INCOMPLETE-ERROR 3
ENV-INVOCATION-FAULT -4 TXN-TIMEOUT-ERROR 4
AP-RESPONSE-FAULT -5 TXN-INCOMPLETE-ERROR 5
AP-EXECUTION-FAULT -6 ENV-EXECUTION-ERROR 6
ENV-EXECUTION-FAULT -7 REQUEST-TIMEOUT-ERROR 7
AP-PROCESSING-FAULT -9 INVALID-INPUT-ERROR 8
ENV-UNSPECIFIED-FAULT -10 NO-OUTPUT-ERROR 9
Faults indicate exceptions that require modifying the source file or environment information. Fault values are expressed in negative numbers.
Errors indicate exceptions for operations that may be successful if retried, without modifying a source file or environment information. In some cases, data must be modified. Error values are expressed in positive numbers.
•class-number
Either an integer workspace field or an integer literal giving a value assigned to an exception class.
•message-identifier
A name associated with the message number, class identifier, and message text in a message group definition associated with this task definition. Use either the message identifier or the message number to raise the exception.
•message-number
Either an integer workspace field or an integer literal giving the integer value assigned to a message identifier by VALUE IS in the message group definition. Use either the message identifier or the message number to raise the exception with CODE.
•message-group-uuid
Either a UUID-workspace field or a UUID-string literal that uniquely identifies the message group.
If you do not specify a uuid value, the default value is zero.
•message-group-name
An unqualified external identifier giving the name of a message group in which the application-defined exception code is stored.
DESCRIPTION
An exception transfers control to the appropriate exception handler, if any is specified. For a task with the RESTARTABLE task attribute, a RAISE EXCEPTION statement that raises a transient transaction exception causes the system to restart the transaction (if the restart limit is not exceeded and the transaction block in which the exception is raised has no nontransactional exchange operations).
Raise an exception with either the class or the code:
•If you specify EXCEPTION CLASS, ACMSxp checks that the exception class is one of the standard predefined exception classes, and sets the exception code to 0.
•If you specify EXCEPTION CODE, ACMSxp provides a more detailed classification of an exception condition, based on the exception code defined in the message group definition, or by ACMSxp.
IN specifies either the exception group for a system-defined exception code or the message group for an application-defined exception code. If IN is omitted, the exception code must belong to a message group with a UUID of zero.
The normal execution flow for RAISE EXCEPTION is to determine the class and code of the exception to be raised and:
•If ROLLBACK is specified, complete the RAISE EXCEPTION with a permanent transaction exception with that class and code.
•If ROLLBACK is not specified, complete the exception with an exception class with the class, code, and transaction exception type associated with the raised class.
Deviations from the normal execution flow occur when an exception occurs. The RAISE EXCEPTION completes with that exception.
RELATED INFORMATION
Syntax: exception(1), exception_handler(1), reraise_exception(1), restart_transaction(1)