The Transactions Sample Application

This topic includes the following sections:

•	How the Transactions Sample Application Works

•	The Development Process for the Transactions Sample Application

•	Building the Transactions Sample Application

•	Compiling the Transactions Sample Application

•	Running the Transactions Sample Application

•	Using the Client Applications in the Transactions Sample Application

Notes:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

For a complete discussion of using transactions in a CORBA application, see Using CORBA Transactions.

How the Transactions Sample Application Works

In the Transactions sample application, students can register for classes. The operation of registering for courses is executed within the scope of a transaction. The Transactions sample application works in the following way:

1.	Students submit a list of courses for which they want to be registered.

2.	For each course in the list, the University server application checks whether:

•	The course is in the database.

•	The student is already registered for a course.

•	The student exceeds the maximum number of credits the student can take.

3.	One of the following occurs:

•	If the course meets all the criteria, the University server application registers the student for the course.

•

If the course is not in the database or if the student is already registered for the course, the University server application adds the course to a list of registered courses for which the student could not be registered. After processing all the registration requests, the server application returns the list of courses for which registration failed. The client application prompts the student to either commit the transaction (thereby registering the student for the courses for which registration request succeeded) or to roll back the transaction (thus not registering the student for any of the courses).

•

If the student exceeds the maximum number of credits the student can take, the University server application returns a TooManyCredits user exception to the client application. The client application provides a brief message explaining that the request was rejected. The client application then rolls back the transaction.

Figure 5‑1 illustrates how the Transactions sample application works.

Figure 5‑1 The Transactions Sample Application

 

The Development Process for the Transactions Sample Application

This section describes the steps used to add transactions to the Transactions sample application. These steps are in addition to the development process outlined in Chapter 3, “The Basic Sample Application.”

Note:

The steps in this section have been done for you and are included in the Transactions sample application.

OMG IDL

During the development process, you would define in Object Management Group (OMG) Interface Definition Language (IDL) the register_for_courses() operation for the Registrar. The register_for_courses() operation has a parameter, NotRegisteredList, which returns to the client application the list of courses for which registration failed. If the value of NotRegisteredList is empty, the client application commits the transaction.

You also need to define the TooManyCredits user exception.

The Client Application

During the development process, you would add the following to your client application:

•	The Bootstrap environmental object to obtain a reference to the TransactionCurrent environmental object in the specified Oracle Tuxedo domain.

•	The operations of the TransactionCurrent environmental object to include a CORBA object in a transaction.

•	A call to the register_for_courses() operation so that students can register for courses.

For information about using Transactions in client applications, see Getting Started with Oracle Tuxedo CORBA Applications and Using CORBA Transactions.

The University Server Application

During the development process, you would add the following to the University server application:

•	Invocations to the TP::open_xa_rm() and TP::close_xa_rm() operations in the Server::initialize() and Server::release() operations of the Server object

•	A method implementation for the register_for_courses() operation

For information about these tasks, see Creating CORBA Server Applications.

The UBBCONFIG File

During the development process, you need the following in the UBBCONFIG file:

•	A server group that includes both the University server application and the server application that manages the database. This server group needs to be specified as transactional.

•	The OPENINFO parameter defined according to the XA parameter for the Oracle database. The XA parameter for the Oracle database is described in the "Developing and Installing Applications that Use the XA Libraries" section of the Oracle7 Server Distributed Systems manual.

Note:

If you use a database other than Oracle, refer to the product documentation for information about defining the XA parameter.

•	The pathname to the transaction log (TLOG) in the TLOGDEVICE parameter.

For information about the transaction log and defining parameters in the UBBCONFIG file, see Setting Up an Oracle Tuxedo Application.

The ICF File

During the development process, change the Transaction policy of the Registrar object from optional to always. The always Transaction policy indicates that this object must be part of a transaction. For information about defining Transaction policies for CORBA objects, see Using CORBA Transactions.

Building the Transactions Sample Application

To build the Transactions sample application, complete the following steps:

1.	Copy the files for the Transactions sample application.

2.	Change the protection on the files for the Transactions sample application files.

3.	Set the environment variables.

4.	Initialize the University database.

5.	Load the UBBCONFIG file.

6.	Create a transaction log.

7.	Build the client and server sample applications.

The following sections describe these steps.

Note:

Before you can build or run the Transactions sample application, you need to complete the steps in Chapter 2, “Setting Up Your Environment.”

Copying the Files for the Transactions Sample Application into a Work Directory

The files for the Transactions sample application are located in the following directories:

Windows

drive:\TUXDIR\samples\corba\university\transaction

UNIX

/usr/TUXDIR/samples/corba/university/transaction

In addition, you need to copy the utils directory into your work directory. The utils directory contains files that set up logging, tracing, and access to the University database.

You will use the files listed in Table 5‑1 to create the Transactions sample application.

 

Table 5‑1 Files Included in the Transactions Sample Application 

