Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WLE Doc Home   |   Transactions & Related Topics   |   Previous   |   Next   |   Contents   |   Index

This topic includes the following sections:

• How the Transactions Sample Application Works

• Development Process for the Transactions Sample Application

• Setting Up the Transactions Sample Application

• Compiling the Transactions Sample Application

• Running the Transactions Sample Application

• Using the Client Applications in the Transactions sample application

Refer to Readme.txt in the \transactions directory for troubleshooting information and the latest information about using the Transactions sample application.

This topic explains how to design and implement transactions in a WebLogic Enterprise (WLE) server application using the Transactions University sample application as an example. This topic also describes how the Transactions sample application works, and discusses the design considerations for implementing transactions in it. For additional general information about transactions, see Integrating Transactions in a WLE Client and Server Application.

How the Transactions Sample Application Works

The Transactions sample application uses transactions to encapsulate the task of a student registering for a set of courses. The transactional model used in this application is a combination of the conversational model and the model in which a single invocation makes multiple individual operations on a database.

In the Transactions sample application, students can register for classes. The operation of registering for courses is executed within the scope of a transaction. This topic includes the following sections:

• Application Steps

• Application Workflow

Application Steps

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 exists 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 6-1 illustrates how the Transactions sample application works.

Figure 6-1 The Transactions Sample Application

Development Process for the Transactions Sample Application

This topic includes the following sections:

• OMG IDL

• Client Application

• University Server Application

• UBBCONFIG File

• Implementation Configuration File (ICF)

This topic describes the steps used to add transactions to the Transactions sample application. These steps are in addition to the development process outlined in "The Basic Sample Application" in the Guide to the University Sample Applications.

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.

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 WLE 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 Transactions in WLE CORBA Applications.

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 C++ Server Applications.

UBBCONFIG File

During the development process, you need to specify the following information 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 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 Modifying the UBBCONFIG File to Accommodate Transactions.

Implementation Configuration File (ICF)

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 Creating C++ Server Applications.

Setting Up the Transactions Sample Application

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

• Step 1: Copy the Files for the Transactions Sample Application into a Work Directory

• Step 2: Change the Protection on the Files for the Transactions Sample Application

• Step 3: Set the Environment Variables

• Step 4: Initialize the University Database

• Step 5: Load the UBBCONFIG File

• Step 6: Create a Transaction Log

  Note: Before you can build or run the Transactions sample application, you need to perform the steps in "Setting Up Your Environment" in the Guide to the University Sample Applications.

Step 1: Copy the Files for the Transactions Sample Application into a Work Directory

You need to copy the files for the Transactions sample application into a work directory on your local machine.

Source File Directories

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

Windows NT

drive :\ WLEdir \samples\corba\university \transaction

UNIX

/usr/ WLEdir /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.

Source Files

Table 6-1 lists the files used to create the Transactions sample application.

Table 6-1 Files Included in the Transactions Sample Application  

File	Description
univt.idl	OMG IDL that declares the CourseSynopsisEnumerator , Registrar , and RegistrarFactory interfaces
univts.cpp	C++ source code for the University server application in the Transactions sample application
univt_i.h univt_i.cpp	C++ source code for method implementations of the CourseSynopsisEnumerator , Registrar , and RegistrarFactory interfaces
univtc.cpp	C++ source code for the CORBA C++ client application in the Transactions sample application
frmBrowser.frm	Visual Basic source code for the ActiveX client application in the Transactions sample application
frmOpen.frm	Visual Basic source code for the ActiveX client application in the Transactions sample application
University.vbp	Visual Basic project file for the ActiveX client application in the Transactions sample application
University.vbw	Visual Basic workspace file for the ActiveX client application in the Transactions sample application
modPublicDeclarations.bas	A Visual Basic file that contains the declarations for variables used in the sample applications
frmTracing.frm frmTracing.frx	Files that provide tracing capabilities to the ActiveX client application
frmLogon.frm	Visual Basic file that performs the security logon for the ActiveX client application
UnivTApplet.java	Java source code for the CORBA Java client application in the Transactions sample application
univt_utils.h univt_utils.cpp	Files that define database access functions for the CORBA C++ client application
univt.icf	ICF file for the Transactions sample application
setenvt.sh	UNIX script that sets the environment variables needed to build and run the Transactions sample application
setenvt.cmd	MS-DOS command procedure that sets the environment variables needed to build and run the Transactions sample application
ubb_t.mk	UBBCONFIG file for the UNIX operating system
ubb_t.nt	UBBCONFIG file for the Windows NT operating system
makefilet.mk	makefile for the Transactions sample application on the UNIX operating system
makefilet.nt	makefile for the Transactions sample application on the Windows NT operating system
log.cpp , log.h , log_client.cpp , and log_server.cpp	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	Files that provide access to an Oracle SQL database instance. These files are located in the \utils directory.
samplesdb.cpp and samplesdb.h	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	SQL for the University database. This file is located in the \utils directory.

