Technology and Community

Jim O'Neil

Subscribe to Jim O'Neil: eMailAlertsEmail Alerts
Get Jim O'Neil: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

PowerBuilder: Article

EAServer Problem Analysis & Troubleshooting

Part Art, Part Science Part 1

Designing and implementing an n-tier or Internet application is a complex task, and issues resulting from errors in the runtime configuration or the application code itself are practically inevitable. Problem analysis and troubleshooting are part art, part science. Therefore, although the techniques discussed here can be helpful, the sheer diversity of client and server environments precludes a single recipe for resolving all issues.

We'll focus on problems that involve PowerBuilder that occur from the point of connectivity all the way through an EAServer component's lifecycle, and close with a troubleshooting checklist of potential resolutions to some of the more common error situations.

Client and Server Environment
One of the first techniques for validating both the client and EAServer environments involves checking the versions and locations of the PowerBuilder executable modules (DLLs on Microsoft Windows platforms) and Java classes that are loaded at runtime. In terms of PowerBuilder clients and components, Sybase recommends that the version of the PowerBuilder Virtual Machine (VM) on the client machine match that used by EAServer. This is required rather than recommended when using proprietary techniques such as the blob format used in DataWindow synchronization (for example, the getFullState and setFullState methods).

Client Requirements
Client requirements for PowerBuilder applications that access EAServer are no different than those for client/server applications. Specific requirements are detailed in the "Application Techniques" manual accompanying the PowerBuilder product, and include the PowerBuilder VM (PBVM90.DLL), the DataWindow engine (PBDWE90.DLL), database interface libraries and the EAServer client ORB implementation (LIBJCC.DLL).

NOTE: Client applications built using the initial release of PowerBuilder 9.0 require that one additional DLL, LIBJSYBHEAP.DLL, be deployed. Beginning with the 9.0.1 maintenance release, this DLL is no longer required because its functionality has been subsumed by PBVM90.DLL.

All of the PowerBuilder DLLs used for a given client application must be of the same build.

Although LIBJCC.DLL ships with PowerBuilder, it's actually an EAServer module and, as such, isn't stamped with a specific version number. Because the implementation is backward-compatible, your client application should use the LIBJCC.DLL shipped with the most recent version of EAServer to which it may connect. Several tools are available to determine what DLLs have actually been loaded by your client application. The Sysinternals web site ( has many useful diagnostic tools, including listdlls and ProcessExplorer, that can be used for this. You can even get a list of modules loaded through the About dialog box in Microsoft Word.

Server Requirements
All versions of EAServer have a serverstart.bat file (or file on Unix platforms) that contains the core of the environment setup and the actual command to launch the server executable image (jagsrv). In EAServer 4.0 and later, a setenv and optional user_setenv command file accompany the serverstart script. When the serverstart script is invoked, it invokes the other two scripts to set site-specific environment requirements complementing those required by the core EAServer product. The primary environment variables used by EAServer 4.0 and later are shown in Table 1.

For most installations, neither the serverstart nor the setenv script requires modification. A user_setenv script may be required, though, to supply additional libraries or classes. For example, Informix JDBC connection caches require that the IBM Informix JDBC driver classes be located on the CLASSPATH, and Oracle OCI caches on a Windows 2000 server require that the Oracle client software be accessible via the PATH variable.

The CLASSPATH that is established for EAServer can be viewed directly from the server properties of Jaguar Manager. Keep in mind, however, that EAServer also uses custom class loaders during its execution, so the absence of a required class on the system CLASSPATH doesn't necessarily mean that failure is imminent. However, the presence of a class on the system CLASSPATH can interfere with an identical class loaded by a custom class loader resulting in a Java ClassCastException or ClassNotFoundException. The remedy is to ensure that all classes required by a component are loaded via custom class loaders. You do this by including such classes in the java.classes property of the associated application, web application, servlet, package, component or even the server itself.

EAServer offers two tracing options to help diagnose class loader errors.

  • Setting the property to true causes the location from which each class is loaded to be recorded in the EAServer log file.
  • Setting to true also records the class loader used for each class.
Listing 1 is an excerpt from the EAServer log where both these properties have been set. The trace lines prefaced with JCL: result from the classloader.debug option, while the others originate with the jvm.verbose setting. This particular example shows the sequence used to instantiate the Java Connection Manager (JCM) service upon server startup.

The BOOTCLASSPATH is used with JDK 1.2 and later so the system class loader can load classes before it loads the core Java classes provided in rt.jar. This is required whenever alternative implementations of classes located in rt.jar need to be used. For instance, in EAServer 4, the EAServer ORB class is org.omg.CORBA.ORB and is located in easclient.jar. Sun's rt.jar distribution, however, also includes this class. To ensure that EAServer uses the Sybase implementation, the serverstart script puts easclient.jar on the BOOTCLASSPATH ahead of rt.jar.

Other classes that need to access classes on the BOOTCLASSPATH may also need to be added to the BOOTCLASSPATH. A common example is third-party JDBC drivers used by EAServer connection caches such as the Oracle Thin JDBC driver. If you include the driver classes (such as %ORACLE_HOME%/jdbc/lib/ in the CLASSPATH but not in the BOOTCLASSPATH, you will encounter a ClassNotFoundException due to class loader conflicts.

At a minimum, PowerBuilder 9.0 components running in EAServer require that the PBVM90 and PBJAG90 modules be available on the operating system path established for the EAServer process. Generally, most components make use of DataStores and one or more database connections; therefore, the PBDWE module and one or more database interfaces (PBJDB, PBODB, PBSYJ, PBO90 and so on) are also needed. The "Application Techniques" manual accompanying PowerBuilder provides specifics on the binary images required by platform and functionality.

The value of the Microsoft Windows PATH variable (and its Unix analogs) used by EAServer can be ascertained via the operating system commands and utilities shown in Table 2. These utilities are particularly useful in ensuring that the correct versions of the PowerBuilder libraries are loaded at runtime.

The listdlls utility has an advantage over the Unix commands because each DLL version is reported as part of the output. On Unix platforms, you need to extract the version number from each specific object file using the strings command. For instance, the following command on HP-UX reports the version of the PowerBuilder VM implemented by the file:

strings | grep -i "^Version [0-9]"

JVMType Switch
When starting EAServer or installing it as a service on a Microsoft Windows system, the -jvmtype switch can specify that the client, server or classic Java VM be used (assuming that the JDK version and operating system support is use). Historically, the Java server VM has had a reputation for being less stable than the client VM, and although it's tuned for application server performance, you may want to use the default client VM if you encounter specific stability issues. Generally, stability is more of a factor in older releases of the Java VM and is characterized by rather severe Java VM abort messages appearing in the EAServer log.

More Stories By Jim O'Neil

Jim is a Technology Evangelist for Microsoft who covers the Northeast District, namely, New England and upstate New York. He is focused on engaging with the development community in the area through user groups, code camps, BarCamps, Microsoft-sponsored events, etc., and just in general serve as ambassador for Microsoft. Since 2009, Jim has been focusing on software development scenarios using cloud computing and Windows Azure. You can follow Jim on Twitter at @jimoneil

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.