File	Description
univt.idl	The OMG IDL that declares the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
univts.cpp	The C++ source code for the University server application in the Transactions sample application.
univt_i.h univt_i.cpp	The C++ source code for method implementations of the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
univtc.cpp	The C++ source code for the CORBA C++ client application in the Transactions sample application.
univt_utils.h univt_utils.cpp	The files that define database access functions for the CORBA C++ client application.
univt.icf	The ICF file for the Transactions sample application.
setenvt.sh	A UNIX script that sets the environment variables needed to build and run the Transactions sample application.
setenvt.cmd	An MS-DOS command procedure that sets the environment variables needed to build and run the Transactions sample application.
ubb_t.mk	The UBBCONFIG file for the UNIX operating system.
ubb_t.nt	The UBBCONFIG file for the Windows operating system.
makefilet.mk	The makefile for the Transactions sample application on the UNIX operating system.
makefilet.nt	The makefile for the Transactions sample application on the Windows operating system.
log.cpp, log.h, log_client.cpp, and log_server.cpp	The client and server applications that provide logging and tracing functions for the sample applications. These files are located in the \utils directory.
oradbconn.cpp and oranoconn.cpp	The files that provide access to an Oracle SQL database instance. These files are located in the \utils directory.
samplesdb.cpp and samplesdb.h	The files that provide print functions for the database exceptions in the sample applications. These files are located in the \utils directory.
unique_id.cpp and unique_id.h	C++ Unique ID class routines for the sample applications. These files are located in the \utils directory.
samplesdbsql.h and samplesdbsql.pc	C++ class methods that implement access to the SQL database. These files are located in the \utils directory.
university.sql	The SQL for the University database. This file is located in the \utils directory.

Changing the Protection on the Files for the Transactions Sample Application

During the installation of the Oracle Tuxedo software, the sample application files are marked read-only. Before you can edit the files or build the files in the Transactions sample application, you need to change the protection of the files you copied into your work directory, as follows:

Windows

prompt>attrib -r drive:\workdirectory\*.*

UNIX

prompt>chmod u+rw /workdirectory/*.*

Setting the Environment Variables

Use the following command to set the environment variables used to build the client and server applications in the Transactions sample application:

Windows

prompt>setenvt

UNIX

prompt>/bin/ksh

prompt>. ./setenvt.sh

Initializing the University Database

Use the following command to initialize the University database used with the Transactions sample application:

Windows

prompt>nmake -f makefilet.nt initdb

UNIX

prompt>make -f makefilet.mk initdb

Loading the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

Windows

prompt>tmloadcf -y ubb_t.nt

UNIX

prompt>tmloadcf -y ubb_t.mk

The build process for the UBBCONFIG file prompts you for an application password. This password will be used to log on to the client applications. Enter the password and press Enter. You are then prompted to verify the password by entering it again.

Creating a Transaction Log

The transaction log records the transaction activities in a CORBA application. During the development process, you need to define the location of the transaction log (specified by the TLOGDEVICE parameter) in the UBBCONFIG file. For the Transactions sample application, the transaction log is placed in your work directory.

To open the transaction log for the Transactions sample application, complete the following steps:

1.	Enter the following command to start the Interactive Administrative Interface:

tmadmin

2.	Enter the following command to create a transaction log:

crdl -b blocks -z directorypath
clog -m SITE1

where

blocks specifies the number of blocks to be allocated for the transaction log and directorypath indicates the location of the transaction log. The directorypath option needs to match the location specified in the TLOGDEVICE parameter in the UBBCONFIG file. The following is an example of the command on Windows:

crdl -b 500 -z c:\mysamples\university\Transaction\TLOG

3.	Enter q to exit the Interactive Administrative Interface.

Compiling the Transactions Sample Application

During the development process, you would use the buildobjclient and buildobjserver commands to build the client and server applications. You would also build a database-specific transaction manager to coordinate the transactional events in the client/server application. However, for the Transactions sample application, this step has been done for you. The directory for the Transactions sample application contains a makefile that builds the client and server sample applications and creates a transaction manager called TMS_ORA.

Note:

In the makefile, the following parameter is hard coded to build a transaction manager for the Oracle database:

RM=Oracle_XA

If you use a database other than Oracle, you need to change this parameter.

Use the following commands to build the CORBA C++ client and server applications in the Transactions sample application:

Windows

prompt>nmake -f makefilet.nt

UNIX

prompt>make -f makefilet.mk

Running the Transactions Sample Application

To run the Transactions sample application, complete the following steps:

1.	Start the server application.

2.	Start one or more of the client applications.

These steps are described in the following sections.

Starting the Server Application

Start the system and sample application server applications in the Transactions sample application by entering the following command:

prompt>tmboot -y

This command starts the following server processes:

•

TMSYSEVT

The Oracle Tuxedo system EventBroker.

•

TMFFNAME

The transaction management services, including the NameManager and the FactoryFinder services.

•

TMIFSRVR

The Interface Repository server process.

•	univt_server

The University server process.

•

ISL

The IIOP Listener/Handler process.

Before using another sample application, enter the following command to stop the system and sample application server processes:

prompt>tmshutdown

Starting the CORBA C++ Client Application

Start the CORBA C++ client application in the Transactions sample application by completing the following steps:

1.	At the MS-DOS prompt, enter the following command:

prompt>univt_client

2.	At the Enter student id: prompt, enter any number between 100001 and 100010.

3.	Press Enter.

4.	At the Enter domain password: prompt, enter the password you defined when you loaded the UBBCONFIG file.

5.	Press Enter.

Using the Client Applications in the Transactions Sample Application

The following sections briefly explain how to use the client applications in the Transactions sample application.

The CORBA C++ Client Application

The CORBA C++ client application in the Transactions sample application has the following additional option:

<R> Register for Courses

To register for a course, complete the following steps:

1.	At the Options prompt, enter R.

2.	At the Course Number prompt, enter a course number followed by -1 . For example:

100011
100039
-1

3.	Press Enter.

4.	At the Options prompt, enter L to view a list of courses for which the student ID is registered.

To exit the C++ CORBA client application, enter E at the Options prompt.