Chapter 5 C Routines Reference

JagSendMsg

Description

Send an error message to the calling client application from a C component.

Syntax

#include <jagpublic.h>

JagStatus JagSendMsg(
              JagSeverity severity, 
              SQLINTEGER errnum, 
              SQLPOINTER msgtext)

Parameters

severity

Must be JAG_SEVERITY_ERROR.

errnum

An integer code for the error.

msgtext

A null-terminated string containing a description of the error.

Return Values

JAG_SUCCEED for successful execution.

If an error occurs, JagSendMessage writes error descriptions to the server log file and returns JAG_FAIL.

Usage

JagSendMessage sends an error message to the client application that invoked the currently executing method. JagSendMessage provides a C facility similar to Java exceptions.

Note Do not call JagSendMsg in C++ components. Instead, throw a user-defined or CORBA system exception.

JagSendMessage should be called only to describe errors that prevent successful completion of a method call. JagSendMessage causes an exception to be thrown in a Java or ActiveX client; in these clients, the exception may preempt the arrival of INOUT parameter values. To return additional status information from a successful call, use additional INOUT parameters.

JagSendMessage should be called only once per method execution, because clients may not be able to process more than one message.

How clients process messages

Clients process the received message differently depending on the type of client:

JagSendMessage and Java Clients
For Java clients, a JagSendMessage call on the server causes the stub method call to throw a Java exception on the client. Note that a component can call JagSendMessage multiple times, however, a Java client receives an exception for only the first call. The message is embedded in a client exception as follows:
- If the active method's definition has a raises clause that lists an exception that contains a string, the client stub throws an instance of that exception. The exception's string field contains the message text.
- Otherwise, the client stub throws an instance of org.omg.CORBA.UNKNOWN that contains the message text..
JagSendMessage and ActiveX Clients
For ActiveX clients, a JagSendMessage call on the server causes an ActiveX automation exception on the client. For more information, see Chapter 8, "Creating ActiveX Components" in the Jaguar CTS Programmer's Guide