Troubleshooting
It contains an outline of common causes for errors, the method you can use to verify your installation, and the tools and techniques provided to diagnose problems. The appendix is also a subset of the Oracle9i Forms Diagnostic Techniques white paper.
The following topics are included:
Accessing the Listener Servlet Administration Page
You can display a test page for the Listener Servlet by accessing the following URL:
http://<
hostname
>:<
port
>/forms/frmservlet/admin
/forms/frmservlet/admin
) has always been helpful for troubleshooting, but was previously difficult or risky to enable because it required modifying the Forms J2EE deployment plan. Enable this utility by setting allow_debug=testmode
in the Forms Web Configuration (formsweb.cfg
). Valid values for allow_debug
are:
Table -58 allow_debug Values
Value | Description |
---|---|
|
Blocks Servlet Administration pages and the commands associated with it. Servlet debugging and logging is disabled. The Forms Listener Servlet status page is presented. |
|
Enables various debug and ODL logging functions exposed by Forms, as well as enabling Servlet Administration specific commands. Servlet Administration test page is not accessible. Forms Listener Servlet status page is presented. |
|
Same as setting to TRUE , however allows access to the Servlet Administration test page.
|
|
Blocks Forms Listener Servlet status, Servlet Administration page, and the commands associated with it. Servlet debugging and logging is disabled. |
Note:
By defaultallow_debug
is disabled (FALSE
). It is recommended that this parameter only be set to TRUE
or TESTMODE
during troubleshooting. It should not be set to TRUE
or TESTMODE
unless explicitly being used by administrators during testing.
Verifying the Installation
If there is something wrong with the installation, then it will result in faulty configuration and Oracle Forms will not run correctly.
After the Oracle Universal Installer indicates that Fusion Middleware was successfully installed, you can verify whether Oracle Forms Services is correctly configured or not.
-
Web Form Tester
Using the Web Form Tester
The Web Form Tester is available with your Oracle Fusion Middleware installation.
To verify whether the Oracle installation and configuration of Forms Services is correct, run the Web Form Tester. To verify an installation, this should be performed on the middle tier where the installation occurred.
These steps assume that WebLogic Server and Oracle Forms have already been installed, the Configuration Wizard run successfully, and Node Manager, Admin Server, and WLS_FORMS have been started. It is also assumed that a Java Plugin has been installed and configured for the browser.
-
Incorrect host name and/or port number used.
-
WLS managed server (e.g. WLS_FORMS) is not running.
-
Incorrect network configuration on server host and/or client.
-
Installation and/or post installation Configuration not successfully completed.
Diagnose FRM-XXXXX Errors
Use the Oracle Forms Applet tool to diagnose and resolve FRM-XXXXX errors.
The Oracle Forms Applet
The brief message about the FRM error should help in identifying the basic cause of the problem. Often, everything required to identify the cause an FRM error is contained in the error reported by the Forms applet. When a FRM error is raised, the error dialog will have a Details button. Click the Details button will show the current Java stack. The exact stack is tied to the root cause and the version of Oracle Forms. This is due to the differing package structure used for the applet class files in the different releases.
Diagnosing Server Crashes with Stack Traces
If the Forms web runtime terminates unexpectedly, then it writes a stack trace to the directory $DOMAIN_HOME/system_components/FORMS/forms1/trace
.
The filename will have the format <forms_runtime_process>_dump_<process id>
.The dump file contains a stack trace of the running process, and shows the last successful operation performed by Forms. This core file users can use to assemble a stack trace with symbol names using GNU Debugger, dbx or similar debugging tool on the machine where the dump occurred.
The following topics are included:
Stack Traces
A stack trace is useful for the following two reasons:
-
The information in the stack is used to identify a known issue. It is not 100% reliable, but an identical stack trace is a good indicator of a matching problem. Even if it is not the same, there may be a workaround or patch for an existing bug that can be tested.
-
If the problem is not a known bug, then the stack may provide valuable information to assist development efforts to pinpoint the cause.
Configuring and Using Stack Traces
To configure and use Stack Traces you have to verify the environment, and understand UNIX and Windows Stack Traces.
Verifying the Environment
To test stack tracing on UNIX or Windows you can set the environment variable FORMS_DELIBERATECRASH
. As the name suggests, setting this will cause the forms runtime process to crash. Oracle Forms currently recognizes two settings: 1
and 2
. If FORMS_DELIBERATECRASH
is set to 1
then forms will crash at runtime whenever the BELL Built-in is executed. If it is set to 2
then forms will crash at runtime whenever a when-button-pressed trigger is fired. This environment variable can be set in the environment (for example, default.env
) file.
Understand UNIX Stack Traces
In a UNIX stack trace, the top two functions siehjmpterm()
and sigacthandler()
are the signal handling code - these functions will often be present in the stack trace. To see the function the program was in when the error occurred you need to read further down the stack.
If you set FORMS_CATCHTERM=0
the two functions do not show up in the dump file. The stack trace is displayed without the crash handling symbols.
Note:
FORMS_CATCHTERM
is deprecated and should no longer be used. It has been replaced with FORMS_ABTERM_CLEANUP
.
Understand Windows Stack Traces
Stack tracing works differently on UNIX and on Windows. The symbol information is contained inside the executable files and shared libraries on Unix. On Windows this information is stripped out at link time and is in the form of binary .sym
files. There should be one .sym
file for every Oracle Forms executable or DLL. The .sym
files are installed by default. On Windows the files are located in the ORACLE_HOME\bin
directory. The mechanism on Windows platforms is such that in the event of a crash the Forms runtime process reads all the .sym files that correspond to the forms executable files loaded into memory. It then uses the information in the .sym files to lookup the symbol name.
Diagnosing Client Crashes
Information is provided about diagnosing client crashes and diagnosing hanging applications.
Client Crashes Diagnosis
If the Forms applet disappears unexpectedly, accompanied by a dialog indicating a fatal error, then the Forms applet has crashed. On Windows, a crash will result in the operating system raising an 'illegal operation' dialog, or may cause the "Not responding" flag in Task Manager. To verify the crash, check for a stack trace file on the client. If the client has crashed then a file with the .rpt extension will be created in the same directory as the executable. The root of the filename will be the name of the executable.
Sometimes the applet may appear to have crashed, but no corresponding .rpt
file can be found. In this case it is likely that the Oracle Forms has unexpectedly disconnected from the client. The applet will still be running, but it has shutdown all the Forms windows, giving the appearance of a client crash.
Hanging Applications Diagnosis
If the client appears to hang then it is important to verify that the server process is still alive. If the server process has not crashed, but the client no longer appears to respond to user interaction then the application is said to be hanging.
In such cases a thread dump can point to the deadlock. A thread dump can be obtained by pressing t
in the Java console. This displays a list of all the threads running in the client JVM.
The information contained in the dump file is extremely useful to Oracle development, and should be included in any bug filed to report the problem.
Causes of Hanging Applications
One cause could be a mismatch between the Java class files and the Oracle Forms version. Communication between the applet and the Forms runtime process is based on message ID. If these message ID's are out of sync, then the applet may not understand an instruction from the server, and vice versa. If you are using JAR files, then try with the <ARCHIVE>
tag removed. If the problem persists then pull the correct class files off the installation/patch CD by hand.
One possible cause of a hanging or crashed appearance is that the Forms Runtime process may have died. Check if the Forms Runtime process on the server is still alive. Check that the FORMS_TIMEOUT
parameter is set. It defines how long the server should wait for a ping from the Oracle Forms client, only cleaning up the runtime process when there has been no activity from the Forms client for the specified time. The client sends out a HEARTBEAT
every two minutes by default. If FORMS_TIMEOUT
is set to two minutes or longer, the server will stay up as long as it hears a HEARTBEAT
from the client. Set to shorter than the HEARTBEAT
interval, it will shut down after the interval specified in FORMS_TIMEOUT
. You can set the interval by setting the HEARTBEAT
applet parameter in formsweb.cfg
, see Configuring Asynchronous Communication. Although this is primarily intended to prevent orphaned server processes, it can also prevent the unwanted premature cleanup of server processes.
Forms Trace and Servlet Logging Tools
Forms Trace and Servlet Logging are two more tools to use in troubleshooting your Oracle Forms Environment.
To configure and use Forms Trace, see Forms Trace and Taking Advantage of Oracle Diagnostics and Logging Tools.
Resolving Memory Problems
To resolve memory problems you have to learn how Java applet uses memory, setting the initial Java heap, and memory leaks.
The following topics are include:
How Java Uses Memory
Like all software programs, a Java applet uses memory. For Java, the language specification requires a 'garbage collector', which is in an internal memory manager for the Java Virtual Machine (JVM). When a Java program needs memory, it requests this memory from the JVM. If there is no memory left, then the JVM will attempt to free some memory by using the garbage collector. The garbage collector will try to release memory that is no longer required to run the program back to the JVM. If there is still insufficient memory to perform the required task then the JVM will attempt to get more memory from the operating system. If that memory allocation fails, then the Java program will be unable to continue.
Setting the Initial Java Heap
You can specify the initial Java Heap (the memory used by the JVM) for your application through Fusion Middleware Control. For the client, you can change the setting in the Java control panel after you've installed the Oracle Java Plug-in.
Note:
The JVM will only use the memory it is told it is allowed to use. Even if you have memory available with the operating system, the JVM will not use it if told not to.
Memory Leaks
A memory leak is an error in a program's dynamic-store allocation logic that causes it to fail to reclaim discarded memory, leading to eventual collapse due to memory exhaustion.
For example, when a program runs it may need to allocate some memory to perform a particular task. If the program has finished with that memory and no longer has any use for it, but fails to make that memory available to other programs running on the computer, then it is said to have leaked the memory.
A typical method used to spot memory leaks is to repeat a series of steps, and observe the memory in use by the application - if the memory usage continues to rise with each iteration, then the assumption is often that the program has a memory leak.
However, some complex applications may choose to retain control of memory it has previously allocated so that it can reuse it at a later point - memory allocation can be an expensive operation, and if the program expects that it will need more memory later it may be more efficient to keep the unused memory available for reuse.
Memory Leaks in Java
The Java language specification demands that the JVM has a garbage collector. In Java, the programmer allocates memory by creating a new object. There is no way to deallocate that memory. Periodically the garbage collector sweeps through the memory allocated to the program, and determines which objects it can safely destroy, therefore releasing the memory. To determine which objects it can safely destroy, the garbage collector uses a 'mark and sweep' algorithm. The garbage collector scans the dynamically allocated memory for objects, marking those which still have active references to them.
After all possible paths to objects have been investigated, unmarked objects that are known to be no longer needed can be garbage collected. A common myth with Java programming is that the presence of a garbage collector means that there can be no memory leaks. This is not true because the garbage collector simply marks those objects, which have active references, and destroys those that do not. It is possible to have an active reference to an object that is no longer needed. This is a memory leak in Java. The solution to the leak is to destroy the references to the object once it is no longer needed so that the garbage collector can identify it as safe to destroy. If a memory leak exists in a Java program, then calling the garbage collector more frequently will not help.
To complicate matters further, the JVM may choose not to release unused memory back to the operating system. In the real world this seldom matters, as most programs will typically require more memory at some point in the near future and can reuse the free memory in the JVM. However, it is worth bearing in mind that not all the memory allocated to the JVM will be in use by the program running in the JVM.
Identifying Memory Leaks
Typically, if a growth in memory usage is observed each time a particular series of operations is performed, then it is a memory leak. The ideal proof is to:
- Get the form into an initial base state, and record the memory usage,
- Perform a series of steps to illustrate the problem,
- Return to the initial base state, and record the memory usage.
By repeating steps 2 and 3, it is possible to determine whether there is a steady memory leak or not. If the growth in memory is small over a large number of iterations, then it may not be a leak at all; it could be that the JVM is retaining unused memory, or the garbage collector is not activating as frequently as expected.
Improve Performance with Caching
When any Java program runs, the Java Virtual Machine needs to load class files. When running over the Internet, the time taken to download a class file each time the program runs can lead to performance problems. To solve this download problem, the JDK supports Java Archive (JAR) files. A JAR file is simply a collection of class files bundled into one compressed file. Typically, the size of the JAR file will be much smaller than the combined size of the class files it contains.
When the JVM first references a class, it checks the local computer to see if any of the previously cached JAR files contain this class. If the class does exist in one of the pre-cached JAR files, then the JVM checks to see if there is a newer version of this JAR file on the application server. If there is a newer JAR file available then the new copy of the JAR file is downloaded to the client cache. If the cached JAR file is up to date, then the class file is loaded from the cached JAR file rather than from over the network.
Caching is important because if the application JAR files do not change, then after the application has run once, and all the JAR files required have been cached on the client, then subsequent invocations of the application will always load the classes from the local cached copies. This can lead to significant performance improvements in the startup time for the application. If new classes are needed to run a specific part of the application, these will be downloaded as required.
Troubleshooting Tips
The troubleshooting list in this section will help you deal with complex issues, but it is not a definitive guide to problem solving or a guaranteed set of solutions to your Oracle Forms environment.
Be methodical
Do not immediately leap to the area you believe to be the cause based on a hunch, or a guess - make sure you eliminate the other possibilities first. An easy trap to fall into is that of spending long periods of time trying to find evidence to support your theory, rather than concentrating on what the evidence shows. Do not overlook the trivial or the obvious.
Divide the problem into sections
-
Chop the problem into manageable sections - this helps eliminate whole areas from investigation. As you investigate an area and satisfy yourself that the problem does not lie there, you can proceed to the next section. An approach to diagnosing a problem that is often successful is to reduce it to its essential parts. This will be important if you need to discuss the problem with Oracle Support Services to obtain a solution.
-
Define what happens, when it happens, how often it happens. Of equal importance is, understanding what does not happen, when it does not happen etc. For example, if a group of users in the same building all get the problem, and it always happens between 9 and 10am, it is just as important to know that it never reproduces in another building, or after 10pm. Perhaps the users only use a particular Form between 9 and 10, or the load on the system is highest between 9 and 10am.
Read the error messages
It sounds obvious, but often the solution information is within the error text. This document will help you understand the error messages, and help identify what action to take.
Make sure you can reproduce the problem, if possible
If you can reproduce the problem yourself, you may notice some behavior that the end user never spotted - perhaps it had always happened, so they simply assumed it was meant to happen. If you can reproduce the problem then you have already started the first step to resolve it.
Make sure you understand the tools you are trying to use
If you decide to use a diagnostic tool, make sure you know how to use it, and how to interpret the data it produces. Time spent in investigating the usage of a tool before the problem happens is time well invested. Make time to learn the tool as well.
Need More Help?
If this Troubleshooting Oracle Forms Services appendix does not solve the problem you encountered, try looking for a solution on My Oracle Support, see https://support.oracle.com/ (formerly Oracle MetaLink). You can also raise a service request, if you are unable to find a solution for your problem. See Release Notes for Oracle Forms and Reports.