|
Oracle® Application Server Forms Services Deployment Guide
10g Release 2 (10.1.2) B14032-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Forms Services Deployment Guide
10g Release 2 (10.1.2) B14032-02 |
|
|
Previous |
Next |
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/.
If there is something wrong with the installation, then it will result in faulty configuration and Oracle Forms will not run correctly. Fortunately, after the Oracle Universal Installer says that Oracle Application Server or Developer Suite was successfully installed, you can be verify whether Oracle Forms services is correctly configured or not. You can use these tools as solutions:
Section A.1.1, "Use The Web Form Tester"
Section A.1.2, "Find Port Information"
The Form Tester is available with your Oracle Application Server or Developer Suite installation. To verify whether the OracleAS 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.
Start Oracle HTTP Server by selecting Start | Program Files Oracle Application Server-AS Home | Oracle HTTP Server | Start HTTP Server, if it is not already started.
For Oracle Developer Suite, start the OC4J instance (if not already started) by selecting Start | Programs | Oracle Developer Suite - DevSuiteHome | Forms Developer | Start OC4J Instance.
Open an instance of the browser by typing ORACLE_HOME/tools/web/html/runform.htm for the URL and hit the ENTER key. Replace ORACLE_HOME with your actual Oracle home for OracleAS or Developer Suite.
You may also run the Web Form Tester by selecting Start | Program Files | OracleAS–Home for AS | Forms Developer | Run a Form on the Web from the Windows Start menu for OracleAS.
For Oracle Developer Suite, select Start |Program Files|Oracle Developer Suite–Home for DS | Forms Developer | Run a Form on the Web from the Windows Start menu.
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.
If the installation of OracleAS or Developer Suite is correct, you'll see a success message in the Web browser. Also, it can be tested from a client computer whether the basic Forms setup in OracleAS or Developer Suite 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://myserver.com: NNNN/forms90/f90servlet?form=test.fmx.
Use these tools to diagnose and resolve FRM-XXXXX errors:
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.
If you are using JInitiator and a Java error is encountered then the error will be written to the browser status line. However, this does not show the full Java error stack. You need to look for it in the JInitiator Java console.
If you have turned the Java Console on, by checking its option in JInitiator Control Panel Applet on a Windows computer, the JInitiator Console window will pop up when your Form runs in a browser. The JInitiator Control Panel Applet can be found on the Start | Settings | Control Panel option in Windows. If JInitiator's Java console does not appear, you can always invoke it manually from the taskbar tray icon by double clicking it.
While running your Forms application, you may encounter various FRM errors. These errors can be raised by several different conditions. When you receive these errors, you will need to obtain more information to resolve it. In this section we will see some of the common errors that one may encounter and how to resolve them.
Broadly speaking, the FRM errors occur due to the following.
Configuration Problems:
Some FRM errors are raised by configuration problems. For example, the Forms Service is not started, or is listening on a different port to that specified in the HTML file. Typically these errors will reproduce consistently.
Forms server process has crashed:
The majority of FRM errors that occur after a successful connection has been established and the form started, are due to the server crashing. Once the server process has died, then the client cannot continue running - the applet has no life of its own, and it cannot continue to run without being able to communicate with the server process.
These errors are often difficult to diagnose: the problem may not reproduce consistently, or the user may be unaware of the sequence of events that led to the crash.
Network Problems:
The communication between the applet and the Forms Server process has experienced network problems, and the communication has been broken.
The following table lists the FRM -92xxx errors caused by these reasons. It also briefly explains what they mean.
| Error | Description |
|---|---|
| FRM-92000 | This is an internal error that occurs when the Java language throws an IllegalAccessException whilst we are trying to load some class files. It usually indicates that the system is misconfigured in some way. The detail message often helps to work out why it occurred. |
| FRM-92010 | This is a Client mis-configuration error that occurs when the Applet parameter "serverArgs" is either not present or has a null value. |
| FRM-92020 | Indicates that either the URL, or the Browser Target, requested was rejected in some way by the browser. |
| FRM-92030 | A Client mis-configuration error, due to a missing Java class file and/or registry mis-configuration. This error occurs when the Server requests a Java class, by numeric "handlerClassId" that the client can't handle since it's not in the registry. |
| FRM-92040 | A Server mis-configuration error, due to a missing Java class file. This error occurs when the Client requests a Java class that couldn't be located on the server. |
| FRM-92050 | The Client was unable to establish a connection to the server computer (host) on the designated socket (port). |
| FRM-92060 | The Client was unable to establish a connection to the Server because the format of the host/port combination was invalid. |
| FRM-92070 | The Client was unable to create a new Object for some reason. The Full details may give some indication as to why the error occurred. (This will not stop the working of the form, it is logged only in the log file) |
| FRM-92080 | Executing an Operating System command, in an attempt to start an external Browser module, caused some problem. |
| FRM-92090 | An Unexpected error occurred. |
| FRM-92095 | The version of JInitiator being used is too low to support the requested functionality (e.g. to run against the Listener Servlet). User should install the specified version (or greater). |
| FRM-92100 | An Unexpected Network error or server failure occurred. |
| FRM-92101 | An unexpected server failure occurred due to some misconfiguration on server side. |
| FRM-92102 | An Unexpected Network error occurred, after trying to reconnect for a specific number of times by Forms. |
| FRM-92120 | A Server configuration error that indicates that an important file (the Registry) could not be located by the client. |
| FRM-92145 | The text used to describe Single Sign-On Authentication failed. |
| FRM-92150 | The version of the client is newer than the version of the server. |
| FRM-92160 | The version of the client is older than the version of the server. |
| FRM-93000 | Generic internal Exception message. Used when some unexpected code error occurs. |
While most of the above FRM errors are self-explanatory, there are a few which are caused for different reasons and are difficult to diagnose. The following topic explains such FRM errors, the possible causes for them, and their solutions.
Cause:
This error can occur when JInitiator uses the browser's proxy setting.
Solution:
Go to Control Panel | JInitiator 1.3.x.x | Proxies and deselect Use Browser Settings and enter the details for the proxy settings.
Heavy load on the server.
Cause:
If there are many simultaneous requests that the server cannot handle. This mainlydepends on the server computer performance and configuration.
Solution:
The Forms Runtime Prestart feature of Oracle Application Server Forms Services 10g comes in handy in this situation. This feature pre-spawns a configurable number of runtime engines to handle incoming client requests, and avoiding application or server hangs because of a rush.
Upgrade the hardware of the server computer to handle the high number of simultaneous requests.
Missing serverURL Parameter
Cause:
The serverURL parameter is either missing or incorrect, in the configuration file(formsweb.cfg)
Solution:
Edit the forms configuration file to enter a valid serverURL parameter value.
Wrong FORMS_TIMEOUT
Cause:
The value of FORMS_TIMEOUT parameter is entered wrongly.
Solution:
Verify the environment file (default.env) and the registry for the FORMS_TIMEOUT parameter value. The value should be a proper integer. The value should not be in quotes, for example:
FORMS_TIMEOUT="10" This is an incorrect entry.
FORMS_TIMEOUT=10 This is the correct entry.
Incorrect Use of RUN_PRODUCT
Cause:
RUN_PRODUCT should only be used, in Oracle Forms, for integration with Oracle Graphics 6i.
Solution:
RUN_PRODUCT Built-in calls that are used to integrate Oracle Forms with Oracle Reports should be replaced using the newer RUN_REPORT_OBJECT Built-in.
Missing ServerArgs parameter
Cause:
The ServerArgs parameter is missing from the HTML, which loads the applet.
Solution:
Make sure that the HTML file, used to load the forms applet, has the ServerArgs parameter in it.
Make sure that the value of the ServerArgs is not null. Remember, the Form name is required in ServerArgs. These parameters can be defined in the Oracle Forms configuration file (formsweb.cfg) or can be directly passed in the URL that is used to run the Form.
Missing jvm.dll
Cause:
The Forms Web executable frmweb.exe is not able to find the jvm.dll
Solution:
Ensure that jvm.dll is located in a directory specified in the PATH environment variable. Set the PATH environment variable in formsweb.cfg, which is typically ORACLE_HOME/forms/server/default.env, to point to the location of the jvm.dll.
Cause:
This error occurs if the Web server is shutdown when the user is accessing the application
Solution:
Check if the Web server is up and running. Try the URL http://servercomputer:portno. If the OC4J home page does not come up, then it indicates that the Web server is down. Contact your Forms or server administrator to start the Web server.
Wrong working directory
Cause:
This error can occur if the working directory specified does not exist.
Solution:
This can be confirmed by looking for a log message like ÒUnable to switch to Working Directory:<workingDirectory>Ó in the application.log file. The application.log file can be found in the application-deployments/formsapp directory of the OC4J instance on which Oracle Forms is deployed.
Edit the forms configuration file with the correct working directory.
FORMS_TIMEOUT and heartbeat
Cause:
This error can occur if the forms applet parameter 'heartbeat' is set to a value more than FORMS_TIMEOUT.
Solution:
Generally, heartbeat is set to a value higher than that of FORMS_TIMEOUT, only when the application is desired to time-out after a certain time of inactivity. It is then, you would get a FRM -92120.If that is not desired for a particular application, then, make sure that the value of heartbeat is less than that of FORMS_TIMEOUT.
Cause:
This error can occur because of the network problems between the Web server and the client. The client is not able to communicate with the server on the specified port.
Solution:
Add the parameter networkRetries to the forms configuration file. Set the value to a suitable number according to the network characteristics and needs, for example, networkRetries=30 This parameter specifies the number of times the Forms client should try reconnecting to the middle tier before finally timing out.
Ports Blocked
Cause:
If the error occurs even after setting up an appropriate value for networkRetries, it could be due to the ports on the web server restricted at TCP/IP level.
Solution:
A socket connection requires a port at each end. If the port is closed it causes the communication stoppage. Firewall and proxies are used to protect the ports. Removing the blocks on the ports on the Web server solves the error.
Cause:
This is a server configuration error, which occurs when the client is unable to find the file Registry.dat on the middle tier.
Solution:
When this error occurs, check if the file Registry.dat is present on the middle tier in the directory ORACLE_HOME/forms/java/oracle/forms/registry. If it is not present, then it needs to be placed.
In a running Forms application, if you suddenly come across this error, there is a possibility that the HTTP server has gone down. You may verify this by typing the URL http://myserver.com:NNNN in your browser. Here you need to replace myserver.com with your host name and NNNN with your HTTP server's port number. If your browser says that it could not connect to the server, then your HTTP server is down and you need to contact your system administrator to bring it up.
When the HTTP server is up and running, on giving the URL http://myserver.com:NNNN your browser will show the ÒOracleAS welcomeÓ.
Cause:Wrong path and/or codebase setting.Solution:Set the proper ORACLE_HOME/bin in the beginning of the system path. The CODEBASE entry in your HTML file or forms configuration file may point to older versions of the Jar file. Either modify the codebase entry in your configuration file or replace the jar file in the codebase path with the appropriate jar file.Clearing the Oracle Jar cache in the user profile directory of the client computer makes sure that the fresh Forms Jar files are downloaded.
This section contains the following:
If the Forms web runtime terminates unexpectedly, then it writes a stack trace to the directory ORACLE_HOME/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.
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.
This section contains the following:
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. The stack above was generated with FORMS_DELIBERATECRASH set to 2. This environment variable can be set in the environment (for example, default.env) file.
By setting the environment variable FORMS_DELIBERATECRASH to 2, and checking the stack trace produced against the one in this document you can determine whether the symbol files are correctly installed. Once you have confirmed that everything is working as expected, if you subsequently encounter a problem where the server has crashed, you can be sure that the stack trace will be useful in resolving the problem.
In a Solaris 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.
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 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.
This section contains the following:
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. If you're using Appletviewer that was started from the directory c:\jdk\1_3_1\bin, the client stack trace file will be c:\jdk\1_3_1\bin\appletviewer.rpt.
If you're using JInitiator, then the executable is considered to be the Web browser. If the browser is Netscape, the client stack trace file will be netscape.rpt, whereas for Internet Explorer it will be iexplore.rpt.
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 Server process 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.
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.
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.
One cause could be a mismatch between the Java class files and the Oracle Forms server version. Communication between the applet and the Forms server process is based on message ID. If these message ID's are out of synch, 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. The timeout facility acts like a heartbeat and expects the Oracle Forms client to 'ping' the server on a set interval, only cleaning up the Oracle Forms Server process when there has been no activity from the Forms client for the specified time. Although this is primarily intended to prevent orphaned server processes, it can also prevent the unwanted premature cleanup of server processes.
A stack dump can be obtained from an Appletviewer by pressing CTRL+BREAK in the command prompt (or DOS session) that you started the Applet-viewer from.
For JInitiator, the Java console shows how to output dump information. Follow the onscreen instructions to view it.
The information contained in the thread dump can help Oracle development identify the problem in the code. The thread dump should be included in any bug filed to report the problem.
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 8, "About Forms Trace" and Chapter 8, "Servlet Logging Tools".
This section contains the following:
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.
You can specify the initial Java Heap (the memory used by the JVM) for your application through Enterprise Manager or at the command line in the middle tier. For example, the following command will set the initial 'Java Heap' (the memory used by the JVM) to 20MB, and the maximum memory to be used by the JVM to 32MB:
appletviewer -J-ms20m -J-mx32Mb dve.html
The default initial and maximum sizes for Appletviewer are 16MB and 20MB respectively.
When using JInitiator, you will need to set the runtime options in the JInitiator control panel.
|
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. |
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.
The Java language specification demands that the JVM has a Garbage Collector (GC). 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. 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.
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.
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.
In addition to reducing the amount of data to be transferred, Jar files also allow JInitiator and Oracle's JDK to use a process referred to as caching. Starting with OJDK 1.1.7.15, several performance improvements were made to the caching process.
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.
While caching means that the Jar file will not be downloaded from the server every time the application is invoked, there were still some issues affecting performance. Since the Jar files contain compressed data, the time to decompress this data from the cached Jar file outweighs the time saved in downloading less data from the network.
Jar files can be digitally signed and undergo authentication to ensure they have not been modified in transit over the network. This procedure involves expensive mathematical calculations. The new caching mechanism introduced in OJDK addresses these issues in the following way:
When the Jar file is downloaded for the first time, two files are created:
A data file, which contains all of the unzipped data from the Jar file. Data files have the extension .dxx, where xx is a number between 00 and 99. For example 10f756b8.d00.
An index file which contains information about the Jar file, including the URL it was loaded from, the date it was last modified on the server, and a table of contents. The table of contents lists all of the entries in the Jar file, their offsets in the data file, and the authentication status of each entry. Index files have the extension .ixx, where xx is a number between 00 and 99. For example 10f756b8.i00.
The information in these files is stored in a binary format. There is no easy way to read them by eye, and there is little value in doing so.
The first eight characters of all cache files represent the URL where the Jar file was downloaded from. This allows the caching mechanism to quickly find a URL in the cache by mapping the URL to its corresponding eight-character representation and looking for files with that name.
When a class file is required by the application, OJDK uses the information in the table of contents to locate the class file in the data cache. If the data was digitally signed, then the list of authenticated signers is read from the data file.
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
Don't 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.Don't 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.
In case the information in the previous sections was not sufficient, you can find more solutions on Oracle MetaLink, http://metalink.oracle.com/. If you do not find a solution for your problem, log a service request.
|
See Also:
|
