Configuring the Listener

The behavior of the Listener can be customized through the use of four configuration parameters: port_number, secondary_port, output_count, and output_interval. FileNet provides default values for each of these parameters. However, you can override the defaults by specifying new values in a configuration file called PchConfig.properties.

Configuration Parameters

In the PchConfig.properties configuration file, you can specify values for the configuration parameters using the syntax property=value. The following table describes the customizable configuration parameters and the default values assigned by FileNet System Manager:

Property
Default
Description
port_number
32775

The primary TCP port number on which the first instantiated Listener (called the primary Listener) listens for connections from Managers. When a Manager connects to the primary Listener, it will be informed about which other ports are bound to other (secondary) Listeners. (Managers will normally choose to connect to both the primary and secondary Listeners). NOTE A different port number should only be specified if another service is already using this port locally.

secondary_port
OS defined

When this parameter is defined, secondary Listeners attempt to bind to the specified port number, then that number plus 1, plus 2, etc., until they successfully bind to a port. After a secondary Listener binds to a port, it contacts the primary Listener and informs it of the port number it has chosen. Multiple Listeners on the same computer will automatically arbitrate the use of the TCP port number using the secondary_port parameter, such that there will always be one Listener listening on the primary port. NOTE By default, secondary Listeners allow the operating system to choose the port to which they should bind. However, some situations exist where this binding method could cause connectivity problems, such as the presence of firewalls. In this case, using this parameter would only necessitate the opening of a small range of ports on the firewall to achieve the Listener bindings.

output_interval

900
(15 minutes)

Specifies the aggregation interval in seconds; values of less than 100 milliseconds are ignored. The aggregation interval is the length of time over which each summary block of performance data is accumulated by the Listener. At the end of each aggregation interval, the Listener computes a summary block (basically, a snapshot of the current counter values), sends the summary to any Managers that have requested automatic updates, and then resets the min and max values associated with the Accumulators. The summary block is also added to a running history maintained by the Listener, which allows newly-connecting Managers to request information about recent application activity. For more information about the aggregation interval, see Getting Started: Configuring the Aggregation Interval in the FileNet System Manager Listener C++ API Developer's Guide or the FileNet System Manager Listener Java™ API Developer's Guide.

output_count
96

Specifies the maximum number of summary blocks that will be written to the summary log file before it is closed and a new one is opened. The default configuration provides for 24 hours worth of data to be written to a single file. Therefore, somewhere between 24 and 48 hours of performance history will be available at any given time.

Multiple Listeners on the same computer will automatically arbitrate the use of the TCP port number, via the secondary_port parameter. This ensures that there is always one Listener listening on the primary port to which Managers can connect.

When executing in an application server environment, you must ensure that the application has the appropriate privileges to listen for connections on these TCP ports. On Windows systems, the WinPerfMon.dll file must be installed in the appropriate search path in order for the Listener to obtain system performance information. On Unix systems, the application must have the privilege to exchange UDP packets with rstatd.

Location of the PchConfig.properties File

When the Listener is instantiated, the System Manager attempts to locate the PchConfig.properties configuration file and if it is found, the contents of the file are processed. When the PchConfig.properties configuration file cannot be located, FileNet assigns the default values to the configuration parameters.

Locating the File for Use with the C++ Listener

The process for locating the file on a Windows platform for use with the C++ Listener API is as follows:

  1. The System Manager first determines if the filenet.pchconfig environment variable is defined. If the variable is defined and its value is not the empty string, then the value of the variable is considered to be the complete path to the location of the configuration file.
  2. If the filenet.pchconfig environment variable is not defined, or its value is the empty string, then the System Manager searches for the configuration file in the current directory.
  3. If the configuration file is not located in the current directory, then if the HOME environment variable is defined, the configuration file is searched for in that directory.
  4. If the configuration file is not located in the directory specified by the HOME environment variable, and if the PATH environment variable is defined, then each semicolon-separated directory is searched for the file.

Locating the File for Use with the Java™ Listener

The process for locating the file on a Java-enabled platform for use with the Java Listener API is as follows:

  1. The System Manager first determines if the filenet.pchconfig Java system property is defined. If the property is defined and its value is not the empty string, then the value of the property is considered to be the complete path to the location of the configuration file.
  2. If the filenet.pchconfig property is not defined, or its value is the empty string, then the System Manager searches for the configuration file in the directories specified by the user.home, user.dir, and java.home Java system properties, in that order.
  3. If the configuration file is not located in any of those directories, then the directories specified in the CLASSPATHS variable are searched.