|
|
|
|
|
|
Using Jolt ASP Connectivity for Tuxedo
The Jolt ASP Connectivity for 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 Tuxedo services.
The following topics are discussed in this section:
The Jolt ASP Connectivity for Tuxedo, an extension to the Jolt class library, enables Tuxedo services and transactions to be invoked from a Web server using a scripting language.
Some of the benefits of this architecture include:
Note: Asynchronous notification is not available in the ASP Connectivity for Tuxedo. It is recommended that Jolt enabled Java clients (applets) be written using a retained connection to support asynchronous notification.
ASP Connectivity Enhancements for Jolt
Jolt includes the following enhancements to ASP Connectivity for Tuxedo:
How the Jolt ASP Connectivity for Tuxedo Works
The Jolt ASP Connectivity for Tuxedo architecture includes three main components: a session, a session pool, and a session pool manager. A session object represents a connection with the Tuxedo system. A session pool represents many physical connections between the Web server and the 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.
A graphical representation of the ASP Connectivity for Tuxedo architecture is shown in the following figure.
Figure 7-1 Jolt ASP Connectivity for Tuxedo Architecture
Refer to the online "API Reference in Javadoc" for additional information about the SessionPool class and SessionPoolManager class.
The ASP Connectivity for Tuxedo Toolkit
The ASP Connectivity for Tuxedo Toolkit is an extension to 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 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 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 Tuxedo Walkthrough
A complete listing of all the 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 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 Tuxedo with Microsoft IIS and VBScript.
To use the information in the following sections, you should be familiar with:
Overview of the ASP for Tuxedo Walkthrough
Follow these steps to complete the ASP Connectivity for Tuxedo walkthrough:
Review this checklist before starting the TRANSFER Request Walkthrough.
Note: This checklist applies to Microsoft Active Server Pages only.
|
File Name |
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 |
VBScript functions for initializing the Jolt Session Pool Manager. |
|
web_templates.inc |
VBScript functions for caching HTML templates. |
|
templates/transfer.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 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 via 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. Every step is not illustrated here, only those steps that are necessary.
Included are:
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 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 step 6 of 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.
Table 7-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 7-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 Tuxedo in the Web Server and the Jolt Servers that reside in your 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 step 6 of 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 7-2 tellerForm.asp: Allow the user to choose TRANSFER service
<INPUT TYPE="button" VALUE="Transfer"
onClick="window.location='transferForm.htm'">
The HTML segment above 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
Figure 7-2 transferForm.htm Example
The form in the previous 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.
The code segment in the following figurethe following listing shows the key HTML elements for this page. The highlighted elements in the following listing correspond to the elements in the following table.
Listing 7-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>
|
Element |
Description |
|---|---|
|
ACTION="tlr.asp" |
When the "submit" button is pressed, 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 using a convention of 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, there is nothing appended to the name of the field. |
The HTML form field names used in this example exactly match the 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 Tuxedo field names. This is done by the Jolt ASP Connectivity For 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 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). Press 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 7-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 shown in the following listing.
Listing 7-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") shown in the following listing.
Listing 7-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 Tuxedo service. In this example, 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 7-7 tlr.asp: Invoke the Tuxedo Service
Set output = pool.call(Request("SVCNAME"), Null, Nothing)
Set iodata(1) = outputAfter you invoke the Tuxedo service, the output object and the second element of the array iodata contain the results of the service call.
Note: In this example, because the initial form specified field names match the 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 the previous listing.
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 7-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 7-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 IfNote: 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 7-3 tlr.asp Results Page
|
|
|
Copyright © 1999 BEA Systems, Inc. All rights reserved.
|