MESSAGE statement

Description

Displays a message.

Syntax

MESSAGE expression, ...
[ TYPE { INFO | ACTION | WARNING | STATUS } ]
[ TO {CONSOLE | CLIENT [ FOR { CONNECTION conn_id | ALL } ] | LOG } 
[ DEBUG ONLY ] ]

conn_id : integer

Parameters

Examples

Example 1

• The following procedure displays a message on the server message window:

CREATE PROCEDURE message_test ()
BEGIN
MESSAGE 'The current date and time: ', Now();
END

Example 2

• The following statement displays the string The current date and time, and the current date and time, on the database server message window:

CALL message_test()

Example 3

• To register a callback in ODBC, first declare the message handler:

void SQL_CALLBACK my_msgproc(
   void *    sqlca, 
   unsigned char     msg_type,
   long              code,
   unsigned short    len, 
   char*              msg ) 
{ … }

Install the declared message handler by calling the SQLSetConnectAttr function.

rc = SQLSetConnectAttr(    
   dbc,
   ASA_REGISTER_MESSAGE_CALLBACK,
   (SQLPOINTER) &my_msgproc, SQL_IS_POINTER );

Usage

The MESSAGE statement displays a message, which can be any expression. Clauses can specify where the message is displayed.

The procedure issuing a MESSAGE … TO CLIENT statement must be associated with a connection.

For example, the message box is not displayed in the following example because the event occurs outside of a connection.

CREATE EVENT CheckIdleTime TYPE ServerIdle 
WHERE event_condition( 'IdleTime' ) > 100 
HANDLER 
BEGIN    
   MESSAGE 'Idle engine' type warning to client; 
END;

However, in the following example, the message is written to the server console.

CREATE EVENT CheckIdleTime TYPE ServerIdle 
WHERE event_condition( 'IdleTime' ) > 100 
HANDLER 
BEGIN   
   MESSAGE 'Idle engine' type warning to console; 
END;

Valid expressions can include a quoted string or other constant, variable, or function. However, queries are not permitted in the output of a MESSAGE statement even though the definition of an expression includes queries.

The FOR clause can be used to notify another application of an event detected on the server without the need for the application to explicitly check for the event. When the FOR clause is used, recipients receive the message the next time that they execute a SQL statement. If the recipient is currently executing a SQL statement, the message is received when the statement completes. If the statement being executed is a stored procedure call, the message is received before the call is completed.

If an application requires notification within a short time after the message is sent and when the connection is not executing SQL statements, you can use a second connection. This connection can execute one or more WAITFOR DELAY statements. These statements do not consume significant resources on the server or network (as would happen with a polling approach), but permit applications to receive notification of the message shortly after it is sent.

ESQL and ODBC clients receive messages via message callback functions. In each case, these functions must be registered. To register ESQL message handlers, use the db_register_callback function.

ODBC clients can register callback functions using the SQLSetConnectAttr function.

None.

Standards

Permissions

Must be connected to the database.

DBA authority is required to execute a MESSAGE statement containing a FOR clause.

See also