0190-0193

Previous Table of Contents Next

Page 190

You can also use the interface at the following URL to manage cartridge names and the services they provide:

 http://host_name.domain_name:port_number/ows-abin/wrbadmin.html 

The Applications and Objects section is where cartridges are associated with physical locations and entry points, and minimum and maximum number of instances are specified.

TIP

Keep in mind that although cartridges are implemented as shared libraries, each instance has its own execution environment, which requires some resources. Again, if you cannot accurately estimate the number of concurrent users, it is safest to start with conservative (low) values. Monitor statistics and utilization and raise the values for particular cartridges as needed to improve performance.

You use the Applications, Protocols, and Hosts section to specify the host names where the cartridge resides. Unless the advanced-version ORB service is used, you can specify only the local host. In a distributed environment, you must specify here the cartridges on remote hosts that will be accessed via the intercartridge exchange. (Obviously, the cartridge factory must be running, and the cartridge must be installed on the remote host.) This section is provided for manual editing of this information, but whenever possible, you should configure and install cartridges through the primary cartridge-administration interface at

 http://host_name.domain_name:port_number/ows-abin/ctadmin.html 

This interface is especially convenient for adding and/or deleting a cartridge, where it can be accomplished with the click of a button. Deleting cartridges manually can require removing a number of entries from the different configuration sections described previously.

Some cartridges might require additional configuration. For example, the supplied PL/SQL cartridge requires additional PL/SQL Agent configuration to access the Transaction Service, available only with the advanced version of Oracle Application Server. The Transaction Service allows transactions to span multiple executions of the PL/SQL cartridge. (Without Transaction Service, the PL/SQL cartridge follows the request-response model.) You must set the following parameters to enable the Transaction Service for a particular PL/SQL Agent:

• Transaction Name: A name that is used to refer to the transaction.
• Transaction Timeout: The maximum number of seconds that can elapse before the transaction is automatically rolled back.
• Begin Transaction URL: The URL of the procedure that starts the transaction.
• Commit Transaction URL: The URL of the procedure that commits the transaction.

Page 191

• Rollback Transaction URL: The URL of the procedure that rolls back the transaction.
• Transactional Boundaries: A list of URLs that implement the transaction (such as the insert and update procedures).

Note that a PL/SQL cartridge URL has the following generic format:

 http://host_and_domain_name[:port]/virtual_path/[ package.]proc_name 

The virtual_path component of the URL refers to the virtual path of the PL/SQL agent. The use of the Transaction Service is described in greater detail later in this chapter.

This section serves as a basic overview of Oracle Web Application Server installation and configuration. The operating-system_specific details of configuring a distributed process installation are beyond the scope of this chapter, but keep in mind that remote listeners, remote authentication servers, and remote cartridges can be shared by a single instance of the ORB.

Using Supplied Cartridges

Oracle Web Application Server comes with a number of prebuilt cartridges that you can use to develop Web applications with minimal effort. This section focuses on the use of the PL/SQL cartridge, particularly in terms of the interactions between the browser and the server. The LiveHTML cartridge, the Java cartridge, and other supplied cartridges are described in less detail. Some knowledge of HTML and CGI programming is assumed.

The PL/SQL Cartridge

The PL/SQL cartridge provides the foundation for Web applications accessing Oracle databases. The PL/SQL cartridge allows Web Application Server to connect to the database and packaged or stand-alone stored procedures and functions. In addition to providing this access to standard PL/SQL capabilities, you can use a number of packages installed with the cartridge to generate an HTML page within PL/SQL. This allows a PL/SQL program to format the response in addition to processing the request.

The PL/SQL Cartridge Procedures and Functions

The PL/SQL cartridge packages include

• htp and htf: Procedures and functions to generate HTML tags and dynamic content.
• owa and owa_init: Procedures and functions used internally by the PL/SQL cartridge.
• owa_sec: Procedures and functions used by the cartridge to authenticate users.
• owa_util: Procedures and functions used to read CGI environment variables , generate dynamic SQL, format dates and times, and so on.
• owa_pattern: Procedures and functions to perform regular-expression pattern matching.

Page 192

