Raise custom messages

The mi_db_error_raise() function can raise exceptions with custom messages, which DataBlade® modules and UDRs can store in the syserrors system catalog table. The syserrors table maps these messages to five-character SQLSTATE values.

To raise an exception whose message text is stored in syserrors, you provide the following information to the mi_db_error_raise() function:
  • A message type of MI_SQL
  • The value of the SQLSTATE variable that identifies the custom exception
  • Optionally, values specified in parameter pairs that replace markers in the custom exception message
When you pass the MI_SQL message type to the mi_db_error_raise() function, the function raises an MI_Exception event whose error descriptor contains the following information:
Error descriptor field Warning Runtime error
Exception level MI_MESSAGE

(If the SQLSTATE value has a class code of "01")

 MI_EXCEPTION

(If the SQLSTATE value has a class code of "02" or greater)
SQLSTATE value (3rd argument) Specified warning value: "01xxx" Specified error value: "xxxxx"

(class code of "02" or greater)
Message text Associated warning text from syserrors table Associated error text from syserrors table
If any exception callback is registered for the same connection, the DataBlade API sends this error descriptor to the callback when the MI_Exception event is raised. For example, assume that the following predefined error message is under an SQLSTATE value of "03I01" in the syserrors table: 
Operation Interrupted.
The following call to mi_db_error_raise() sends this predefined error message to a registered (and enabled) callback that handles the MI_Exception event:
mi_db_error_raise (conn, MI_SQL, "03I01", NULL);

The exception level for this exception would be MI_EXCEPTION because any SQLSTATE value whose class code is greater than "02" is considered to represent a runtime error. If no such callback was registered (or enabled), the database server would take its default exception-handling behavior.

If the SQLSTATE value had a class code of "01", mi_db_error_raise() would raise a warning instead of an error. The following mi_db_error_raise() call raises an MI_Exception event whose exception level is MI_MESSAGE: 
mi_db_error_raise(conn, MI_SQL, "01877", NULL);
When this exception is raised, execution continues at the next line after this call to mi_db_error_raise().
Tip: Both of the preceding mi_db_error_raise() examples specify NULL as the last argument because neither of their syserrors messages contains parameter markers.