Appendix B      Troubleshooting

This appendix provides information on how to troubleshoot problems encountered installing and using Secure Trading Agent.

Control Panel

---

Use the Secure Trading Agent Control Panel utility to verify and configure your system settings. You can use this utility to configure proxy servers, resolve port conflicts, and other configuration issues that may affect your Secure Trading Agent system.

For information on running the Control Panel, refer to "Configuring Secure Trading Agent".

---

Caution

The Secure Trading Agent Control Panel utility is the only tool you should use to manage the configuration of Secure Trading Agent. This is because Secure Trading Agent contains several internal processes that must be correctly managed to ensure that they interoperate as designed. Using other management tools, such as the Windows Services Control Panel, may cause the internal process to behave unexpectedly or fail.

---

Communications Center Tools

---

The Tools page from the Secure Trading Agent Communications Center provides utilities you can use to monitor the message handler, view application events for the current session, and view message events for specified messages. For information on using the tools available with the Communications Center, refer to Chapter 4, "Secure Trading Agent Tools and Utilities".

Log Files

---

Secure Trading Agent provides logs for various components of your Secure Trading Agent installation. You can view these logs to research problems you may be experiencing with Secure Trading Agent. Log files are available for the following components:

• HSQL Database Service
• Configuration Server
• Message Handler
• Sun Management Center
• Installation

In the following descriptions of the Secure Trading Agent log files, InstallationDirectory refers to the location you installed Secure Trading Agent. The default installation locations are:

/opt/SUNWebXML/S1ISSTA (Solaris platforms)
C:\Sun\S1ISSTA (Windows platforms)

When the path to a log file is the same on both platforms, this manual uses the Solaris path conventions.

HSQL Database Service

Secure Trading Agent uses the HSQL database service to store messaging information. If you find that your installation cannot connect to the database, check the HSQL log at:

<InstallationDirectory>/log

Configuration Server

Secure Trading Agent uses the configuration server to manage login and password security for database connections. If you have problems logging in to your installation, check the log file for the configuration server at:

<InstallationDirectory>/config/logs/catalina.out

Message Handler

Secure Trading Agent uses the message handler to send and receive messages between you and your trading partners. To troubleshoot problems with the message handler, check the log file at:

<InstallationDirectory>/tomcat/logs/catalina.out

Sun Management Center

Secure Trading Agent uses the Sun Management Center server to host the Communications Center application. Problems with the Sun Management Server can include logging into the Sun Management Center, lack of response, cannot connect to the web server, or empty pages served. The log file for the Sun Management Center is at:

/var/sadm/webconsole/logs/ (Solaris)
<InstallationDirectory>\smc\webconsole\logs (Windows)

Installation

The Secure Trading Agent installer creates a log file for both the installation process and uninstall process. The log files have unique extensions to avoid overwriting previous log files. The Secure Trading Agent installation logs are at:

/var/sadm/install/logs/ (Solaris)
C:\Documents and Settings\<UserId>\LocalSettings\Temp (Windows)

Processes

---

At times you may need to verify the status of Secure Trading Agent processes. Under normal conditions, Secure Trading Agent runs the following four processes:

• Sun Management Center service
• Secure Trading Agent messaging service
• Secure Trading Agent configuration service
• Secure Trading Agent HSQL database service

To check for Secure Trading Agent processes on Solaris platforms

1. Issue the ps command and grep for SUNWebXML.

For example:

/usr/bin/ps -ef | grep SUNWebXML

This example should list the following services:

• configsvc
• ebmessagingsvc
• ebmshdbsvc

To check for the Sun Management Center process on Solaris platforms

1. Issue the ps command and grep for java.

For example:

/usr/bin/ps -ef | grep java
/usr/j2se/bin/java -classpath /opt/SUNWtcatu/usr/apache/tomcat/bin/bootstrap.java

To check for processes on Windows platforms

1. Open the Windows Task Manager and check for the following four processes:

• configsvc.exe
• ebmessagingsvc.exe
• ebmshdbsvc.exe
• smcwebserversvc.exe

Each of these process should have a corresponding java process listed in the Task Manager.

ebScript Utility

---

Use the ebScript utility to help isolate problems with the Sun Management Center or the Secure Trading Agent Communications Center web application. ebScript runs independent of the Sun Management Center and also makes its own calls to the messaging handler.

If an activity that you are attempting fails in the Communications Center (for example, sending a message fails) see if the same activity succeeds using ebScript.

Rebuilding the Secure Trading Agent Database

---

