A Troubleshooting Oracle Forms Services

This chapter contains the following:

This chapter provides information to help you resolve problems that might occur when you run an application over the Web using Oracle Forms. 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.

This chapter is also a subset of the whitepaper Oracle Forms Diagnostic Techniques that can be found at http://www.oracle.com/technology/products/forms/.

A.1 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 Control was successfully installed, you can verify whether Oracle Forms Services is correctly configured or not. You can use these tools:

Section A.1.1, "Use The Web Form Tester"

Section A.1.2, "Find Port Information"

A.1.1 Use 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 on the middle tier. The following is an example of how this can be done on a Windows computer.

  1. Start the Admin server for the WebLogic Server domain by selecting Start | Program Files |Oracle WebLogic Server | User Projects | Domain | Start Admin Server for WLS Domain, if it is not already started.

  2. If the managed server is not up, perform the following steps:

    1. Start the node manager by selecting Start | Program Files |Oracle WebLogic | WebLogic Server 11gR1 | Tools | Node Manager, if it is not already started.

    2. Start Forms Services from the WebLogic Administrator Console.

  3. Open an instance of the browser by typing <ORACLE_HOME>/tools/web/html/runform.htm for the URL and press ENTER. Replace ORACLE_HOME with your actual Oracle home for Oracle Fusion Middleware.

  4. Alternatively, you can run the Web Form Tester by selecting Start | Program Files | <Oracle_Home> | Forms Services | Run a Form on the Web from the Windows Start menu for Oracle Fusion Middleware.

  5. Enter the Web port and click the Run Form button. See Section A.1.2, "Find Port Information" to learn how to find out the Web port.

  6. If the installation of Oracle Fusion Middleware is correct, you will see a success message in the Web browser. Also, it can be tested from a client computer whether the basic Forms setup in Oracle Fusion Middleware on the middle tier is installed correctly or not by the installer. You can run the test form from any client computer by running it from the browser with the URL http://example.com:NNNN/forms/frmservlet?form=test.fmx.

A.1.2 Find Port Information

When in doubt or you need to know what port numbers to use to run Forms after installation, you can look at port information in the file <ORACLE_HOME>/install/portlist.ini. Use the appropriate port numbers for your installation.

A.2 Diagnosing FRM-XXXXX Errors

Use these tools to diagnose and resolve FRM-XXXXX errors:

A.2.1 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. Pressing 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.

A.3 Diagnosing Server Crashes with Stack Traces

This section contains the following:

If the Forms web runtime terminates unexpectedly, then it writes a stack trace to the directory $ORACLE_INSTANCE/FormsComponent/forms/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 can be used to assemble a stack trace with symbol names using GNU Debugger, dbx or similar debugging tool on the machine where the dump occurred.

A.3.1 About Stack Traces

A stack trace is useful for two reasons:

  • The information in the stack can be 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.

A.3.2 Configuring and Using Stack Traces

This section contains the following:

A.3.2.1 Verifying the Environment

In order 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.

A.3.2.2 Understanding 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.

A.3.2.3 Understanding 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.

A.4 Diagnosing Client Crashes

This section contains the following:

A.4.1 About Diagnosing Client Crashes

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.

A.4.2 Diagnosing Hanging Applications

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.

A.4.2.1 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.

Another cause 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. For more information, see Section 8.6.3, "Configuring Asynchronous Communication." Although this is primarily intended to prevent orphaned server processes, it can also prevent the unwanted premature cleanup of server processes.

A.5 Forms Trace and Servlet Logging Tools

Forms Trace and Servlet Logging are two more tools to use in troubleshooting your Oracle Forms Environment. For more information on configuring and using Forms Trace, see Chapter 12, "About Forms Trace" and Chapter 12, "Taking Advantage of Oracle Diagnostics and Logging Tools".

A.6 Resolving Memory Problems

This section contains the following:

A.6.1 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.

A.6.2 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 Sun 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.

A.6.3 About 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.

A.6.3.1 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 de-allocate 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.

A.6.3.2 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:

  1. Get the form into an initial base state, and record the memory usage,

  2. Perform a series of steps to illustrate the problem,

  3. 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.

A.6.4 Improving 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. In order 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.

A.7 Troubleshooting Tips

The following troubleshooting list 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.

A.8 Need More Help?

In case the information in the previous sections was not sufficient, you can find more solutions on My Oracle Support (formerly OracleMetaLink), http://metalink.oracle.com/. If you do not find a solution for your problem, log a service request.

See Also: