Using Jolt ASP Connectivity for BEA Tuxedo

Jolt Active Server Pages (ASP) connectivity for BEA Tuxedo provides an easy-to-use interface for processing and generating dynamic HTML pages. You do not need to learn how to write Common Gateway Interface (CGI) transactional programs to access BEA Tuxedo services.

This topic includes the following sections:

• Key Features

• How Jolt ASP Connectivity for BEA Tuxedo Works

• ASP Connectivity for BEA Tuxedo Toolkit

• Jolt ASP Connectivity for BEA Tuxedo Walkthrough

• Overview of the ASP for BEA Tuxedo Walkthrough

• Getting Started Checklist

• Overview of the TRANSFER Service

• TRANSFER Request Walkthrough

 

---

Key Features

Jolt ASP Connectivity for BEA Tuxedo, an extension to the Jolt class library, enables BEA Tuxedo services and transactions to be invoked from a Web server using a scripting language.

This architecture has several benefits:

• The HTML interface is preserved.

• The need to download Java class files is eliminated, along with the delays associated with the download.

• Session Pooling efficiently utilizes the BEA Tuxedo resources.

• Jolt ASP Connectivity for Tuxedo leverages industry standard HTTP protocol with encryption, as well as firewall configuration for the Web server.

Note: Asynchronous notification is not available in the ASP Connectivity for BEA Tuxedo. It is recommended that Jolt-enabled Java clients (applets) be written using a retained connection to support asynchronous notification.

 

---

How Jolt ASP Connectivity for BEA Tuxedo Works

The Jolt ASP Connectivity for BEA Tuxedo architecture includes three main components: a session, a session pool, and a session pool manager. A session object represents a connection with the BEA Tuxedo system. A session pool represents many physical connections between the Web server and the BEA Tuxedo system. It also associates a session with an HTTP request.

The session pool manager is responsible for maintaining a set of session objects, each having a unique session identifier.

Jolt ASP Connectivity for BEA Tuxedo works as follows:

1. If the Web application has not been initialized, the Web application initializes the session pool manager, creates a session pool, and establishes sessions (also known as connections) with the Jolt Server.

2. When a service request arrives, the Web application gets a session pool object from the session pool manager. The session pool invokes the service call using the session that is the "least busy," based on the number of outstanding call requests on a given session.

3. If the selected session is terminated by the Jolt Server, the session pool object restarts a new session or reroutes the request to another session. If the session pool manager is unable to get any session, a null session object is returned.

A graphical representation of the ASP Connectivity for BEA Tuxedo architecture is shown in the following figure.

Figure 8-1 Jolt ASP Connectivity for BEA Tuxedo Architecture

 

For additional information about the SessionPool and SessionPoolManager classes, see the online BEA Jolt API Reference.

 

---

ASP Connectivity for BEA Tuxedo Toolkit

The ASP Connectivity for BEA Tuxedo Toolkit is an extension of the Jolt Class Library. The Toolkit allows the Jolt Client Class Library to be used in a Web server (such as Microsoft Active Server) to provide an interface between HTML clients or browsers, and a BEA Tuxedo application.

Samples delivered with the software support four services: INQUIRY, WITHDRAWAL, DEPOSIT, and TRANSFER. This section explains the steps you follow to use an HTML client interface with the TRANSFER service of the BEA Tuxedo BankApp application. The TRANSFER service illustrates the use of parameters with multiple occurrences. This walkthrough explains the use of the TRANSFER service only.

 

---

Jolt ASP Connectivity for BEA Tuxedo Walkthrough

A complete listing of all examples used in this chapter are distributed with the Jolt software. In this section, segments of code from these samples are used to illustrate the use of the Toolkit.

The samples delivered with the software support four services: INQUIRY, WITHDRAWAL, DEPOSIT, and TRANSFER. This chapter explains the steps you can follow to use an HTML client interface to the TRANSFER service of the BEA Tuxedo Bankapp application. The TRANSFER service illustrates the use of parameters with multiple occurrences. This walkthrough explains the use of the TRANSFER service only.

Note: The walkthrough illustrates the use of the ASP Connectivity for BEA Tuxedo with Microsoft IIS and VBScript.

To use the information in the following sections, you should be familiar with:

• BEA Tuxedo and the sample BEA Tuxedo application, BankApp

• BEA Jolt

• Hypertext Markup Language (HTML)

• Visual Basic (VB) Script

• Object-oriented programming concepts

 

---

Overview of the ASP for BEA Tuxedo Walkthrough

Follow the steps below to complete the ASP Connectivity for BEA Tuxedo walkthrough.

1. Review the Getting Started Checklist.

2. Review the Overview of the TRANSFER Service.

3. Complete the steps in the TRANSFER Request Walkthrough:

   • Initializing the Jolt Session Pool Manager

   • Submitting a TRANSFER Request from the Client

   • Processing the Request

   • Returning the Results to the Client

 

---

Getting Started Checklist

Review this checklist before starting the TRANSFER Request Walkthrough.

Note: This checklist applies to Microsoft Active Server Pages only. It also assumes that you have already installed BEA Tuxedo and the Jolt Server on a host machine, as well as the BEA Jolt client on a machine where Microsoft IIS is installed.

Tuxedo Host Running Jolt Server

1. Ensure that you have a supported browser installed on your client machine. The client machine must have a network connection to the Web server that is used to connect to the BEA Tuxedo environment.

2. Configure and boot BEA Tuxedo and the BEA Tuxedo BankApp example.

   1. Make sure the TRANSFER service is available.

   2. Refer to the BEA Tuxedo user documentation for information about completing this task.

3. Configure the BEA Tuxedo application to start Jolt. (Refer to Installing the BEA Tuxedo System for information about how to configure a Jolt server.)

   1. Note the hostname and port number associated with your Jolt Server Listener (JSL).

   2. Ensure that the TRANSFER service is defined in the Jolt Repository.

   3. Test the TRANSFER service using the Jolt Repository Editor to make sure it is accessible. Then, export the TRANSFER service using the Repository Editor to make the TRANFER service available to all Jolt clients.

Machine Running Jolt Client and Microsoft IIS

1. If the Microsoft Java Component Framework from the Microsoft IIS SDK is not installed, install it now.

   On a Windows NT 4.0 platform, this SDK is not installed if you chose the Typical form of installation for the Microsoft NT Option Pack 4.0. Select the SHOW SUBCOMPONENTS option on the installer to display additional options under IIS. Look for the SDK and install it.

   On Windows NT or 2000, you can also obtain the Microsoft Java Component Framework classes from the Microsoft SDK for Java. To download Microsoft Java Component Framework files, complete the following procedure:

   1. Open a Web browser and link to the Microsoft Web site:

      http://www.microsoft.com

      Search for the following string: Microsoft SDK for Java.

      Alternatively, go directly to the download page:

      http://www.microsoft.com/java/download/dl_sdk40.htm

   2. Download the Microsoft SDK for Java 4.0 for Windows, and install it on your machine.

2. Create a new directory named aspcomp in your java\Trustlib directory. The Trustlib directory often resides in %windir%\java\TrustLib. Because the Framework files are created in a package called aspcomp, the Java Virtual Machine (JVM) expects to find them there.

3. Copy the Microsoft Java Component Framework class files to the java\TrustLib\aspcomp directory. Copy only the *.class files. For example:

 ...\Program Files\Microsoft SDK for Java 4.0\Samples\ASP\aspcomp> copy *.class C:\WINNT\java\TrustLib\aspcomp

4. Copy the jolt.jar file into the %windir%\java\Trustlib directory. Then use the jar command to unpack jolt.jar and create the Jolt class files in the java\TrustLib directory. Because the Jolt classes are created in a package with a name that starts with BEA, the JVM expects to find them in the java\Trustlib\bea subdirectory.

5. Copy the joltasp.jar file into the %windir%\java\Trustlib directory. Then use the jar command to unpack joltasp.jar and create the Jolt Pool ASP class files in the java\Trustlib directory. Because the Jolt Pool ASP classes are created in a package with a name that starts with BEA, the JVM expects to find them in the java\Trustlib\bea\ subdirectory.

6. Obtain the wasreg.cmd file from the Jolt installation directory. Run wasreg.cmd to register the BEA Jolt ASP classes as BEAJOLTPOOL ActiveX components. This step makes the BEAJOLTPOOL components accessible from the Microsoft ASP scripts. To unregister your Java classes as ActiveX components, run the wasunreg.cmd script provided by BEA Jolt.

   Registration can also be done manually or by using a setup program; the only task performed by javareg/register is the creation of registry entries.

   The wasreg.cmd and wasunreg.cmd scripts use the JavaReg utility. This utility is available with Visual J++ or the Microsoft SDK for Java.

7. After registering the ASP classes as ActiveX components, you are ready to test the sample application delivered with the Jolt ASP Connectivity for BEA Tuxedo software:

   1. Copy the %tuxdir%\udataobj\jolt\examples\asp\bankapp directory to the default Microsoft IIS directory.

   2. Edit the bankapp.properties file to fit your environment.

   3. Start the application by entering the following URL from your browser:

      http://web-server:port/bankapp/tellerForm.asp

   Note: A port number is optional; whether you specify a port depends on the configuration of your Web server. In most cases, it is not necessary to include a port number in this URL.

8. The following table lists the files in the sample application. These files provide a valuable reference for the TRANSFER Request Walkthrough. They are located in the directory for the Jolt example in TUXDIR\udataobj\jolt\examples\asp.

   Table 8-1 Sample BankApp Source Files

   Filename	Description
   tellerForm.asp	Initializes the Jolt Session Pool Manager and displays available BankApp services
   transferForm.htm	Presents an HTML form for user input
   tlr.asp	Processes the HTML form and returns results as an HTML page
   web_admin.inc	VBScript functions for initializing the Jolt Session Pool Manager
   web_start.inc
   web_templates.inc	VBScript functions for caching HTML templates
   templates/*.temp	HTML templates used for returning results

   
    

 

---

Overview of the TRANSFER Service

The TRANSFER service in BankApp moves funds between two accounts. The service takes two account numbers, an input amount, and returns two balances—one for each account. In addition, the service returns an error message if there is an application or system error.

A TRANSFER is a WITHDRAWAL and a DEPOSIT executed as a single transaction. The transaction is created on the server, so the client does not need to create a transaction.

The client interface consists of an HTML page with a form used to enter the required data—account numbers and a dollar amount. This data is sent to the Web server as a "POST" request.

In the Web server, this request is processed using a VBScript Active Server Page. This program extracts the input data fields from the request, formats them for use with the Jolt ASP Connectivity for BEA Tuxedo class library, and dispatches the request to the TRANSFER service in the BankApp application. The TRANSFER service returns the results of the transaction. These results are returned to the VBScript program that merges them into a dynamically created HTML page. This page is returned to the client by way of the Web server infrastructure.

In the final part of this walkthrough, run the necessary HTML pages and server-side VBScript logic to execute a TRANSFER.

 

---

TRANSFER Request Walkthrough

This section explains what happens when you execute a TRANSFER request. Each step is not include here; only those steps that are necessary, as follows:

• Initializing the Jolt Session Pool Manager

• Submitting a TRANSFER Request from the Client

• Processing the Request

• Returning the Results to the Client

Initializing the Jolt Session Pool Manager

To start the walkthrough, use the browser on your client to connect to the Web server where the Jolt Asp Connectivity for BEA Tuxedo classes are installed. The first page to download is tellerForm.asp (see the following figure for an example of a tellerForm.asp page). If the teller sample has been installed as described in the Getting Started Checklist, the URL for this page will be:

http://<web-server:port>/teller/tellerForm.asp

Note: The use of the port number is optional, depending on how your Web server is configured. In most cases, you are not required to add the ":port" in the URL.

Figure 8-2 tellerForm.asp Example

 

The page, tellerForm.asp, contains VBScript procedures required to initialize the Jolt Session Pool Manager. The initialization code is contained in an ASP Script block. This code tells the Web server to execute this block of code on the server, instead of sending it to the client.

Listing 8-1 tellerForm.asp: Initialize the Jolt Session Pool Manager

<%
'// Initialize the session manager and cache templates
Call web_initSessionMgr(Null)
Call web_cacheTemplates()
%>

The VBScript procedure web_initSessionMgr() calls other VBScript procedures to establish a pool of Jolt sessions. A Jolt session is established between the Jolt ASP Connectivity for BEA Tuxedo in the Web server and the Jolt Servers that reside in your BEA Tuxedo application. One of the procedures called is web_start(). This procedure (in the file web_start.inc) should have been edited as part of the teller application installation process in the Getting Started Checklist.

The procedure web_cacheTemplates() reads various HTML template files into a memory cache. This step is not required, but it improves performance.

Listing 8-2 tellerForm.asp: Allow the User to Choose TRANSFER Service

<INPUT TYPE="button" VALUE="Transfer" 
    onClick="window.location='transferForm.htm'">

The HTML segment shown in the previous listing displays a button labeled "Transfer." When this button is selected, the browser loads the page transferForm.htm. This page presents a form used to enter the data required by the TRANSFER service.

Submitting a TRANSFER Request from the Client

The form in the following figure is generated by the page transferForm.htm. This page presents you with a form for input. The page consists of three text fields (two account numbers and a dollar amount), and a button that, when pressed, causes the TRANSFER service to be invoked.

Figure 8-3 transferForm.htm Example

 

The code segment in the following listing shows the key HTML elements for this page. The bolded text in the following listing correspond to the elements in the table Key HTML Elements and Descriptions.

Listing 8-3 transferForm.htm: TRANSFER Form

<FORM NAME="teller" ACTION="tlr.asp" METHOD="POST">
<TABLE>
<TR><TD ALIGN=RIGHT>From Account Number: </TD>
    <TD><INPUT TYPE="text" NAME="ACCOUNT_ID_0"></TD></TR>
<TR><TD ALIGN=RIGHT>To Account Number: </TD>
    <TD><INPUT TYPE="text" NAME="ACCOUNT_ID_1"></TD></TR>
<TR><TD ALIGN=RIGHT>Amount: $</TD>
    <TD><INPUT TYPE="text" NAME="SAMOUNT"></TD></TR>
</TABLE>
<CENTER>
<INPUT TYPE="hidden" NAME="SVCNAME" VALUE="TRANSFER">
<INPUT TYPE="submit" VALUE="Transfer">
<INPUT TYPE="reset" VALUE="Clear">
</CENTER>
</FORM>

Table 8-2 Key HTML Elements and Descriptions

Element	Description
ACTION="tlr.asp"	When you click the Submit button, the contents of this form are delivered to a page called tlr.asp on the Web server for processing.
NAME="ACCOUNT_ID_0"	Shows the use of a field with multiple occurrences. The TRANSFER service expects two input account numbers, both called "ACCOUNT_ID". By appending an underscore and occurrence_number (e.g., _0, _1) to the field name, both the name of a field and its occurrence can be passed to the program on the Web server.
NAME="SAMOUNT"	Shows the use of an input field that has a single occurrence. In this example, nothing is appended to the name of the field.

 

The HTML form field names used in this example exactly match the BEA Tuxedo field names expected by the TRANSFER service. This is not required, but doing so facilitates processing on the server because you do not have to map these inputs to BEA Tuxedo field names. This is done by the Jolt ASP Connectivity for BEA Tuxedo classes.

The hidden field SVCNAME is assigned a value of TRANSFER. This field does not appear on the client form, but it is sent to the Web server as part of the request. The VBScript program retrieves the value of this field in order to determine which BEA Tuxedo service is to be called (in this example, the service is TRANSFER).

Complete the fields From Account Number, To Account Number, and Amount. (10000 and 10001 are valid BankApp account numbers). Click the Transfer button. The data entered on the form is sent to the Web server for processing by the program tlr.asp as specified in the ACTION field of the form.

Processing the Request

When the Web server receives the TRANSFER request, it runs the program tlr.asp. Client requests are turned into a Request object in the Web server. This Request object has members containing all the data that was input to the form along with other form data, such as hidden fields. The Web server makes the Request object available to the program being invoked.

The program tlr.asp contains only VBScript. The first action performed by this program verifies that the Jolt Session Pool Manager is initialized.

The code example shown in the following listing performs the initialization check and returns an HTML error page if the pool is not initialized.

Listing 8-4 tlr.asp: Verify the Jolt Session Pool Manager Is Initialized

<%
If Not IsObject(Application("mgr")) Then
%>
    <HTML>
    <HEAD><TITLE>Error</TITLE></HEAD>
    <BODY><CENTER>
    <H2>Session Manager is not initialized</H2>
    <P>Make sure that you access the correct HTML
    </CENTER></BODY>
    </HTML>
<%
End If
%>

If the session pool is initialized, the program continues to process the request. The program locates a Session from the Session Pool Manager as shown in the following listing.

Listing 8-5 tlr.asp: Locate a Session

Set pool = Application("mgr").getSessionPool(Null)

Once a valid session is located, the program retrieves an HTML template that is used to return the results to the client. In this example, these templates were cached in the initialization section. The template retrieved is identified by the name of the service being invoked, Request("SVCNAME") as shown in the following listing.

Listing 8-6 tlr.asp: Retrieve a Cached HTML Template

'// Choose the response template
If IsEmpty(Application("templates")) Then
   Set template = Server.CreateObject("BEAWEB.Template")
Else
   Select Case Request("SVCNAME")
      Case "INQUIRY"
         Set template = Application("templates")(INQUIRY)
      Case "DEPOSIT"
         Set template = Application("templates")(DEPOSIT)
      Case "WITHDRAWAL"
         Set template = Application("templates")(WITHDRAWAL)
      Case "TRANSFER"
         Set template = Application("templates")(TRANSFER)
   End Select
End If

Next, call the BEA Tuxedo service as shown in the following listing. In the following listing, the input data from the Request object is passed to the call() method of the session. The call() method uses the built-in ASP Request object as input. The results of the call() are stored in the output object and an array, iodata.

Listing 8-7 tlr.asp: Invoke the BEA Tuxedo Service

Set output = pool.call(Request("SVCNAME"), Null, Nothing)
Set iodata(1) = output

After you invoke the BEA Tuxedo service, the output object and the second element of the array iodata contain the results of the service call.

Note: Because the initial form specified field names match the BEA Tuxedo service parameter names, the Request object can be used in the call() method. If these names do not match, create an input array with "name=value" elements for each service parameter before invoking the call() method.

Returning the Results to the Client

At this stage, no results have been returned to the client. The final step sends an HTML page containing the results of the service call back to the client. The HTML page consists of the template merged with the data returned by the service call shown in Listing  8-7.

The template file contains placeholders for variable (call-specific) data. These placeholders are identified by the special tag <%=NAME%>. In the code example shown in the following listing, an index is used to indicate which occurrence of a parameter name is used. For example, ACCOUNT_ID[0] specifies the first occurrence of the field ACCOUNT_ID.

Listing 8-8 transfer.temp: Placeholders for TRANSFER Results

<TABLE BORDER=1>
<TR><TD></TD><TD ALIGN=CENTER><B>Account #</B></TD>
   <TD ALIGN=CENTER><B>Balance</B></TR>
<TR><TD ALIGN=RIGHT><B>From:</B></TD><TD><%=ACCOUNT_ID[0]%></TD>
   <TD><%=SBALANCE[0]%></TR>
<TR><TD ALIGN=RIGHT><B>To:</B></TD><TD><%=ACCOUNT_ID[1]%></TD>
   <TD><%=SBALANCE[1]%></TR>
</TABLE>

To substitute the placeholders in the template with the actual values of the data returned from the service call, use the eval() method of the Template object shown in the following listing. This method matches placeholders in the template file with fields of the same name in the results data and replaces them accordingly. A check for valid results (output object) is done as shown in the following listing. If there is no output object, an error template page is returned.

Listing 8-9 tlr.asp: Template Processing

path = Application("templatedir")
If (Not IsObject(output)) Or (output is Nothing) Then
    Call template.evalFile(path & "\nosession.temp", Null)
Elseif output.noError() Then
    Call template.eval(iodata)
Elseif output.applicationError() Then
    Call template.evalFile(path & "\error.temp", iodata)
Else
    '// System error
    Dim errdata(0)
    Set errdata(0) = Server.CreateObject("BEAWEB.TemplateData")
    Call errdata(0).setValue("ERRNO", output.getError())
    Call errdata(0).setValue("ERRMSG", output.getStringError())
    Call template.evalFile(path & "\syserror.temp", errdata)
End If

Note: The array iodata contains both the input request and the results from the service call. This is useful if you want the results page to contain data that is part of the input.

When the template is processed, the resulting HTML is returned to the client as shown in the following figure.

Figure 8-4 tlr.asp Results Page