Appendix: Troubleshooting Change Assistant and EMF

This appendix covers topics related to troubleshooting the configuration and operation of Change Assistant and the Environment Management Framework.

Peer Cannot Connect to the Hub

When an Environment Management peer (typically an agent or the viewer) can't communicate with the hub, the following error messages appear in the logs and stdout:

Broken connection - attempting to reconnect
RemoteException while connecting to server - retrying attempt 1
RemoteException while connecting to server - retrying attempt 2
RemoteException while connecting to server - retrying attempt 3

The peer periodically attempts to reconnect to the hub (by default every ten seconds) with the parameters that are specified in the configuration.properties file.

Determining the Error Condition

The peer may not be able to communicate with the hub for one of the following reasons:

• The peer is started but the hub is not started.

  The peer reconnects once the hub is started.

• The peer is started but the web server is configured to run on a different machine.

  Edit the configuration.properties file and change the hubURL parameter.

• The peer is started but the web server is configured to listen on a different port.

  Users continue to see the error messages described previously. Edit the configuration.properties file and change the port number for the hubURL parameter. Shut down and restart the peer.

• The peer is running and communicating with the hub, and the PIA web server is shut down.

  Users see the broken connection error message. Once the PIA web server is started, the connection is restored.

When the peer has a pinginterval configuration parameter set to a high value (60 seconds or more), the following exception might appear in the log:

INFO Thread-48 org.apache.commons.httpclient.HttpMethodBase - Recoverable
 exception caught when processing request WARN Thread-48 org.apache.commons.httpclient.HttpMethodBase
- Recoverable exception caught but MethodRetryHandler.retryMethod() returned
false, rethrowing exception Broken connection - attempting to reconnect
Sending pulse from 'com.peoplesoft.emf.peer:id=5' 

This is due to an HTTP client connection timeout which does not affect functionality.

Ensuring the Correct Configuration

To ensure that you've configured the peer (agent or viewer) to properly connect with the hub, try each of the following actions in turn:

• Ping the hub host machine.

  At a command prompt, enter ping machinename, using the machine name configured in the hubURL setting. You should see messages indicating a reply from the machine.

• Ping the hub host domain.

  At a command prompt, enter ping hostdomain, using the fully qualified domain name as it's configured in the hubURL setting; for example, mymachine.mydomain.com. You should see messages indicating a reply from the machine.

• Use an IP address in the hubURL.

  In configuration.properties, replace the domain name in the hubURL setting with the machine's IP address, then restart the peer.

• Ensure that you specify the right port number in the hubURL.

  In configuration.properties, the port number in the hubURL setting must be <PIA port> if you set up PIA for a single server. In single server configurations, the hub uses the same port to which PIA is configured.

  In multi-server configurations, the hub uses the application default port, which is 8001. If you need to change this setting, it must be done in the web server configuration files.

Agent-Specific Resolutions

If an agent is still experiencing connection difficulties, delete the following agent directories if they exist:

• PS_HOME\PSEMAgent\envmetadata\data\ids

• PS_HOME\PSEMAgent\envmetadata\PersistentStorage

• PS_HOME\PSEMAgent\envmetadata\transactions

Note. You must also delete these directories after you install an additional hub on the same machine which doesn't replace the existing hub, then shut down the old hub and start the new hub using the same settings.

Viewer-Specific Resolutions

If the viewer Java application can't connect to the hub, first ensure that you specify the right port number when launching the viewer program.

If you set up PIA for a single server, 80 is the default port number, if you set up PIA for multiple servers, 8081 is the default listening port number for PSEMHUB.

If the viewer is still experiencing connection difficulties, delete the following viewer directories if they exist:

• PS_HOME\PSEMViewer\envmetadata\data\ids

• PS_HOME\PSEMViewer\envmetadata\PersistentStorage

• PS_HOME\PSEMViewer\envmetadata\transactions

Note. You must also delete these directories after you install an additional hub on the same machine which doesn't replace the existing hub, then shut down the old hub and start the new hub using the same settings.

Servlet Request Processor Exception

When running WebSphere on multiple servers the following error can occur in the stdout log of the server running PSEMHUB:

[10/21/03 20:32:44:826 PDT]  136aa03 OSEListenerDi E PLGN0021E:
Servlet Request Processor Exception:
Virtual Host/WebGroup Not Found : The host pt-lnx03.peoplesoft.com
on port 6080 has not been defined

Use the following steps to correct the error: . (the host now can accept redirected queries from your reverse proxy. Normally this configuration is applied during PIA install).

1. Open your WebSphere administration console.

2. Select Environment, Virtual Hosts, default_host, Host Aliases.

3. Add *.* so the host now can accept redirected queries from the reverse proxy.

   Normally this configuration is applied during PIA install.

Error Initializing Agent

When starting agents, if you receive the following error message, determine whether an agent is already running:

Error initializing agent. Verify if another agent is not
running on this machine or if you have the required permission to run the
agent.

If the console for the agent is not visible, check the task manager for the list of Java processes that are currently running. Stop a running agent by invoking the scripts to stop the agents and then restart the desired agent.

Determine whether the agent port is available. If not, choose a different port to start the agent.

Distributed Object Manager Errors

When running process, such as Application Engine, through the Process Scheduler (by way of Change Assistant) the following error can occur if you do not have security set appropriately for the PROCESSREQUEST.

Connecting to App Server: 10.138.124.216:9000
Error, exception caught: Distributed Object Manager: Page=Create Language=%2 (1,4)

See Ensuring Process Scheduler Security Authentication.

Cloned Databases Not Being Unique

When copying databases, it is extremely important to delete the GUID value in the new (copied) database. If not deleted, the hub will assume that the two environments are the same, leading to confusing environment records.

To resolve this, set the value of the GUID field in the PSOPTIONS table to <space> in the new database. You can insert the blank value in the PSOPTIONS table using the SQL tool at your site. The next time an application server connects to the database, the system generates a new, unique GUID.

Large SQL Scripts Fail on Microsoft SQL Server

In some situations, depending on various factors, such as memory available on the Change Assistant workstation, large SQL scripts can fail when run against Microsoft SQL Server. For example, this can occur when running the Microsoft conversion script during an upgrade.

To resolve this issue:

• Set the step executing the SQL script to run manually.

• Split the script into at least three separate scripts and run them individually.

Process Scheduler Logs Retrieved Using FTP Losing Formatting

When reviewing Process Scheduler files retrieved by way of FTP, in some cases formatting is lost.

This is typically an issue with the ANSI setting on the FTP server. For example, on a vsftpd server, in the vsftpd.conf file, make sure ascii_download_enable is set to YES. If not, stop the FTP daemon, modify the setting, and restart the FTP daemon. (Adjust this information as needed for your FTP server).

Errors Found in Log Files

Change Assistant scans log files that are generated when various processes run, such as SQL, Data Mover, SQR, CopyDatabase and so on. The following table describes what logs are produced and what Change Assistant determines to be an error: