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

Considerations When Running as a Service
When running EAServer as a service on Microsoft Windows operating systems, the key environment settings are drawn from the registry hive at \HKEY_LOCAL_MACHINE SYSTEMCurrentControlSetServicesservice-nameParameters, where service-name is the name of the EAServer instance provided on the serverstart -install command line.

The settings for PATH, CLASSPATH and BOOTCLASSPATH are stored in the registry when the service is installed. When the service is actually started, the current values of these environment variables are appended to the values that were stored in the registry when the service was created. Because the EAServer process itself sets these environment variables, a minimal environment that includes the %JAGUAR%/dll directory in the system PATH must exist for the service to start.

Also note that when installing the service, the CLASSPATH is extended to include each JAR or ZIP file located in the %JAGUAR%/java/lib directory. If you start the server as a service, only the JARs and ZIPs present in that directory when the service was installed are added to the CLASSPATH. In contrast, when starting the server via the serverstart batch file, the JARs and ZIPs present in that directory at the moment the server is started are dynamically added to the CLASSPATH.

Connecting to EAServer
Some of the most common and easiest issues to overcome involve connectivity from a PowerBuilder application or another client to EAServer. Connectivity issues may occur because of configuration issues in the client environment, failures on the server side or even issues involving firewalls and network address translation.

Diagnosing Failed Connections
The Connection object is the usual mechanism for establishing a client connection to EAServer from PowerBuilder. When the connection to server fails, the ConnectToServer method returns one of the error codes shown in Table 3. That information, along with the contents of the ErrText property of the Connection object, often reveals the root cause of the failure.

The error code 57 can pop up in a number of scenarios such as a reference to a nonexistent server, an incorrect communications protocol or an invalid user ID or password. By default, a client attempts to connect five times with a delay of two seconds between tries; therefore, an error 57 immediately returned to the client generally indicates that it found the server but that there was a problem validating the user's credentials. If the failure results from a timeout, it's usually because the location property doesn't specify a valid operating EAServer. In both cases, an investigation of the EAServer log via Jaguar Manager or a text editor is in order.

By default, EAServer doesn't validate any user except for the special administrative user, jagadmin. You need to use operating system authentication (an EAServer server property configurable via Jaguar Manager) or an EAServer custom authentication service to verify user credentials. When using one of these techniques, multiple failed requests will lock you out of the server because it has interpreted those requests as a possible attack. Note: The excerpt from the EAServer log (see Listing 2) where the IP address of the client attempting access is recorded can be useful in identifying the failed client or the source of an attempted break-in.

Obviously, if the client fails to connect with the server, the EAServer log won't contain any error information, so the absence of information itself can be a clue to the cause. As a first step in diagnosing such cases, ensure that the location property of the Connection object has the following format:


Here, the protocol is either iiop or iiops. Next, match this value to an entry at the beginning of the server log similar to this:

Dec 23 21:22:08 2002: Listener # 6: Jaguar_iiop: Active: yes Protocol:
'IIOP': 'phoenix',9000 Security Profile: '*NONE*'

If the Active attribute is set to no, the listener is not operational, as the following EAServer log entry demonstrates:

Dec 23 21:33:19 2002: SRVLIB Message: 16240/10/0: Net-Library routine
?net_listen(phoenix 9000) failed in srv__start_listeners Network error:
status = 23 - Net-Lib protocol driver call to register a listener failed

The most common causes for this behavior are that another server instance is already running or that some other application has already claimed use of that port. To verify, use the netstat command to determine what ports are in use. Listing 3 shows some output of the netstat command executed on a Solaris machine. Here the presence of ports 8080 and 9000 (both default EAServer ports) in a LISTEN state likely means that an EAServer instance is already running on that machine.

Tracing Client Connectivity Requests
In some cases, the EAServer log file alone might provide little insight into why you failed to connect to the server. In these situations, you might have to resort to tracing the underlying network protocol traffic. Using EAServer or Sybase and even third-party tools there are ways to capture packets to and from EAServer in any of the three supported communication protocols: IIOP, HTTP, and TDS.

IIOP Requests
To turn on IIOP tracing from a PowerBuilder client, populate the options property of the Connection object with the ORBLogIIOP and ORBLogFile parameters, as demonstrated next. For the ORBLogFile attribute, make sure that a full path is given and enclosed in quotation marks:

ln_connect.options = "ORBLogIIOP='true',ORBLogFile='c:orb.log'"

Listings 4 and 5 contain excerpts of an IIOP client trace indicating a failed session initialization. The IIOP putMessage in Listing 4 shows the request to create a session for user jagadmin using the password badpwd. The response (see Listing 5) is in the form of an IIOP getMessage packet that contains a NO_PERMISSION exception because the wrong password was given.

Detailed analysis of IIOP packets is really beyond our scope here; however, the chapter entitled "General Inter-ORB Protocol" in The Common Object Request Broker: Architecture and Specification (available from can be used to help interpret these traces.

You can also enable IIOP tracing on EAServer itself by setting the server property to true. Many internal workings of EAServer are handled via inter-component calls using IIOP - not to mention the fact that a server may be handling many clients - so IIOP logging causes the EAServer log to grow quickly. You can reduce the size of the log somewhat by setting the property to true, which defers the tracing until the server actually begins accepting requests from clients.

HTTP Requests
When using PowerBuilder client applications, the primary mode of communicating with EAServer is via IIOP. PowerBuilder's GetURL and PostURL functions, however, offer a mechanism to access EAServer servlets and JSPs via the HTTP protocol (HTTPS is not supported here). In such a scenario, PowerBuilder accesses EAServer as a web server, so you can diagnose connectivity issues as you would when trying to access any web site from a browser client such as Internet Explorer. The error and return codes are those defined by the World Wide Web Consortium (W3C) in the HTTP specification available from

Three log files associated with EAServer running as a web server can aid in diagnosing problems with HTTP client requests.

1.  The HTTPRequest log provides a one-line summary of every URL accessed, the IP address of the requesting client, the HTTP return code and the number of bytes of data returned. This log also contains entries for failed requests such as the ubiquitous 404 Page Not Found.

The default format for this file is the Common Log Format as defined by the W3C. Extended log file format (as shown in Listing 6) can also be enabled by setting the http.elffenable server property to true in Jaguar Manager.

The additional property lets you specify exactly which items are included in the extended log file format and in what order they appear. The options include those in Table 4 where the default value for this property is hostaddr,date,time,reqline,status,length, cookie,referer.

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.