Configure Enterprise Communicator (PEC)

Enterprise Communicator (referred to as PEC) is a common communication product that CA Harvest SCM uses and requires. All PEC components are installed when you install the product. However, PEC can also run stand-alone as a separate component. Other products using PEC can assume and rely on all features of PEC being present when the RTHOME environment variable is set.
The RTserver
RTserver is a publish-subscribe message router that uses connections to make large scale distributed inter-process communication (IPC) easier. RTserver routes messages between the CA Harvest SCM server and the product client.
The RTclient
An RTclient is a process that is connected to an RTserver: the CA Harvest SCM client (GUI or command line) and the product broker process. Each RTclient has one IPC connection to one RTserver. An RTclient cannot be connected to more than one RTserver at a time.
The product broker has the capability to auto-start an RTserver process if one is not already running. Other RTclients and client GUI/command line, for example, automatically connect to the RTserver running on the product broker node.
RTserver Options
RTserver allows the setting of options at startup time. These options are defined in a startup command file named rtserver.cm. This file is located in the RTHOME/standard directory. The option values that have been specified in the RTserver command file are set each time RTserver is started.
Options are set with the setopt command. The general format is
setopt
option values
  • server_names
     Specifies a list of logical connection names used to find other RTserver processes. Each logical connection name has the form protocol:node:address, which can be shortened to protocol:node, or node.
    Example option setting:
    setopt server_names CA SCM
    CA Harvest SCM specifies a node or computer name.
  • conn_names
     Specifies a list of logical connection names used by RTclient processes (CA Harvest SCM client) to find this RTserver. Each logical connection name has the form protocol:node:address, which can be shortened to protocol:node, or node.
    Example option setting:
    setopt conn_names CA SCM
    CA Harvest SCM specifies a node or computer name.
Logical Connection Names
A logical connection name has the form protocol:node:address. A server uses a logical connection name to create a server connection, and a client process uses the same logical connection name to create a client connection to the server process. For the client process to find the server process, the logical connection name used by the client must 
exactly 
match the logical connection name used by the server (for example, the name tcp:sparc:1234 does not match the name tcp:risc:1234).
Protocol
The protocol part of the connection name refers to an IPC protocol type. The valid values for protocol are:
UNIX: local, tcp. Windows: tcp.
Node
The 
node
 part of the connection name refers to a computer node name or IP address. The special value _node can be used for node to indicate the name of the current node. This is the default if not specified.
Address
The address part of the connection name refers to a protocol-specific IPC location, such as a TCP port number.
Name-to-IP Address Resolution Requirements
Direct connection from client to server, client to a remote agent, a remote agent to a server, and server to remote agent is based on the following requirements:              
Connection Type
Example
Requirement
Client to server
Check out to a local file system
Client host must be able to resolve the server's node name to an IP address.
Client to remote agent
Log in to a remote agent
Client host must be able to resolve the remote agent's node name to an IP address.
Remote agent to server
Check out to a remote agent
Remote agent host must be able to resolve the server's node name to an IP address.
Server to remote agent
Check in, Check out
Server must be able to resolve the agent host's name to an IP address.
Note:
 By default, CA Harvest SCM uses the computer's host name as the node name.
The RT_FORCE_NODE_NAME Environment Variable
Enterprise Communicator uses the computer node name returned by the hostname command (Windows) or uname command (UNIX). In some cases, it is necessary to override the default node name using an alias or virtual machine name.
The environment variable, RT_FORCE_NODE_NAME, forces Enterprise Communicator to use the specified node name. This variable is set in the user environment responsible for the startup of the RTserver and CA Harvest SCM broker. The product broker and product client use the assigned node name defined by the RT_FORCE_NODE_NAME variable.
  • On Windows platforms, define the system variable, RT_FORCE_NODE_NAME, and assign it a node name. The value or node name assigned overrides the default node name used by Enterprise Communicator.
  • On UNIX platforms, define an environment variable, $RT_FORCE_NODE_NAME, in the user shell. Set the value of this variable to override the default node name used by Enterprise Communicator.
You must restart RTserver, the product broker and the product clients for the change to take effect.
The Fully Qualified Domain Name as Node Name
CA Harvest SCM requires Name to IP Address resolution when establishing a connection from HClient to HServer, HClient to HAgent, and HAgent to HServer. By default, the product uses hostname (shortname, nodename) resolution when creating these connections.
In an environment where hostname resolution is not supported across the entire network and Fully Qualified Domain Name (FQDN) is the only name resolution infrastructure provided, it is necessary to enable the use of FQDN in the product components that require it.
On every computer running a remote agent or server (only required on computers running remote agent or server), define RT_FORCE_NODE_NAME as an environment variable and set its value to the FQDN of the computer.
For example, if the computer's FQDN is m1.company.com:
Windows
 
