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.