• owa_text: Procedures, functions, and datatypes for manipulating large strings (used by owa_pattern).
• owa_image: Procedures and functions used to handle coordinates in image maps and so on.
• owa_cookie: Procedures and functions to send and retrieve cookies.
• owa_opt_lock: Procedures and functions to assist in implementing optimistic locking strategies.

Dynamic HTML with HTP and HTF

The most commonly used packages for generating dynamic HTML are htp and htf. These packages are nearly identical; htf simply contains function versions of the procedures in htp. These packages are called within application-specific stored procedures and functions to create and format dynamic HTML. Table 9.1 provides simple examples of some of the most commonly used procedures and the HTML they generate.

Table 9.1. Some of the most commonly used procedures in the htp package.

htp Procedure	Generated HTML
htmlOpen	<HTML>
htmlClose	</HTML>
headOpen	<HEAD>
headClose	</HEAD>
bodyOpen	<BODY>
bodyClose	</BODY>
line	<HR>
paragraph	<P>
title(`ACME Home Page')	<TITLE>ACME Corporation<TITLE>
header(1, `ACME Corporation')	<H1>ACME Corporation</H1>
print(`some static text')	some static text
img(`/images/logo.gif')	<IMG SRC="/images/logo.gif">
mapOpen	<MAP>
mapClose	</MAP>
anchor(`search.html', `search')	<A HREF="search.html">search</A>

These are just a few simple examples of the HTML that can be generated using the htp package. Note that some of the procedures accept additional parameters to add HTML NAME or TARGET tag/value pairs, specify additional attributes, and so on.

Page 193

The htp and htf packages support generation of nearly every HTML tag and attribute imaginable, including tags related to tables, forms, and frames . However, if a particular tag is not available, you can always manually add it to a page using the print procedure.

You can use a number of procedures in the owa_util package to generate dynamic content based on information read from the database. For example, you can use the tablePrint procedure to format the results of a SQL query in an HTML table. In its simplest form, it takes only the name of the table or view to be displayed in the table:

 owa_util.tablePrint(`dept'); 

In addition to generating dynamic HTML using SELECT statements, you can use the PL/SQL cartridge to perform database operations. Data is passed from the client to the PL/SQL cartridge in much the same way that parameters are passed to CGI scripts. However, the manner in which the PL/SQL cartridge accepts the parameters is far superior : Parameters are passed directly to the stored procedure in Oracle. For example, assume that an HTML form is developed to accept a request for technical support on a particular product. It might contain fields such as username, e-mail address, and a description of the problem. You can write a stored procedure to accept this input and insert a row into an Oracle table:

 CREATE PROCEDURE req_prodA_supp(usersname IN VARCHAR2, emailaddr IN VARCHAR2, problem IN VARCHAR2) 

PL/SQL procedures are invoked through the browser using a URL and named parameters. In the preceding example, the HTML form has two text boxes and a text area with names corresponding to the arguments of the PL/SQL procedure. The form also needs a Submit button to send the request to the server. The FORM tag contains the same attributes as it does for a CGI script. Remember that PL/SQL cartridge URLs have the following general form:

 http://hostname.domain:port/virtual_path/package_name .proc_name 

Based on the example, the FORM tag might look like this:

 <FORM ACTION="http://www.acme.com:80/web_users/plsql/req_prodA_supp" METHOD=POST> 

Note that the virtual path specified is the virtual path of the PL/SQL agent to use, and that all security restrictions apply. In particular, the PL/SQL agent must be accessible to the user, and the user associated with the PL/SQL agent must have access to the stored procedure.

When the user clicks the Submit button, a request similar to the following is sent to the server:

 http://www.acme.com:80/web_users/plsql/req_prodA_supp?USERSNAME=John+Doe &EMAILADDR=[e-mail]&PROBLEM=Periodic+GPFs+under+Windows95 

When the listener receives this request, it first checks its virtual paths to determine if it can process the request. After it fails to find the virtual path, it forwards the request to the dispatcher. The dispatcher then accesses the virtual path management service of the WRB and determines that this is a request for the PL/SQL cartridge. It then requests an instance of the PL/SQL cartridge from the WRB, which locates an available instance (or loads a new one) and notifies

Previous Table of Contents Next