Oracle Forms Server Release 6i: Deploying Forms Applications to the Web with iAS Patch 2 A86202-01 |

|  |  | Contents | Index

# 11
Performance Tuning Considerations

## 11.1 Introduction

This chapter describes the tuning considerations that arise when you use Forms Server to deploy an application over the Internet or other network environment. This chapter looks at the network and the resources on the application server. It includes the following sections:

- Built-in Optimization Features of Forms Server

- Tuning Forms Server Applications

- Performance Collection Services

- Trace Collection

Tuning the connection between Forms Server and the database server is beyond the scope of this chapter.

## 11.2 Built-in Optimization Features of Forms Server

The Forms Server and Java client include several optimizations that fit broadly into the following categories:

- Minimizing Client Resource Requirements

- Minimizing Forms Server Resource Requirements

- Minimizing Network Usage

- Maximizing the Efficiency of Packets Sent Over the Network

- Rendering Application Displays Efficiently on the Client

### 11.2.1 Minimizing Client Resource Requirements

The Java client is primarily responsible for rendering the application display. It has no embedded application logic. Once loaded, a Java client can display multiple Forms simultaneously. Using a generic Java client for all Forms Server applications requires fewer resources on the client when compared to having a customized Java client for each application.

The Java client is structured around many Java classes. These are grouped into functional subcomponents, such as displaying the splash screen, communicating with the network, and changing the look-and-feel. Functional subcomponents allow the Forms Developer and the Java Virtual Machine (JVM) to load functionality as it is needed, rather than downloading all of the functionality classes at once.

### 11.2.2 Minimizing Forms Server Resource Requirements

When a Form definition is loaded from an FMX file, the profile of the executing process can be summarized as:

- Encoded Program Units

- Boilerplate Objects/Images

- Data Segments

Of these, only the Data Segments section is unique to a given instance of an application. The Encoded Program Units and Boilerplate Objects/Images are common to all application users. Forms Server maps the shared components into physical memory, and then shares them between all processes accessing the same FMX file.

The first user to load a given FMX file will use the full memory requirement for that Form. However, subsequent users will have a greatly reduced memory requirement, which is dependent only on the extent of local data. This method of mapping shared components reduces the average memory required per user for a given application.

### 11.2.3 Minimizing Network Usage

Bandwidth is a valuable resource, and the general growth of Internet computing puts an ever increasing strain on the infrastructure. Therefore, it is critical that applications use the network's capacity sparingly.

Forms Server communicates with the Java client using meta data messages. Meta data messages are a collection of name-value pairs that tell the client which object to act upon and how. By sending only parameters to generic objects on the Java client, there is approximately 90-percent less traffic (when compared to sending new code to achieve the same effect).

Forms Server intelligently condenses the data stream in three ways:

- When sets of similar messages (collections of name-value pairs) are sent, the second and subsequent messages include only the differences from the previous message. This results in significant reductions in network traffic. This process is called message diff-ing.

- When the same string is to be repeated on the client display (for example, when displaying multiple rows of data with the same company name), Forms Server sends the string only once, and then references the string in subsequent messages. Passing strings by reference increases bandwidth efficiency.

- Data types are transmitted in the lowest number of bytes required for their value.

### 11.2.4 Maximizing the Efficiency of Packets Sent Over the Network

Latency can be the most significant factor that influences the responsiveness of an application. One of the best ways to reduce the effects of latency is to minimize the number of network packets sent during a conversation between the Java client and the Forms Server.

The extensive use of triggers within the Forms Developer model is a strength, but they can increase the effect of latency by requiring a network round trip for each trigger. One way to avoid the latency concerns adhering to triggers is by grouping them together through Event Bundling. For example, when a user navigates from item A to item B (such as when tabbing from one entry field to another), a range of pre- and post-triggers may fire, each of which requires processing on the Forms Server.

Event Bundling gathers all of the events triggered while navigating between the two objects, and delivers them as a single packet to the Forms Server for processing. When navigation involves traversing many objects (such as when a mouse click is on a distant object), Event Bundling gathers all events from all of the objects that were traversed, and delivers the group to the Forms Server as a single network message.

### 11.2.5 Rendering Application Displays Efficiently on the Client

All boilerplate objects in a given Form are part of a Virtual Graphics System (VGS) tree. VGS is the graphical subcomponent that is common to all Forms Developer products. VGS tree objects are described using attributes such as coordinates, colors, line width, and font. When sending a VGS tree for an object to the Java client, the only attributes that are sent are those that differ from the defaults for the given object type.

Images are transmitted and stored as compressed JPEG images. This reduces both network overhead and client memory requirements.

Minimizing resources includes minimizing the memory overhead of the client and server processes. Optimal use of the network requires that bandwidth be kept to a minimum and that the number of packets used to communicate between the client and Forms Server be minimized in order to contain the latency effects of the network.

## 11.3 Tuning Forms Server Applications

An application developer can take steps to ensure that maximum benefits are gained from Forms Server's built-in architectural optimizations. The remainder of this chapter discusses key performance issues that affect many applications and how developers can improve performance by tuning applications to exploit Forms Server features.

Issues discussed are:

- Location of the Form Server with Respect to the Data Server

- Minimizing the Application Startup Time

- Reducing the Required Network Bandwidth

- Other Techniques to Improve Performance

### 11.3.1 Location of the Form Server with Respect to the Data Server

The Java client connection to the Forms Server can use features such as Event Bundling to effectively counteract the effects of network latency. It uses message diff-ing to reduce network bandwidth. On the other hand, the client/server relationship that exists between the Forms Server and the data server is much less tolerant of round-trip delays and network congestion.

For these reasons, it is best to locate the Forms Server on the same high speed LAN as the data server, which may consequently locate the Forms Server more remotely from the users. This may seem contrary to the standard convention of placing servers in close proximity to users, but it is a consequence of Forms Server's improved efficiency over a network as compared to a traditional client/server implementation.

In an optimal configuration, as shown in Figure 11-1, the Form Server and data server are co-located in a Data Center, which is the recommended set-up, while clients access the server over low-bandwidth (modem) and high-latency (satellite) connections.

#### Figure 11-1 Co-Locating the Forms Server and Data Server

### 11.3.2 Minimizing the Application Startup Time

First impressions are important, and a key criterion for any user is the time it takes to load an application. Startup time is regarded as overhead. It also sets an expectation of future performance. When a business uses thin-client technologies, the required additional overhead of loading client code may have a negative impact on users. Therefore, it is important to minimize load time wherever possible.

After requesting a Forms application, several steps must be completed before the application is ready for use:

1. Invoke Java Virtual Machine (JVM).

2. Load all initial Java client classes, and authenticate security of classes.

3. Display splash screen.

4. Initialize Form:

   1. Load additional Java classes, as required.

   2. Authenticate security of classes.

   3. Render boilerplate objects and images.

   4. Render all elements on the initial screen.

5. Remove splash screen.

6. Form is ready for use.

An application developer has little influence on the time it takes to launch the JVM. However, the Java deployment model and the structure of the Form Developer Java client allow the developer to decide which Java classes to load and how. This, in turn, minimizes the load time required for Java classes.

The Java client requires a core set of classes for basic functionality (such as opening a window) and additional classes for specific display objects (such as LOV items). These classes must initially reside on the server, but the following techniques can be used to improve the time it takes to load these classes into the client's JVM:

- Using JAR Files

- Using Caching

- Deferred Load on Demand

#### 11.3.2.1 Using JAR Files

Java provides the Java Archive (JAR) mechanism to create files that allow classes to be grouped together and then compressed (zipped) for efficient delivery across the network to the client. Once used on the client, the files are cached for future use.

Form Server provides the following pre-configured JAR files to support typical deployment scenarios:

#####

File name | Usage | Description
--- | --- | ---
f60all_jinit.jar | Optional | For Oracle JInitiator only, contains an extra-compressed set of Java class files for all runtime situations.
f60all.jar | Optional | Contains the entire set of Java class files for all runtime situations.
f60common.jar | Required | Required by the applet.
f60generic_laf.jar | Optional | Must be loaded if the application is deployed with the Generic lookAndFeel runtime setting or if no lookAndFeel setting is specified.
    <APPLET ...>
    <PARAM NAME="lookAndFeel" VALUE="Generic">
    ...
    </APPLET>
f60oracle_laf.jar | Optional | Must only be loaded if the application is deployed with the Oracle lookAndFeel runtime setting.
    <APPLET ...>
    <PARAM NAME="lookAndFeel" VALUE="Oracle">
    ...
    </APPLET>
f60splash.jar | Required | Required by the applet.
f60tree.jar | Optional | Must only be loaded if the Forms application uses the hierarchical tree control.

To specify one or more JAR files for an applet, specify the ARCHIVE parameter in the <APPLET> tag of the referencing HTML file. For example:

    <APPLET CODEBASE="http://www.server.com/webcode/"
    ARCHIVE="f60all.jar, icons.jar"
    CODE="oracle.forms..">

#### 11.3.2.2 Using Caching

Both of the supported JVMs for Form Server (Oracle JInitiator and Oracle JDK) support the caching of JAR files. When the JVM references a class, it first checks the local client cache to see if the class exists in a pre-cached JAR file. If the class exists in cache, JVM checks the server to see if there is a more current version of the JAR file. If there isn't, the class is loaded from the local cache rather than from across the network.

Be sure that the cache is of proper size to maximize its effectiveness. Too small a cache size may cause valid JAR files to be overwritten, thereby requiring that another JAR file be downloaded when the application is run again. The default cache size is 20MB. This size should be compared with the size of the cache contents after successfully running the application.

JAR files are cached relative to the host from which they were loaded. This has implications in a load-balancing architecture where identical JAR files from different servers can fill the cache. By having JAR files in a central location and by having them referenced for each server in the load-balancing configuration, the developer can ensure that only one copy of each JAR file is maintained in the client's cache. A consequence of this technique is that certain classes within the JAR file must be signed to enable connections back to servers other than the one from which they were loaded. The Oracle-supplied JAR files already pre-sign the classes.

#### 11.3.2.3 Deferred Load on Demand

One downside of the JAR method is that all classes within a JAR file need to be loaded and validated by the JVM before execution continues. A useful feature of the JAR file is the ability to refer to other JAR files, thus limiting the number of classes stored within the given archive. The JVM is able to navigate to the required JAR files in the order required by the application.

The Oracle-supplied f60splash.jar file contains enough logic to initialize the client and display a welcoming splash screen. It also contains deferred references to files that are contained in the other JAR files, which are subsequently loaded on demand. In order to use deferred load on demand, the f60splash.jar file must be the first JAR file referenced in the HTML page.

### 11.3.3 Reducing the Required Network Bandwidth

The developer can design the application to maximize data stream compression by using message diff-ing, which sends along only the information that differs from one message to another. The following steps can be taken to reduce the differences between messages:

- Control the order in which messages are sent. The order in which messages are sent is governed by two criteria:

  - For the initial display, the display order in the Object Navigator

  - During execution, the order of program changes to item properties

    Where the result does not impact usability, you should strive to place similar objects that are on the same canvas after each other in the Object Navigator. For example, place buttons with buttons, text items with text items, and so on. (If you use the item property Next Navigation Item, the same order of navigation will be used for the items in the Form.) By ordering similar items together on the Object Navigator, the item properties sent to the client to display the first Form will include many similar items in consecutive order, which allows the message diff-ing algorithm to function efficiently.

  In addition, when triggers or other logic are used to alter item properties, then you should group properties of similar items together before altering the item properties of another display type. For example:

      set_item_property(text_item1_id, FONT_WEIGHT, FONT_BOLD);
      set_item_property(text_item2_id, FONT_WEIGHT, FONT_BOLD);
      set_item_property(text_item3_id, FONT_WEIGHT, FONT_BOLD);
      set_item_property(button_item1_id, LABEL, 'Exit');
      ...

- Promote similarities between objects. Using similar objects improves message diff-ing effectiveness (in addition to being more visually appealing to the user). The following steps encourage consistency between objects:

  - Accept default values for properties, and change only those attributes needed for the object.

  - Use Smart Classes to describe groups of objects.

  - Lock the look-and-feel into a small number of visual attributes.

- Reduce the use of boilerplate text. As a developer, you should use the PROMPT item property rather than boilerplate text wherever applicable. Forms Developer 6.0 and higher includes the Associate Prompt feature, which allows boilerplate text to be re-designated as the prompt for a given item.

- Reduce the use of boilerplate items (such as arcs, circles, and polygons). All boilerplate items for a given Form are loaded at Form initialization. Boilerplate items take time to load and use resources on the client whether they are displayed or not. Common boilerplate items, namely rectangles and lines, are optimized. Therefore, restricting the application to these basic boilerplate items reduces network bandwidth and client resources while improving startup times.

- Keep navigation to a minimum. An Event Bundle is sent each time a navigation event finishes, whether the navigation extends over two objects or many more. Design Forms that do not require the user to navigate through fields when default values are being accepted. A Form should encourage the user to quickly exit once the Form is complete, which causes all additional navigation events to fire as one Event Bundle.

- Reduce the time to draw the initial screen. Once the Java client has loaded the required classes, it must load and initialize all of the objects to be displayed before it can display the initial screen. By keeping the number of items to a minimum, the initial screen is populated and displayed to the user more promptly. Techniques that reduce the time to draw the initial screen include:

  - Providing a login screen for the application with a restricted set of objects (such as a title, small logo, username, and password).

  - On the Form's initial display, hiding elements not immediately required. Use the canvas properties:

    `RAISE ON ENTRY = YES` (Canvas only)
    `VISIBLE = NO`
    Pay attention to TAB canvases that consist of several sheets where only one will ever be displayed. For responsive switching between tabs, all items for all sheets on the canvas are loaded, including those that are hidden behind the initial tab. Consequently, the time taken to load and initialize a TAB canvas is related to all objects on the canvas and not just to those initially visible.
- Disable MENU_BUFFERING. By default, MENU_BUFFERING is set to True. This means that changes to a menu are buffered for a future "synchronize" event when the altered menu is re-transmitted in full. (Most applications make either many simultaneous changes to a menu or none at all. Therefore, sending the entire menu at once is the most efficient method of updating the menu on the client.) However, a given application may make only minimal changes to a menu. In this case, it may be more efficient to send each change as it happens. You can achieve this using the statement:

    Set_Application_Property (MENU_BUFFERING, 'false');

  Menu buffering applies only to the menu properties of LABEL, ICON, VISIBLE, and CHECKED. An ENABLE/DISABLE event is always sent and does not entail the retransmission of an entire menu.

### 11.3.4 Other Techniques to Improve Performance

The following techniques may further reduce the resources required to execute an application:

- Restrict the use of MOUSE-UP, MOUSE-DOWN triggers. In the Java model, an event must be triggered when a mouse button action is detected. The event is passed to the Form Server to determine whether this is a MOUSE-UP or a MOUSE-DOWN event. A given application may define only one trigger (for example, MOUSE-DOWN), but an event is still generated by the client for the associated (MOUSE-UP) event, even though there is no trigger code specified to handle the event. Mouse events are asynchronous, so they are processed outside of the usual Event Bundling model.

- Examine timers and replace with JavaBeans. When a timer fires, an asynchronous event is generated. There may not be other events in the queue to bundle with this event. Although a timer is only a few bytes in size, a timer firing every second generates 60 network trips a minute and almost 30,000 packets in a typical working day. Many timers are used to provide clocks or animation. Replace these components with self-contained JavaBeans that achieve the same effect without requiring the intervention of Forms Server and the network.

- Consider localizing the validation of input items. It is common practice to process input to an item using a When-Validate-Item trigger. The trigger itself is processed on the Forms Server. You should consider using pluggable Java components to replace the default functionality of standard client items, such as text boxes. Then, validation of items, such as date or max/min values, are contained within the item. This technique opens up opportunities for more complex, application-specific validation like automatic formatting of input, such as telephone numbers with the format (XXX) XXX-XXXX.

- Reduce the application to many smaller Forms, rather than one large Form. By providing a fine-grained application, the user's navigation defines which objects are loaded and initialized from the Form Server. With large Forms, the danger is that the application is delayed while objects are initialized, many of which may never be referenced. When chaining Forms together, consider using the built-ins OPEN_FORM and NEW_FORM:

  - With OPEN_FORM, the calling Form is left open on the client and the server, so that the additional Form on both the client and the server consumes more memory. However, if the Form is already in use by another user, then the increase in server memory is limited to just the data segments. When the user returns to the initial Form, it already resides in local memory and requires no additional network traffic to redisplay.

  - With NEW_FORM, the calling Form is closed on the client and the server, and all object properties are destroyed. Consequently, it consumes less memory on the server and client. Returning to the initial Form requires that it be downloaded again to the client, which requires network resources and startup time delays. Use OPEN_FORM to display the next Form in an application unless it is unlikely that the initial form will be called again (such as a login form).

## 11.4 Performance Collection Services

The Forms runtime diagnostics have been enhanced with the addition of Performance Collection Services. These provide you with information you can use to better understand and improve your application's runtime performance.

### 11.4.1 How to Use Performance Collection Services

To activate Performance Collection Services, include `record=performance' in the command line argument (for runtime in a client/server environment), or as a part of `serverArgs' parameter in the HTML file (for web deployment).

For example, if running in the client/server mode, use:

    ifrun60  module=.. userid=.. record=performance log=yourlogname

The results are written onto the file yourlogname. If the file name is not specified, a file with a unique filename is created. This name is in the format `perf_xxxx' where `xxxx' is the ProcessId of the runtime process running.

In the HTML file, this invocation will be:

    <param name= "serverArgs" value = "module=.. userid=.. record=performance
    log=yourlogname">

### 11.4.2 Events Collected by Performance Services

The following events are collected by Performance Services:

#####

Event | Description
--- | ---
ClientTime | Time spent at the Client
Logon Time | Time to logon to the Database Server
Logoff Time | Time to logoff from the Database Server
DB Time | Time for any database operations
APServerTime | Processing time at the Forms Server

### 11.4.3 Analyzing the Performance Data

The data collected by Performance Services is analyzed using PERL scripts, f60parse.pl, which are located in the <ORACE_HOME>\6iserver\forms60\perl\ directory.

To start the data collection, enter the following command:

    perl f60parse.pl -input=infile -eventf='evfile' -outputf='ofile'

Where:

- infile is the recorded data while running the application.

- evfile is the event description file.

- ofile is the results file generated by the PERL script.

- eventf and outputf are optional parameters.

By default, the output appears in the following HTML files, which can be viewed in a browser:

#####

File name | Description
--- | ---
index.html | Summary of user action
detailed1.html | Detailed events
detailed2.html | Detailed event collection
event.html | Event definitions

When specified, an XLS output file is created with the given name.

## 11.5 Trace Collection

When you develop and deploy a Forms application, you may want to know what parts of the application can be optimized and what actions are taking time or resources. Oracle Trace integration allows you to analyze in depth the performance and the resource consumption of your Forms application.

Oracle Trace is part of Oracle Enterprise Manager (OEM). Oracle Trace is the Oracle tool to gather and analyze the performance of the Oracle Database, Forms Server 6i, and other products which implement the Oracle Trace API for tracing. To take full advantage of Oracle Trace, you must install Diagnostics Pack, one of the optional packs provided in the Oracle Enterprise Manager product suite. The Diagnostics Pack contains a set of tools to administer the Oracle Trace collections remotely through a GUI interface and to efficiently view the Oracle Trace output.

In this section, we discuss:

- Types of Forms Events Traced Using Oracle Trace

- Using Forms and Oracle Trace without the Diagnostics Pack

- Using Forms and Oracle Trace with the Diagnostics Pack

- Setting Up the Load Balancer Server Trace Log

### 11.5.1 Types of Forms Events Traced Using Oracle Trace

Oracle Trace only collects data for predefined events, of which there are two types:

- Duration Events

- Point Events

Duration events have a begin point and an end point. For example, a transaction is a duration event. Nested events can occur in a duration event, such as if an error occurs within a transaction. Point events represent an instantaneous occurrence in the product. For example, the display of a canvas or a dialog are point events.

For Forms Server, those events are defined in a binary file (oforms.fdf), shipped as part of Forms Server 6i and located in the following directory:

NT: <ORACLE_HOME>\6iserver\net80\admin\fdf

UNIX: <ORACLE_HOME>/6iserver/network/admin/fdf

#### 11.5.1.1 Forms Duration Events and Items

The following table lists the Forms duration event number and name, describes the event and the specific and generic items associated with it. The items are the information displayed for this particular event.

#####

Event Number and Name | Description and Items
--- | ---
1. Session | Total time spent by the end user in the Forms Session, including login and logout. Specific items = Session Name, IPAddress. Generic items = UCPU, SCPU, INPUT_IO, PAGEFAULTS, PAGEFAULTS_IO, MAXRS_SIZE
2. Form | Total time spent by the end user in the specific form and the forms called from this form. Specific item = Form Name. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
3. Query | Total time spent by the end user in a specific query. Specific item = Block Name. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
4. Trigger | Total time spent by the end user in a specific trigger. Specific items = Block Name, Item Name, Trigger Id. Generic items =Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
5. LOV | Total time spent by the end user in a LOV. Specific items = LOV Name, Blockname, Itemname Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
11. Built-in | Total time spent by the end user in a built-in. Specific item = Built-in Name. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
12. User Exit | Total time spent by the end user in a user exit. Specific item = User Exit Name. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
13. SQL | Total time spent by the end user in SQL code. Specific item = SQL Statement. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
14. Menu Create | Total time spent by the end user in creating a menu. Specific item = Menu Name. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
41. ServerTime | Time spent in processing at the Forms Server. Specific item = none. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
42. DBTime | Total time spent at the database Specific item = SQL statement. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
43. DBLogon | Time spent logging on to the database. Specific item = none. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).
44. DBLogoff | Time spent logging off from the database. Specific item = none. Generic items = UCPU, SCPU, MAXRS_SIZE, CROSS_FAC (Session id).

Note: :

Each point event also has a Timestamp. Duration events have a Start Timestamp and an End Timestamp.

#### 11.5.1.2 Forms Point Events and Items

The following table lists the Forms point event number and name, and describes the event and both specific and generic items associated with it.

#####

Event Number and Name | Description and Items
--- | ---
1. Alert | Instant when an alert occurs. Specific item = Alert Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).
2. Editor | Instant when an editor is invoked. Specific item = Editor Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).
3. Window | Instant when a window is created. Specific item = Window Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).
4. Canvas | Instant when the user visits a canvas from the user perspective. Specific item = Canvas Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).
5. Timer | Instant when a timer activates. Specific item = Timer Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).
11. Dialog | Instant when a dialog activates. Specific item = Dialog Name. Generic items = UCPU, SCPU, CROSS_FAC (FormID).

### 11.5.2 Using Forms and Oracle Trace without the Diagnostics Pack

Even if you have not installed Oracle Enterprise Manager and Oracle Diagnostics Pack, you can still use Oracle Trace to profile your Forms application. When you install Forms Server, the command line trace executables are automatically installed in your <ORACLE_HOME> and provide a manual way to analyze your Forms application performance.

To use Forms and Oracle Trace without the Diagnostics Pack, you must:

- Start the Trace Collection using a command line and run your Form application in trace mode

- Format the Trace output to produce text files containing the information about your Forms application

#### 11.5.2.1 Starting the Collection

Without the Oracle Diagnostics Pack installed, you need to use the Command Line Interface (CLI) to manage your data colections. The CLI is available from a MS/DOS window on Windows-based systems or from the console on Unix-based systems.

1. Start the collection with the otrccol command.

To start the data collection, enter the following command:

    otrccol start job_id input_parameter_file

Where:

- job_id can be any numeric value (1234, for example)

- input_parameter_file is a text file containing specific parameter values that are required to start the collection.

  This file must use the following format:

      col_name = my collection

  col_name is the unique name you want to give to the collection.

      dat_file= <usually same as collection name>.dat

  dat_file is the name of the trace file that will be created.

      cdf_file= <usually same as collection name>. cdf

  cdf_file is the name of the trace definition file that will be created.

      fdf_file= oforms.fdf

  fdf-file is the name of the file containing the forms events that will be traced. This file is always oforms.fdf.

      regid= 1 192216243 0 0 45 <database SID>

  regid is the registration identifier which contains the code for the company (192216243 is Oracle, the code for the product (45=Forms) and other internal information. The <SID> is mandatory but is not used when the Diagnostics Pack is not present.

Once you have started the collection, a process is running and waiting for a Forms application to run in trace mode.

2. Start your Forms in Trace mode

To start your form in Trace mode, you need to add the parameter pecs=trace to the command line.

- In client/server mode on Windows NT:

      ifrun60 module=myModule userid=scott/tiger@orcl pecs=trace

- On the Web using Forms Server, in the HTML page:

  Include pecs=trace as part of the serverArgs parameter defined in the HTML file used for running the form.

- On the Web using Forms Server and the Forms servlet:

  Include otherParams=pecs=trace as part of your specific section in the formsweb.cfg file.

Your application should now be running in trace mode, and all the events occurring during the execution of the aplication are written to two output files specified in the parameter file used to start the collection.

3. Locate the output

Once you have run your Forms application in trace mode, two files will have been generated:

- A file with the .DAT extension containing the trace output in binary format.

- A file with the .CDF extension containing the trace definition.

Those files are located in the following directory:

NT: <ORACLE_HOME>\6iserver\otrace80\admin\cdf

Unix: <ORACLE_HOME>/6iserver/otrace/admin/cdf

4. Stop the collection with the otrccol command

To stop the data collection, enter the following command:

    otrccol stop job_id input_parameter_file

where job_id and input_parameter_file are the same parameters as the ones used to start the collection.

#### 11.5.2.2 Formatting the Output

Once you have generated the trace files, you are ready to fromat the output to view the information you have gathered diring the Forms session. When you don't have the Oracle Diagnostics Pack installed, you can produce text files from the trace files using the Oracle Trace statistics reporting utility.

The Oracle Trace statistics reporting utility displays statistics for all items associated with each occurrence of a server event. These reports can be quite large. You can control the report output by using command parameters. Use the following command and optional parameters to produce a report:

    otrcrep [optional parameters] collection_name.cdf

Oracle Trace creates one text file per event and includes the entire set of items in that event. For example, one file for the triggers, one file for the built-ins, one file for the network, and so on.

#### 11.5.2.3 Using Optional Report Parameters

You can manipulate the output of the Oracle Trace reporting utility by using the following optional report parameters:

#####

Parameters | Description
--- | ---
output_path | Specifies a full output path for the report files. If not specified, the files will be placed in the current directory.
-p [<pid>] | Organizes event data by process. If you specify a process ID (pid), you will create on file with all the events generated by that process in chronological order. If you omit the process ID, you will create one file for each process that participated in the collection. The output files are named as follows: collection Ppid.txt
- P | Creates a report called collection_PROCESS.txt that lists all processes that participated in the collection. It does not include event data. You could created this report first to determine the specific processes for which you might want to create more detailed reports.
-w# | Sets report width, such as -w132; the default is 80 characters.
-i# | Sets the number of report lines per page; the default is 63 lines per page.
-h | Suppresses all event and item report headers, producing a shorter report.
-s | Used only with Net8 data (or SQL*Net for Oracle7).
-a | Creates a report containing all the events for all products, in the order they occur in the data collection (.dat) file.

### 11.5.3 Using Forms and Oracle Trace with the Diagnostics Pack

If you have the Oracle Diagnostics Pack installed, you can take advantage of the tools provided to manage the Oracle Trace collections remotely with Oracle Trace Manager and view the collected data with the Trace Data Viewer.

#### 11.5.3.1 Starting the Collection

To use Oracle Trace Manager, you first have to install Oracle Enterprise Manager on a middle tier machine and install the Intelligent agent on the nodes where you want to collect the data.

For more information about now to install OEM, please refer to the Oracle Enterprise Manager docmentation.

From the Oracle Trace Manager, you are able to:

- remotely discover the node where you will run the Data Collection.

- start the collection on this node using a wizard asking for the name of the collection and some optional parameters.

Once you have started the collection on a node, you can see that the collection is running from the Oracle Trace Manager main screen, and you can stop it at any time remotely from the same tool. Once the Data Collection is running, you can run your Forms applications in trace mode.

#### 11.5.3.2 Formatting the Output

The Trace output generated when using the Trace Manager is the same as when using Oracle Trace from the command line utilities. Only the way you start the collection differs. This means that after the application has been run in trace mode, the two trace files are generated (.CDF and .DAT files) in the CDF directory.

To be able to view the content of the trace with the Trace Data Viewer, the trace output needs to be formatted to a datagase schema. To do this using Oracle Trace Manager, right click on the collection you want to upload to the database and choose the format option. This will automatically format the trace to the database in the schema specified in th Trace Manager preferences.

#### 11.5.3.3 Using the Trace Data Viewer

The trace output is now stored in the database within a specific schema. To view and analyze the content of this trace, launce the Trace Data Viewer and connect to the database with the user name that uploaded the data.

From the Trace Data Viewer, you can analyze:

- The network traffic

- The time spent in the different events

- The CPU consumption for those events

From the Trace Data Viewer main screen, you can drill down to specific information about Forms sessions. For instance, the Network Traffic Statistics contain the number of bytes and packets sent or received, the IP address connected, and the number of roundtrips during the session.

You can drill down to the level of detail you want, going from an overview to a drill-down analysis of specific events, such as: Server, Triggers, Builti-ins, Query, and other types of events. For each of these events, you have a detailed view of the time spent and the CPU consumption for the events. When you choose a detailed view, you can sort the information displayed by CPU consumption or time elapsed by clicking on the column header of the column you want to sort by. For instance, this is very helpful in determining which trigger takes the most time to execute or which built-in consumes the most CPU resouces.

Finally, Trace Data Viewer summarizes all the duration events and point events that occurred during the execution of each form with an average and standard deviation of CPU and elapsed time for all the duration events.

### 11.5.4 Setting Up the Load Balancer Server Trace Log

This section describes the format of Load Balancer Server trace messages. To start a trace, you must restart the Load Balancer Server and specify the <traceLevel> parameter in the forms60_server shell script. The <traceLevel> defaults to 0 for no tracing. Specifying 10 allows you to create trace output for the Laod Balance Server.

#### 11.5.4.1 Trace level 1

Trace level 1 contains a header as follows:

    HOSTNAME:          neko.us.oracle.com    IP ADDRESS: 144.25.83.146
    Data port number:  1234  Request port number:  1235
    Maximum number of clients: 10    Trace level: 2

- Hostname and IP Address: Indicate the D2LS server host name and address.

- Data port number: Indicates the port number where the D2LS server listens for D2LC client messages. This port should be used to configure the D2LC client processes.

- Request port number: Indicates the port number where the server listens for requests for least loaded host information.

- Maximum number of clients: Indicates the number of slots allocated for D2LC clients. One slot is required for each client.

- Trace level: Indicates the amount of Trace information printed to the server log file.

#### 11.5.4.2 Trace level 2

At Trace level 2, messages are given in the following format from a D2LC client. A description of each field follows.

     D:000    144.25.83.92:1236  922541864 1     2  45 3 [cogito]
     |  |          |        |        |     |     |  |  | |
     ^  |          |        |        |     |     |  |  | |  Packet type recv'd
       ^^^         |        |        |     |     |  |  | |  Client index
              ^^^^^^^^^^^^  |        |     |     |  |  | |  D2LC IP Address
                           ^^^^      |     |     |  |  | |  D2LC Port number
                                 ^^^^^^^^^ |     |  |  | |  Time msg recv'd
                                           ^     |  |  | |  Scale factor
                                                 ^  |  | |  Sequence number
                                                    ^^ | |  Number of processes
                                                       ^ |  Last selected
                                                         ^  D2LC Hostname

The description of each field of the trace log is as follows:

- Packet Type Received: Indicates what type of packet was received. The following types are possible:

  - D: Data Received from D2LC Client. For packets with type "D", the remaining data on the trace line corresponds to information communicated from the client.

  - S: Selected client for Least Loaded Host. For packets with type "S", the remaining data on the trace line corresponds to the client selected and returned as the least loaded host.

- Client index: The client index is the internal index for the D2LC client. This index is assigned when a request is first received from the client, starting at 0.

- D2LC IP Address: The IP Address for the client sending the message.

- D2LC Port number: The IP Port number used by the client to send the message.

- Time message received: This is the time that the message was received from the client, in seconds since 00:00:00 UTC, January 1, 1970.

- Scale factor: The scale factor assigned for the client. The scale factor is used as a multiplier against the number of processes in choosing the least loaded host.

- Sequence number: The sequence number is the number of times the client has attempted to send messages to the D2LS server.

- Number of processes: The number of processes reported by the client.

- Last selected: This number indicates the last time a client was selected as a least loaded host. An internal counter in the server is incremented over time. When a client is selected as least loaded host, this counter is stored in the Last Selected field. The D2LC client with the lowest Last Selected field is known to be least recently used. When a request for a least loaded host results in a tie for least number of processes, then the least recently used client is selected to break the tie.

- D2LC Hostname: Shows the hostname of the D2LC client.

#### 11.5.4.3 Sample Trace File

The following is a sample trace file for a two server configuration. Formsvr1 runs a D2L client and D2L server. Formsvr2 runs a D2L client.

    HOSTNAME:          formsvr1.us.oracle.com       IP ADDRESS:   144.25.87.101
    Data port number:  1234 Request port number:  1235
    Maximum number of clients: 10   Trace level: 2

    D:000   144.25.87.101:1000  925260387 1     2    0 0 [formsvr1]
    D:000   144.25.87.101:1000  925260387 1     3   43 0 [formsvr1]
    D:001   144.25.87.102:1001  925260388 1     2    0 0 [formsvr2]
    D:001   144.25.87.102:1001  925260388 1     3   43 0 [formsvr2]
    S:000   144.25.87.101:1000  925260387 1     3   44 1 [formsvr1]
    D:000   144.25.87.101:1000  925260387 1     4   45 1 [formsvr1]
    D:001   144.25.87.102:1001  925260388 1     4   45 0 [formsvr2]
    S:001   144.25.87.102:1001  925260388 1     4   46 2 [formsvr2]
    D:000   144.25.87.101:1000  925260387 1     5   45 1 [formsvr1]
    D:001   144.25.87.102:1001  925260388 1     5   45 2 [formsvr2]
    S:000   144.25.87.101:1000  925260387 1     5   46 3 [formsvr1]
    D:000   144.25.87.101:1000  925260387 1     6   47 3 [formsvr1]
    D:001   144.25.87.102:1001  925260388 1     6   47 2 [formsvr2]
    S:001   144.25.87.102:1001  925260388 1     6   48 4 [formsvr2]
    D:000   144.25.87.101:1000  925260387 1     7   47 3 [formsvr1]
    D:001   144.25.87.102:1001  925260388 1     7   47 4 [formsvr2]

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|  |  | Contents | Index