The mi_tab_check_msg() function

The mi_tab_check_msg() function sends messages to the oncheck utility.

Syntax

mi_integer mi_tab_check_msg(MI_AM_TABLE_DESC *tableDesc,
   mi_integer msg_type, 
   char *msg[, marker_1, ..., marker_n])
tableDesc
Points to the descriptor for the table that the oncheck command line specifies.
msg_type
Indicates where oncheck should look for the message.

If msg_type is MI_SQL, an error occurred. The syserrors system catalog table contains the message.

If msg_type is MI_MESSAGE, the pointer in the msg argument contains the address of an information-only message string.

msg
Points to a message string of up to 400 bytes if msg_type is MI_MESSAGE.

If msg_type is MI_SQL, msg points to a five-character SQLSTATE value. The value identifies an error or warning in the syserrors system catalog table.

marker_n
Specifies a marker name in the syserrors system catalog table and a value to substitute for that marker.

Usage

When a user initiates the oncheck utility, the database server invokes the am_check purpose function, which checks the structure and integrity of virtual tables. To report state information to the oncheck utility, am_check can call the mi_tab_check_msg() function.

The syserrors system catalog table can contain user-defined error and warning messages. A five-character SQLSTATE value identifies each message.

The text of an error or warning message can include markers that the access method replaces with state-specific information. To insert state-specific information in the message, the access method passes values for each marker to mi_tab_check_msg().

To raise an exception whose message text is stored in syserrors, provide the following information to the mi_tab_check_msg() 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

The access method can allocate memory for messages or create automatic variables that keep their values for the duration of the mi_tab_check_msg() function.

The DataBlade® API mi_db_error_raise() function works similarly to mi_tab_check_msg(). For examples that show how to create messages, see the description of mi_db_error_raise() in the Informix® DataBlade API Programmer's Guide.
Restriction: Do not use msg_type values MI_FATAL or MI_EXCEPTION with mi_tab_check_msg(). These message types are reserved for the DataBlade API function mi_db_error_raise().

Return values

None

Related topics

See the description of:
  • DataBlade API function mi_db_error_raise() in the Informix DataBlade API Programmer's Guide, particularly the information about raising custom messages