You may want to rebuild the Secure Trading Agent database (HSQL) in the rare event that it becomes corrupt. Rebuilding the database should be done from a terminal window on both Solaris and Windows platforms.

---

Caution

Rebuilding the database is an extreme recovery method. When you rebuild the database, all ebXML agreements and messages in your system are deleted and can no longer be recovered.

---

The following procedure shows how to rebuild the database. In the procedure, InstallationDirectory refers to the location you installed Secure Trading Agent. The default installation locations are:

/opt/SUNWebXML/S1ISSTA (Solaris platforms)
C:\Sun\S1ISSTA (Windows platforms)

To rebuild the Secure Trading Agent database

1. Stop the message service handler with the following command:

ebmsh stop

ebmsh is located in <InstallationDirectory>/bin

2. Delete all files from the database directory in the following location:

<InstallationDirectory>/jdbc/repos/hsql/




---

Caution

This removes all agreements and messages in the database.

---




3. Run the following command:

ebmsh rebuild-db

4. Restart the Sun Management Center with the following command:

Solaris platforms:

/usr/sadm/bin/smcwebserver restart

Windows platforms:

From the Start > Programs > Sun Microsystems menu, select:
Secure Trading Agent > Services > Stop Web Server

From the Start > Programs > Sun Microsystems menu, select:
Secure Trading Agent > Services > Start Web Server

5. Start the message service handler with the following command:

ebmsh start

Configuring Oracle as a Database

---

This section lists common problems encountered when using the Secure Trading Agent Control Panel (ebctl) to configure Oracle as the Secure Trading Agent database. The instructions for configuring a database are described in "Specifying a Database Service".

If the Oracle configuration fails, you must correct the error before proceeding. Typically, you correct errors in the specification of the Oracle user name, password, or database URL. ebctl displays the following messages when the Oracle configuration fails:

...

DatabaseService: Creating database tables...

<some oracle error>

ERROR: sqlsession: cannot get a database connection

The following sections provides examples of typical configuration errors.

Bad JDBC Driver Class

If you specify a bad JDBC Driver Class, ebctl writes the following messages to the display:

...

Done -- now installing rest of system.

ERROR: JDBC driver 'bogus' is not available (java.lang.ClassNotFoundException: bogus).

You should always accept the default JDBC driver class name provided by ebctl. Never specify an alternate JDBC driver class name unless instructed specifically to do so by field support. The default JDBC driver class name is:

oracle.jdbc.driver.OracleDriver

Bad JDBC Driver Descriptor in the Oracle URL

If you specify a bad JDBC driver descriptor in the Oracle URL, ebctl writes the following messages to the display:

...

DatabaseService: Creating database tables...

ERROR: cannot get a database connection: java.sql.SQLException: Invalid Oracle URL specified

ERROR: sqlsession: cannot get a database connection

Correct this error by specifying the correct JDBC driver descriptor in the Oracle URL. The correct JDBC driver descriptor is:

jdbc:oracle:thin:

Bad User Name or Password

If you specify a correct URL with a bad user name or password for Oracle, ebctl writes the following messages to the display:

...

DatabaseService: Creating database tables...

ERROR: cannot get a database connection: java.sql.SQLException: ORA-01017: invalid username/password; logon denied

ERROR: sqlsession: cannot get a database connection

Correct this error by specifying the correct Oracle user name and/or password.

Bad SID in the Oracle URL

If you specify a bad SID in the Oracle URL ebctl writes the following messages to the display:

...

DatabaseService: Creating database tables...

ERROR: cannot get a database connection: java.sql.SQLException: Io exception: Connection

refused(DESCRIPTION=(TMP=)(VSNNUM=153092352)(ERR=12505)(ERROR_STACK=(ERROR=(CODE=12505)(EMFI=4))))

ERROR: sqlsession: cannot get a database connection

Correct this error by specifying the correct Oracle SID in the Oracle URL.

Sun Management Center Packages

---

When the Secure Trading Agent installer installs the Sun Management Center on Solaris platforms, it installs the packages listed in Table B-1.

Table B-1    Sun Management Center Packages

SUNWbzip	SUNWjato
SUNWmdoc	SUNWj3rt
SUNWmdemo	SUNWj3man
SUNWmctag	SUNWj3dmo
SUNWmconr	SUNWj3dev
SUNWmcon	SUNWtcatu

If you run into problems installing or uninstalling Secure Trading Agent or the Sun Management Center on Solaris, you may want to check to see if these packages are properly installed or removed.