| CCINETB Configuration | CCINAMPU Configuration | |
CCITCP is supported on Windows 95, Windows 98, Windows NT and UNIX systems.
CCI over TCP/IP (CCITCP) allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) in two ways: directly, by specifying the TCP/IP address and port being used by the application you want to connect to (this is described in the Advanced Features section); or indirectly, by specifying a logical "Server Name" of the service you wish to connect to.
This second method allows the most flexibility: the applications can be moved from machine to machine without being altered; and the details of the machine they are running on are unimportant (as long as they support CCI and TCP/IP, of course). This flexibility is achieved by having an intermediate program which CCI can query when a connection request is made. This program contains or can obtain the necessary details to allow an application to establish a connection with another application of a given Server Name. This program is called the CCITCP2 registration daemon.
Before using CCI over TCP/IP (with or without using CCITCP2) there is some configuration that is necessary, described in the sections below.
In order to enable CCI support for TCP/IP three executable modules are provided:
Before the CCI modules can work effectively the appropriate TCP/IP network hardware and software drivers must be already installed, fully configured, and working. Once the TCP/IP software is installed and configured, the network connections should be fully checked out using suitable utilities, such as the TCP/IP standard commands "ping" and "ftp", before attempting to use CCI over TCP/IP. Ensure that if hostnames are going to be used (as opposed to only dotted decimal IP addresses) that the Domain Name Server (DNS) configuration is correct and that the service is working.
Where a network is connected to other networks, ensure that TCP/IP is aware of the gateway(s) to these networks by running "route add" or a similar command. Please see your TCP/IP vendor's installation and configuration guides for details of these steps.
Once you are certain that TCP/IP is fully configured and functional and that the machines which you wish to communicate with are similarly set up and reachable, then the only other configuration issue that needs to be resolved is where (and whether) a CCITCP2 daemon will be run to enable these machines to contact each other.
This section does not apply to UNIX installations. Please refer to CCI Configuration for UNIX users
If a CCITCP2 daemon is used to allow CCITCP clients and servers to establish contact then the "CCI Configuration" utility needs to be run first. It can be started by going to the "Configuration" group under the product Start menu item and selecting "CCI Configuration". Alternatively just run CCIINST from any Net Express or Mainframe Express Command Prompt.
The CCI Configuration Utility asks for the address of the machine in the reachable network which is running a CCITCP2 daemon. You can enter either a hostname or a dotted decimal format address. If you do not know the TCP/IP hostname or address of the system that the CCITCP2 daemon is running on, contact your system/network administrator.
The CCI Configuration Utility also updates the TCP/IP services file with values necessary for CCI to work over TCP/IP.
If you leave the hostname field empty, CCI assumes that the CCITCP2 daemon will be running on the local machine, and the changes to the services file are still made.
If the machine running the CCITCP2 daemon changes, you must rerun the CCI Installation Utility and change the hostname to the new value. If there are any MERANT processes running which were started before the value was changed (e.g. Command Prompt, Integrated Development Environment, etc.) then these will need to be re-started before they pick up the new value.
Prior to using CCITCP with CCITCP2, an entry must be made in the /etc/services file as follows:-
mfcobol 86/udp
Without this entry in the /etc/services file, CCITCP2 cannot function.
On UNIX systems the user is required to set an environment variable "CCITCP2" to select the location of the machine hosting CCITCP2 executable in the network that is being used.
An example of the setting of a CCITCP2 environment variable for korn shell users is
export CCITCP2=myhostmachinename
or
export CCITCP2=192.77.293.1
The method for setting environment variables in other UNIX shells differs slightly from the examples given here, please use the appropriate method for the user shell of your choice.
Please refer to the section Environment Variables and the CCI.INI File for more details of the advanced configuration of CCITCP.
There only needs to be one CCITCP2 process active on a network in order for CCI over TCP/IP to work, as long as all machines have been configured (using the CCI Configuration Utility) to use it. Alternatively, multiple CCITCP2 processes running in the network can coexist and can communicate between each other so that a machine configured to use one daemon can find an application registered with a different daemon in the network. For instance, it is possible for every machine on the network to be running a copy of CCITCP2 and be configured to use their own local copy to search for connections. This would, however, generate a lot more network broadcast traffic compared to having just one daemon which all machines are configured to use.
The CCI Configuration Utility needs to be run on a machine before CCITCP2 can be successfully started on it (enter a blank hostname if the daemon is run locally). Once started, the daemon will accept service registrations until the effective RAM available to the process is exhausted, or until it is shut down.
CCITCP2 can be started manually at any time (as long as it is not already running) by entering:
ccitcp2
at a Net Express or Mainframe Express command prompt, or it can be started automatically at system start-up by including it in the startup folder. Alternatively, on NT, it can be installed as a service (see CCITCP2 as an NT Service).
On UNIX systems CCITCP2 can only be started by a superuser (root).
If both the Server Name and Machine Name (see Application Configuration for a definition of these terms) are specified by the client application, the CCITCP2 process returns the machine and port address of the service specified to the client so that it can establish a connection with the named service. If the service is not found, an error is returned.
However, if the Server Name is specified but the Machine Name is not, the CCITCP2 process searches all the registered Server Names in the reachable network in the following order until either the named service is found or an error is returned:
You can avoid the potential problem of producing an undesired connection from the third level search by closely observing the rules followed at the first two search levels or by using a unique name for each server process on the network.
This section provides information that may be useful if you experience problems when using CCI over TCP/IP with CCITCP2.
"mfcobol port entry not found in services file" error
Run the CCI Configuration Utility on the machine receiving this error: this should automatically update the TCP/IP services file with the necessary entries.
"Cannot find CCITCP2" error
Run the CCI Configuration Utility on the machine receiving this error. Make sure that the hostname or TCP address value matches that of the machine running the CCITCP2 process you expect to use, and that the CCITCP2 process is running on that machine. Use "ping" and "ftp" to make sure that the machine is reachable using the address you have specified. Check that there are no CCITCP environment variables or CCI.INI file entries over-riding the value specified by the Configuration Utility. If the value has been changed recently, make sure that the failing process has been subsequently re-started.
"Registered service found but could not make a connection" error
There are two main possible causes of this message:
To check to see if this is what is happening close and re-start the CCITCP2 daemon that the client is pointed at. This will clear it of all registered Server Names, including any "orphan" servers. (If CCITCP2 is running in debug console mode then you can press F2 and it will list what CCI servers are registered with it.) Check to see that the CCI service is not abnormally terminating.
"A CCITCP call has timed out" error
This most commonly occurs if the server application that the client is attempting to contact is not running at the time the client is started. However, it can also a be produced in a network topology which includes routers or bridges which have not been configured to allow CCITCP2 daemons to communicate with each other. For example, if a client fails to connect with a registered service as follows:
The CCITCP2 modules are designed to communicate with each other using the TCP/IP broadcast address mechanism. If this is not correctly configured, CCITCP2 cannot locate services registered with other CCITCP2 modules. If this happens, you should advise your system administrator.
System administrators should be aware of the following:
For CCITCP2 modules to communicate correctly, your network must be configured to pass broadcast packets to all areas that want to use CCITCP.
On Windows NT you can run the CCITCP2 daemon as an NT service by entering:
ccitcp2 -i
at the Net Express or Mainframe Express command prompt. (You must be logged on as a user with Administrator privilege to do this.)
Once installed as an NT service, CCITCP2 can be started and stopped via the Control Panel in the usual way.
You can use the -c option to install CCITCP2 as a service and run it in debug mode so that a console shows services being registered and connections being made:
ccitcp2 -c
Note that if CCITCP has already been installed as a non-console service it will need to be uninstalled first. To uninstall CCITCP2 as a service, use the -u option:
ccitcp2 -u
The -? option lists the available CCITCP2 startup modes.
Note: If CCITCP2 is installed as an NT service, it will be started automatically when the NT system is re-started. If a non-service CCITCP2 has previously been added to the Windows Startup group, it should be removed; otherwise, Windows will try to start a second instance of CCITCP2.
If CCITCP2 is started from a command line with the -d (debug) option or installed as a service with the -c option, then pressing the F2 key will list the CCI services that are registered with the daemon. F4 toggles the echoing of the console output to the ccitcp2.log file in the current directory of the daemon.
A CCITCP2 registration daemon is not necessary if the CCI client application and the CCI server application establish a connection directly between each other. This can only be done when the server application starts up on a specific TCP port, and the client knows which address and port the server is using.
In a relatively static application enterprise environment where the server application location is well-defined and persistent, then using direct connection can have advantages over using a CCITCP2 registration process to help establish a connection.
Allowing a server application to listen on a known, fixed port means that clients can contact the server through a security firewall if a gap has been configured for that port and address.
A CCI server can support both direct connection and normal connection via a CCITCP2 daemon simultaneously. If a server starts on a fixed port, and a CCITCP2 daemon is present, then it will register a Server Name with it as normal, but in addition clients will be able to connect to it directly because the port it is using is known. If the CCITCP2 daemon is not present or reachable then a fixed port server will still start successfully, but only clients who attempt to connect directly will be able to contact it.
A variety of environment variables and CCI.INI file entries can be used to customize CCI behavior either on a machine-wide or per-process basis. Most users should not need to use either of these methods, but they are provided in case a greater degree of application control is required.
If more than one of the above methods is used for the same purpose or feature, the order of precedence that determines the behavior is:
In the following sections UNIX users should use the appropriate method of setting environment variables for the user shell which is being used. The examples given are guides using the manner of setting environment variables found on the PC.
Instead of using the CCI Configuration Utility to set the TCP address of the machine running the CCITCP2 registration daemon the environment variable "CCITCP2" can be used instead. This may be useful if you need different processes on the same machine to contact different registration daemons. The value can be set from the command prompt by typing:
set CCITCP2=hostname
where hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.
The environment variable value will always take precedence over any value set using the Configuration Utility. To restore a process to using the value set by the Configuration Utility simply set the environment variable to an empty string e.g.
set CCITCP2=
Alternatively, if this environment variable is set system-wide (by creating a system variable in the system environment settings, or by using a CONFIG.SYS file) then this value will always take precedence over any value set using the Configuration Utility.
If you want to start a CCI server on a fixed port, then you can associate the Server Name with the port value by using the CCITCPS_ environment variable (instead of appending the information on the Server Name itself, as described in the CCITCP Server Name section). If the Server Name is server_name, and you want it to use the fixed TCP port 3000, this can be specified by typing:
set CCITCPS_server_name=MFPORT:3000
Note that this will only work if the server application process is started in the same session or process that has this environment variable set.
If a client is known to be trying to connect to a server with Server Name server_name, and the TCP address (server_hostname) and port (e.g. 3000) that the server is using is known, then the client can be made to connect directly to it by setting an environment variable as follows:
CCITCPT_server_name=MFNODE:server_hostname,MFPORT:3000
Note that this can be used instead of setting the client Machine Name value (see section CCITCP Machine Name). This is useful if the Machine Name value the client specifies cannot be altered by an application defined method.
The CCI.INI file is only used by CCITCP if direct connection or a fixed port server is required. In addition, this configuration method is only recommended when the Server Name or Machine Name cannot be modified by the application that is using CCI, and the environment variable method described in the section above is also not considered suitable.
There are two possible sections in the CCI.INI file which are specifically used by CCITCP:
[ccitcp-servers]
which can have entries of the following form:
server_name=MFPORT:xxxxx
This is used exclusively to match a given Server Name server_name (see CCITCP Server Name for a description of valid values) with a fixed TCP port value xxxxxx.
The other CCI.INI section used is:
[ccitcp-targets]
which expects entries of the following form:
server_name=MFNODE:server_hostname,MFPORT:xxxxx
This is used exclusively by clients to associate a target Server Name server_name with a Machine Name value to the right of the "=" character (see CCITCP Machine Name for valid values and uses).
CCITCP Client/Server applications use the CCI Server Name and Machine Name parameters to enable the CCI Client to specify the CCI Server with which to communicate.
The CCI Server identifies itself on the network by using the Server Name parameter. The CCI Client specifies the CCI Server using the Server Name. Additionally, if it only wants to find this Server running on a particular machine in the network, it needs to specify the Machine Name parameter.
Both CCI server and CCI client applications need to have a Server Name specified: server applications need to register themselves as available under this name (or what fixed port to use); and clients need to specify which server they wish to contact.
This can be any valid alphanumeric string (up to 127 characters in length). Names beginning with a ',' character, or including the consecutive characters ",MF" are reserved for MERANT use.
If you wish to have the server start on a fixed or known TCP port (see Direct Connection and Starting Servers on Fixed Ports), then this can be achieved by appending the string ",MFPORT:xxxxx" to the Server Name, where xxxxx is the decimal value of the port. This string is not used as part of the Server Name, but is interpreted by CCI so that the server uses the specified port for listening for incoming clients. If you do not wish the server to have any name (that is, clients cannot use CCITCP2 to contact the server, but can only specify it directly by using the Machine Name parameter) then the Server Name need only consist of this string.
Note: It is recommended that you do not use port numbers below 2000 as these may already be in use by standard TCP services. The maximum port value normally supported is 65535. Care should be taken not to use a port value that is already in use by other standard applications: check with the system or network administrator on valid port value ranges that should be used.
This is a parameter that only needs to be specified by CCI client applications.
This should be the TCP address (either the hostname if DNS is enabled, or the dotted decimal address if not) of the machine you wish to restrict the client to contacting. If you know that the Server Name of the application the client is trying to contact is unique in the reachable network, or you do not care which server of this same name it connects to, then this parameter is optional.
If you do not wish to use a CCITCP2 daemon to resolve the TCP address and port that the server is using (see Using CCI over TCP/IP without CCITCP2), but want the client to contact the server directly, then the Machine Name must have the following form:
MFNODE:server_hostname,MFPORT:xxxxx
where server_hostname is the hostname or dotted decimal address which the server application is using, and xxxxxx is the decimal port value.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| CCINETB Configuration | CCINAMPU Configuration | |