Step 2: Change the Protection on the Files for the Transactions Sample Application

During the installation of the WLE 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 NT

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

UNIX

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

Step 3: Set 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 NT

prompt>setenvt

UNIX

prompt>/bin/ksh

prompt>. ./setenvt.sh

Step 4: Initialize the University Database

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

Windows NT

prompt>nmake -f makefilet.nt initdb

UNIX

prompt>make -f makefilet.mk initdb

Step 5: Load the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

Windows NT

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.

Step 6: Create a Transaction Log

The transaction log records the transaction activities in a WLE 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.

You need to perform the following steps to open the transaction log for the Transactions sample application:

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

   • directorypath indicates the location of the transaction log. The directorypath needs to match the location specified in the TLOGDEVICE parameter in the UBBCONFIG file.

     The following is an example of the command on Windows NT:

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

3. Enter q t o exit the Interactive Administrative Interface.

This topic includes the following sections:

• Building the CORBA C++ Server and Client Applications

• Building the CORBA Java Client Application

• Building the ActiveX Client Application

During the development process, you 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.

For more information about the buildobjclient and buildobjserver commands, see the C++ Programming Reference.

Building the CORBA C++ Server and Client Applications

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

Windows NT

prompt>nmake -f makefilet.nt

UNIX

prompt>make -f makefilet.mk

To build the CORBA Java client application:

Windows NT

prompt>nmake -f makefilet.nt javaclient

UNIX

prompt>make -f makefilet.mk javaclient

For information about starting the ActiveX client application, see Starting the ActiveX Client Application.

Running the Transactions Sample Application

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

• Step 1: Start the Server Application

• Step 2: Start a Client Application

Step 1: Start the Server Application

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

prompt>tmboot -y

Table 6-2 shows the server processes started by running this command:

Table 6-2 Server Processes Started by tmboot Command

Process	Description
TMSYSEVT	BEA TUXEDO system event broker.
TMFFNAME	Transaction management services, including the NameManager and the FactoryFinder services.
TMIFSRVR	Interface Repository server process. This server process is used only by ActiveX client applications.
univt_server	University server process.
ISL	IIOP Listener/Handler process.

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

prompt>tmshutdown

Step 2: Start a Client Application

This topic includes the following sections:

• Starting the CORBA C++ Client Application

• Starting the CORBA Java Client Application

• Starting the ActiveX Client Application

Starting the CORBA C++ Client Application

Start the CORBA C++ client application in the Transactions sample application by performing 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.

Before you can start the CORBA Java client application, you need to change the value of the Port and Host parameters in UnivSApplet.html to match the host name and port number specified in the ISL parameter in the UBBCONFIG file. For example:

<param   name=port      value=2500>
<param   name=host      value=BEANIE>

Start the CORBA Java client application in the Transactions sample application by performing the following steps:

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

   prompt>appletviewer UnivTApplet.html

   A logon window appears.

2. Enter a number between 100001 and 100010 in the student ID field.

3. In the Domain Password field, enter the password you defined when you loaded the UBBCONFIG file.

4. Double click the Logon button.

For the University sample applications, the task of loading the OMG IDL for the CORBA interfaces into the Interface Repository is automated by the makefile .

Creating ActiveX Bindings for CORBA Interfaces

Before you can start the ActiveX client application, you must use the Application Builder to create ActiveX bindings for the CORBA interfaces.

To create an ActiveX binding for a CORBA interface:

1. Click the BEA Application Builder icon in the WLE program group.

   The IIOP Listener window appears.

2. In the IIOP Listener window, enter the host name and port number that you specified in the ISL parameter in the UBBCONFIG file. You must match exactly the capitalization used in the UBBCONFIG file.

   The Logon window appears.

3. In the Logon window, enter a student ID between 100001 and 100010 for the user name and the password you defined when you loaded the UBBCONFIG file.

   The Application Builder window appears. All the CORBA interfaces loaded in the Interface Repository appear in the Services window of the Application Builder.

4. Highlight the UniversityT folder in the Services window and drag it to the Workstation Views window, or copy the UniversityT folder from the Services window and paste it into the Workstation Views window.

   A confirmation window appears.

5. Click Create to create the ActiveX bindings for the CORBA interfaces in the Transactions sample application.

   The Application Builder creates the following:

   • A binding for the CORBA interface. The binding is named DI modulename_interfacename . For example, the binding for the Registrar interface is named DIUniversityT_Registrar .

   • A type library. By default, the type library is placed in \ WLEdir \TypeLibraries.

     The type library file is named DI modulename_interfacename .tlb.

   • A Windows system registry entry, including unique Program IDs for each object type, for the CORBA interface.

Perform the following steps to run the ActiveX client application:

1. Open the University.vbw file in Visual Basic.

2. From the Run menu, click Start.

   The IIOP Listener window appears.

3. In the IIOP Listener window, enter the host name and port number that you specified in the ISL parameter in the UBBCONFIG file. You must match exactly the capitalization used in the UBBCONFIG file.

   The Logon window appears.

4. In the Logon window, enter a student ID between 100001 and 100010 for the user name and the password you defined when you loaded the UBBCONFIG file.

This topic includes the following sections:

• CORBA C++ Client Application

• CORBA Java Client Application

• ActiveX Client Application

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

CORBA C++ Client Application

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

<R>    Register for Courses

Perform the following steps to register for a course:

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.

CORBA Java Client Application

When you log on to the CORBA Java client application, a Student Account Summary window appears. Use the Student Account Summary window to register for courses.

Registering for a Class

Perform the following steps to register for a class:

1. Obtain a list of available courses from the Student Account Summary window by entering a text string in the Search String text box, such as computer .

2. Click the Search Catalog button.

   A list of courses matching the search string appears in the window.

3. Select a course by clicking on its name in the lower portion of the Student Account Summary window.

   If you are already registered for a course, Yes appears in the Registered field on the Student Account Summary window.

4. To register for the course, click the Register button on the Student Account Summary window.

To view a list of courses for which the student ID is registered, double click the Show Registration button.

To exit the CORBA Java client application, click the Logoff button in the Student Account Summary window, or choose Quit from the Applet menu.

ActiveX Client Application

When you log on to the ActiveX client application, the Course Browser window appears. Use the Course Browser window to register for courses.

Registering for a Class

Perform the following steps to register for a class:

1. In the text box next to the Find Courses button, enter a text string or use the pulldown menu to choose a curriculum subject, such as computer .

2. Click the Find Courses button.

   A list of all the courses that match that search string appears.

3. Select a course from the list that appears in the window next to the Get Details button, or double-click the course name.

   The details for the selected course appear.

4. Click the Register for Course button or double click the course to enter the course into the schedule.

   The course appears in the student's schedule at the bottom of the window. If the student is already registered for the course, it appears in the color green. If the course conflicts with a previously registered course, it appears in the color red.

While using the ActiveX client application:

• To remove a course from the schedule, double click the course in the schedule.

• To view a list of courses for which the student ID is registered, click the Get Registered Courses button.

• To complete information about a course, click the Get Details button.

• To exit the ActiveX client application, choose Exit from the File menu.