CORBA Programming Reference

TP::userlog()

Synopsis

Writes a message to the user log (ULOG) file.

C++ Binding

static int    TP::userlog(char*, ...);

Arguments

The first argument is a printf(3S) style format specification. The printf(3S) argument is described in a C or C++ reference manual.

Exceptions

None.

Description

The userlog() method writes a message to the user log (ULOG) file. Messages are appended to the ULOG file with a tag made up of the time (hhmmss), system name, process name, and process-id of the invoking process. The tag is terminated with a colon.

We recommend that server applications limit their use of userlog() messages to messages that can be used to help debug application errors; flooding the ULOG file with incidental information can make it difficult to spot actual errors.

Return Value

The userlog() method returns the number of characters that were output, or a negative value if an output error was encountered. Output errors include the inability to open or write to the current log file.

Example

The following example shows how to use the TP::userlog() method:

userlog ("System exception caught: %s", e.get_id());

CosTransactions::TransactionalObject Interface Not Enforced

Use of this interface is now deprecated. Therefore, the use of this interface is now optional and no enforcement of descent from this interface is done for objects infected with transactions. The programmer can specify that an object is not to be infected by transactions by specifying the never or ignore transaction policies. There is no interface enforcement for eligibility for transactions. The only indicator is the transaction policy.

Note: The CORBAservices Object Transaction Service does not require that all requests be performed within the scope of a transaction. It is up to each object to determine its behavior when invoked outside the scope of a transaction; an object that requires a transaction context can raise a standard exception.

Error Conditions, Exceptions, and Error Messages

Exceptions Raised by the TP Framework

The following exceptions are raised by the TP Framework and are returned to clients when error conditions occur in, or are detected by, the TP Framework:

CORBA::INTERNAL
CORBA::OBJECT_NOT_EXIST
CORBA::OBJ_ADAPTER
CORBA::INVALID_TRANSACTION
CORBA::TRANSACTION_ROLLEDBACK

Since the reason for these exceptions may be ambiguous, each time one of these exceptions is raised, the TP Framework also writes a descriptive error message that explains the reason to the user log file.

Exceptions in the Server Application Code

Exceptions raised within a method invoked by a client are always raised back to the client exactly as they were raised in the method invoked by the client.

The following TP Framework callback methods are initiated by events other than client requests on the object:

Tobj_ServantBase::activate_object()
Tobj_ServantBase::deactivate_object()
Server::create_servant()

If exception conditions are raised in these methods, those exact exceptions are not reported back to the client. However, each of these methods is defined to raise an exception that includes a reason string. The TP Framework will catch the exception raised by the callback and log the reason string to the user log file. The TP Framework may raise an exception back to the client. Refer to the descriptions of the individual TP Framework callback methods for more information about these exceptions.

Example

For Tobj_ServantBase::deactivate_object(), the following line of code throws a DeactivateObjectFailed exception:

throw TobjS::DeactivateObjectFailed( "deactivate failed to save
                                       state!");

This message is appended to the user log file with a tag made up of the time (hhmmss), system name, process name, and process-id of the calling process. The tag is terminated with a colon. The preceding throw statement causes the following line to appear in the user log file:

151104.T1!simpapps.247: APPEXC: deactivate failed to save state!

Where 151104 is the time (3:11:04pm), T1 is the system name, simpapps is the process name, 247 is the process-id, and APPEXC identifies the message as an application exception message.

Exceptions and Transactions

Exceptions that are raised in either CORBA object methods or in TP Framework callback methods will not automatically cause a transaction to be rolled back unless the TP Framework started the transaction. It is up to the application code to call Current.rollback_only() if the condition that caused the exception to be raised should also cause the transaction to be rolled back.

Restriction of Nested Calls on CORBA Objects

The TP Framework restricts nested calls on CORBA objects. The restriction is as follows:

During a client invocation of a method of CORBA object A, CORBA object A cannot be invoked by another CORBA object B that is acting as a client of CORBA object A.

The TP Framework will detect the fact that a second CORBA object is acting as a client to an object that is already processing a method invocation, and will return a CORBA::OBJ_ADAPTER exception to the caller.

Note: Application code should not depend on this behavior; that is, users should not make any processing dependent on this behavior. This restriction may be lifted in a future release.