Generally speaking, client applications require much less attention as to configuration details and settings than do server applications. In most cases the default settings will be fine for both clients and servers and that is more often true for the client-side than the server-side. We will cover some configuration aspects of both clients and servers in what follows below.
Of paramount importance to any running client is address resolution. And primarily this means that a client must be able to find the TINE Equipment Name Server, ENS (unless you're running in stand-alone mode or are running in an ENS-less situation). There are several ways of doing this and your control system administrators have most likely ensured that this happens automatically.
ENS Resolution
The addesses of any available Equipment Name Servers can be provided in a single .csv file called cshosts.csv located in a directory given by the environment variable TINE_HOME. If there is no setting for the variable, then the current working directory is used.
The addresses (IP addresses) of any available ENSes can also be provided by providing the IP address information to the current domain name server (DNS) for the entries tineens1, tineens2, tineens3, an so on (up to 5 entities). The address returned for tineens1 will be taken as the primary.
The address of the primary ENS can also be set via the environment variable TINE_ENS.
The address of the primary ENS can also be set explicitly (in the client application) by the API call SetNameServerAddress (C) or setENSAddress (java).
Finally, if all else fails and the network topology supports multicasts, a client will send a form of where-are-you multicast to establish the address of the primary ENS.
The precendence order of the above strategies is 1) explicitly setting the address via API, 2) the current setting of the environment variable TINE_ENS, 3) the addresses given in a cshosts.csv file, 4) the address returned by a query to the DNS, and 5) a response from a where-are-you multicast.
The solution making use of the entries tineens1 and tineens2 in the DNS is a common method for providing this information at a TINE site. The solution providing a cshosts.csv in a known location given by the environment variable TINE_HOME is likewise a common solution.
Performance Settings
Most data transfer issues, transactions, information monitoring, etc. should work just fine with the standard default settings. When the transfer under consideration involves very large data sets and/or very rapid monitoring then it might behoove you to consider applying some seldom used settings, which although they might require more resources, could dramatically improve the overall client-server response.
These include the following:
ENS Resolution
The comments above in the section on Client Side Configuration concerning ENS resolution apply to the server as well. TINE is a plug-and-play system whereby a server will register itself with the (primary) ENS of the local TINE system. So the address of the ENS is just as important to a server as to a client.
Server Names
It might be a good time to refresh your memory about names in the What's in a Name section in the Overview.
Suffice it to say, that care should be given to the choice of those names which the customer (i.e. control system clients, control system browsers) sees. These will be the Context of the device server registering itself in the system and the Server Name of the server, along with any Device Names and Property Names the server might register.
As noted before, the combination of Context and Server Name must be unique with a TINE system. A client asking for information (any information) from e.g. the address /PETRA/ARCHIVER must acquire the same and one-and-only address which any other client in the system would get.
But there are some other names (and parameters) to worry about as well!
A device Server belongs to and is managed by a FEC (Front End Controller) process. In many, many cases a FEC contains only a single server, but not only is this not always the case, but the number of exceptions to the rule are hardly rare.
And a FEC also has a name and a port offset.
At the end of the day, the FEC Name will point to specific process with a specific port address at a specific IP address. And therefor, this name (this FEC Name) must be system-wide unique!
Now, the FEC Name can contain up to 16 characters (and it will be truncated to 16 characters if you attempt to provide a longer name), so the combination of these 16 characters must be system-wide unique. This is fortunately not a name which is seen by most users of the control system, so it is maybe tempting to adopt a strategy bases of IP address and port of using some guaranteed unique name.
We advise against this. For one thing, this name does show up in log files and other diagnostic tools and it is therefor useful to have a meaningful name for the process. And if a registration results in a collision, then the ENS will refuse the name and the FEC process will be notified and will (at least under default conditions) terminate until the name collision is resolved.
This FEC information (i.e. its name and port offset) can be configured in local database files (e.g. fecid.csv or fec.xml) or set via API call (e.g. RegisterFecInformation() in C or systemInit() in java).
The simplest configuration for supplying the FEC information is a single column fecid.csv file providing just the FEC_NAME :
This will assign a port offset of 0 to the FEC and not supply any other associated information. A more extensive set of information can be provided by supplying not only the PORT_OFFSET column but other relavent columns as well :
If the CONTEXT column is given, then the Context provided will be applied to all exported device servers as long as the device server itself does not override the context information.
Multiple servers (on the same host) can make use of the same fecid.csv file, should the FEC_HOME environment variable point the FEC processes to the same directory. If the fecid.csv file is of the simpler form shown above, i.e. a single entry. Then only one of these FECs will be able to start, as they will both be trying to use not only the same FEC name but also the same port offset. To circumvent this problem (and it is indeed desired to point multiple FECs to the same configuration directory) you will need to include an EXPORT_NAME column.
If this column is present, then the FEC process will scan through the row entries in fecid.csv and attempt to match the registered device server name to a value in the EXPORT_NAME column. Upon the first match, then the associated row entries will define the FEC name and the port offset along with any other entries provided for the process which is starting.
As noted elsewhere in these documentation pages, the unique combination of device server Context and Server Name will ultimately be translated to a local equipment module name on some (uniquely named) FEC.
Now, this local equipment module name resides only within the process and is not required to be unique, which is a good thing, because it is composed of no more than 6 characters. This is also a name which a control system user seldom sees, but is used as an identifier within the process and some configuration files and also as a subdirectory name at the server.
The associated context can be that provided in the fecid.csv file or it can be given in an associated exports.csv file, which provides the device server name and (optionally) its context, along with a list of registered properties and their characteristics.
Note that column entries such as EXPORT_NAME, CONTEXT, and LOCAL_NAME might be repeated for each property that is registered in this way.
If you choose to use a fec.xml file for configuration, maybe because it offers a more logical, hierarchical, configuration perspective, then be aware that you then have the perspective of a single FEC process and its device servers, and that you cannot point multiple servers to the same FEC_HOME directory containing a single fec.xml file.
An example:
Running Multiple Servers on the Same Host
So the absolute simplest thing to do when launching a new server might be to set its FEC Name equal to its Server Name (e.g. MyServer) in some Context, and leave the Port Offset at its default value of 0. The Server Name can contain up to 32 characters, so MyServer works fine for both the FEC and the Server names.
This will work as long as there is no other server entry in the same context called MyServer and as long as there is no other FEC in the entire TINE site called MyServer.
What happens when you want to launch another server process on the same host?
Maybe you realize that they both can't be called MyServer and so configure the second server to to use Fec Name = Server Name = MyServer2 and give it a try.
If you do this you will have an immediate problem locally. The process will not even be able to send this new information to the ENS unless you remembered to set the Port Offset to something other than 0 (i.e. something other than the value the first server is using). The local host will not allow two different processes to bind to the same server port!
So the moral of the story is: each FEC process on a given host must have not only a unique FEC name but also a unique Port Offset.
If TINE is installed correctly on your system, then you will have an area (known as TINE_ROOT) where all processes can maintain and update various caching and manifest files. On Windows systems, this will be SystemDrive%\Tine. On Unix (Linux) systems, this will be /var/lib/tine. The FEC manifest is a file called fecmf.csv and will be located in the cache subdirectory in this TINE_ROOT area.
The API call GetPortOffset (C Lib) or TEquipmentModuleFactory.getPortOffset() (Java) will consult this manifest and return either the value of the current entry (if there is one) or the next best valid entry (if there isn't).
Should you have a FEC process with more than one server, then the strategy Fec Name = Server Name no longer makes sense and you will have to think of some representative FEC Name for the set of servers hosted by the process, just as you will have to make use of different server names (or possibly different Context names) as well as different local equipment module names for the two servers (remember that this latter name most be locally unique - i.e. within the process). You of course can launch two such servers on the same host as long as you provide unique FEC Names and ports and otherwise ensure that none of the servers is trying to use the same Context and Server names.
Performance Settings
Providing Good Service
1.5.8