In Control Panel, System, Environment Variables, add, as a SYSTEM VARIABLE, the variable RT_FORCE_NODE_NAME with a value of m1.company.com.
UNIX
 
Add RT_FORCE_NODE_NAME=m1.company.com; export RT_FORCE_NODE_NAME to the USER PROFILE for every product user on the computer or the SYSTEM PROFILE.
Important! 
When RT_FORCE_NODE_NAME is defined on a remote agent computer, its value must be used as the agent's computer name for all product utilities that connect to the agent.
For example, if RT_FORCE_NODE_NAME is defined with the value of m1.company.com:
  • Using the Workbench, log in to the agent using m1.company.com as the agent computer name.
  • Using the hco command, check out a file to the remote agent using m1.company.com as the agent computer name.
    hco ... -rm m1.company.com ...
Important! 
When RT_FORCE_NODE_NAME is defined on a broker computer, its value must be used as the broker name for all product utilities that connect to the broker.For example, if RT_FORCE_NODE_NAME is defined with the value of m1.company.com:
  • Using the Workbench, log in to the broker using m1.company.com as the broker name.
  • Using the hco command, check out a file using m1.company.com as the broker name.
    hco -b m1.company.com ...
The RTserver Port Number
The default RTserver communication port number is 5101. This port number can be set to any accessible port in your network. For example, if the default port of 5101 is not in the range of available ports across a firewall, you will need to specify another RTserver port number.
Note:
 Before changing the port number, you must stop the CA Harvest SCM broker, product clients, product agents, and the RTserver.
RTserver Setup
The RTserver startup command file must specify the Conn_Names option with the logical connection names value. The Conn_Names option specifies a list of logical connection names used by RTclient (the CA Harvest SCM client) to find this RTserver. Each logical connection name has the form protocol:node:address.
Note:
 The RTserver startup command file, rtserver.cm, is found in the RTHOME/standard directory.
Port number 5101 (default) represents the address portion of protocol:node:address. To specify a different port, define the Conn_Names option in the rtserver.cm file.
Example rtserver.cm file:
/* ---------------------------------- */ /* RTserver-specific options */ /* ---------------------------------- */ setopt prompt                         "SERVER> " setopt time_format           hms setopt client_connect_timeout   10.0 setopt client_max_buffer     10000000 /* ~10 MB */ setopt log_in_client         UNKNOWN setopt log_in_server               UNKNOWN setopt log_out_client              UNKNOWN setopt log_out_server              UNKNOWN setopt udp_broadcast_timeout       5.0 setopt Enable_Control_Msgs     connect, disconnectsetopt Conn_Names tcp:ca scm:5202
In this example, CA Harvest SCM specifies the computer node name.
You must restart the RTserver for the changes to take effect.
Specify the Network Port Number
The CA Harvest SCM client, broker, and server must specify the network port number using the -rtserver option in the following argument files: hbroker.arg, HServer.arg, and HClient.arg. The argument files are located in the CA_SCM_HOME directory.
Note:
 The argument file, HClient.arg, is not created by the installation and must be created manually in the CA_SCM_HOME directory. Other than specifying nondefault port numbers, and the option -cm[ 
i,a
] to specify the connect method for the connection between the client and the server, the HClient.arg file is not necessary.
 
Follow these steps:
  1. Add the -rtserver option to the hbroker.arg, HServer.arg, and HClient.arg files using the following syntax:
    -rtserver=tcp:node:address
    For example:
    -rtserver=tcp:scm:5202
    The network port number is specified.
  2. Restart the RTserver, in addition to the product's broker and clients. The changes take effect.
The Server Port Range
The CA Harvest SCM server uses operating system TCP/IP ports in addition to the RTserver TCP/IP communication port for the following functions: check-in, check-out, form file attachments, load repository and browsing the file system using a product remote agent.
The additional TCP/IP ports are assigned by the operating system dynamically (ephemeral ports) unless otherwise specified during the product server installation, or specified during post-installation using the instructions while specifying the CA Harvest SCM communication port number.
Configuring the TCP/IP port range to be used by the product is done completely on the product server installation. No product client configuration is necessary.
The product server port range is explicitly set in the RTserver startup command file, rtserver.cm for Windows-based product server installations and $RTHOME/standard/rtserver.cm for UNIX/Linux-based product server installations.
If the port range is not explicitly set in the rtserver.cm file, the product server uses operating system assigned ports (ephemeral ports) for the product functions mentioned in the previous section.
Define the Port Range
If you did not specify a TCP/IP port range during the CA Harvest SCM server installation, you can do this post-installation by performing the following procedure.
Important! 
The port range specified must be greater than or equal to the number of product server processes and remote agent processes running behind the firewall. If the port range is less than what is specified in the preceding paragraph, the check-in, check-out, load repository, form file attachment, and remote agent access may not function properly.
Follow these steps:
  1. Open the following files for editing:
    • For Windows: %RTHOME%\standard\rtserver.cm
    • For UNIX/Linux: $RTHOME/standard/rtserver.cm
  2. Define the option, setopt direct_connect_port_range, in the rtserver.cm file. For example, if the port range to specify is 9000 to 9100 inclusive:
    setopt direct_connect_port_range 9000,9100
  3. Save and close the rtserver.cm file.
Note:
 You must restart RTserver, the product broker, and product clients for the changes to take effect.
Modify the Port Range
If you specified a TCP/IP port range during the CA Harvest SCM server installation and need to modify this port range post-installation, you can modify an existing port range by following the instructions in this procedure.
Important!
 The port range specified must be greater than or equal to the number of product server processes and remote agent processes running behind the firewall. If the port range is less than what is specified in the preceding paragraph, the check-in, check-out, load repository, form file attachment, and remote agent access may not function properly.
Follow these steps:
  1. Open the following files for editing:
    • For Windows: %RTHOME%\standard\rtserver.cm
    • For UNIX/Linux: $RTHOME/standard/rtserver.cm
  2. Locate the port range option, setopt direct_connect_port_range. Edit the range as necessary. For example, if the current range is 9000 to 9050 and you want to increase it to 9100, edit as follows:
    setopt direct_connect_port_range 9000,9050
    change to: setopt direct_connect_port_range 9000,9100
  3. Save and close the rtserver.cm file.
  4. (UNIX/Linux systems) Source the PEC environment script located in $RTHOME/bin/rtinit.sh(csh): . ./rtinit.sh
     
    (Bourne/Korn/Bash shells) source rtinit.csh (C shell)
  5. Stop the RTserver process by executing the following command:
    rtserver -stop
After the RTserver process has been stopped, the product broker automatically restarts the RTserver process. Stopping the RTserver will not interrupt product client operations.
Time-out Parameters
The time-out parameters affect the running of multiple concurrent CA Harvest SCM operations related to the product agent process. An example is a group of users that simultaneously check out files from the product to remote computers that run the product agent processes. The time-out parameters are:
  • _
    conn
    _init_timeout
  • ptm_client_accept_timeout
  • ptm_server_accept_timeout
Due to system resource constraints and concurrency usage conflicts, sometimes a user may encounter a time-out error message. However, a user can change parameters to achieve better concurrency usage and avoid this time-out error.
The Connection Time-out Values
The default value for the RTserver connection time-out is five seconds. However, this value may be too short to accommodate all connection needs if a very large number of messages is sent to the RTserver simultaneously. Users can extend this time-out period by altering the PEC setting parameter _CONN_INIT_TIMEOUT in RTHOME/standard/rtclient.cm file on the computer that runs the product client process. See the following example for the increase of this time-out setting:
/* increase to 30 seconds */ setopt _conn_init_timeout 30.0
 Increasing this time-out value may introduce side effects. For example, an invalid hostname specified to log in to a product agent computer can introduce the login time-out due to the message delivery failure. Users will wait much longer to receive the message regarding the connection failure. Therefore, users need to specify the time period based on the concurrency requirement.
If you receive an error on the standard output of the product command line client process similar to the following, you need to increase this time-out value:
WARNING: Attempted to read from connection client:local:<broker>:RTSERVER.First read size is 8. The number of bytes read returned by TipcLinkRecvTimeout is -1. WARNING: Last RTworks Error Code: 9 timeout reached Last C Error Code: 2 No such file or directory
When the product performs the bulk data transfer (for example, check out a file), it uses peer-to-peer connection between client, server, and agent. Sometimes users may encounter a time-out error for establishing this peer-to-peer connection during a check-out in a high concurrency usage scenario. In the PEC install directory, RTHOME/standard/rtclient.cm file, the time-out parameters, ptm_client_accept_timeout and ptm_server_accept_timeout, can be changed to avoid time-out errors. The default value is 60 seconds for both. See the following examples to change the default values for these options.
Examples:
If you receive an agent login time-out error, “The login operation timed out,” specify the time-out value for ptm_client_accept_timeout in the RTHOME/standard/rtclient.cm file on the product client host computer:
/* increase to 120 seconds */setopt ptm_client_accept_timeout 120.0
If you receive a network time-out error, “Network timeout,” specify the time-out value for ptm_server_accept_timeout in the RTHOME/standard/rtclient.cm file on the product server host computer:
/* increase to 120 seconds */ptm_server_accept_timeout 120.0
Restart the product server after setting ptm_server_accept_timeout.