Main Page | Features | Central Services | csv-Files | Types | Transfer | Access | API-C | API-VB/ActiveX | API-Java | Examples | Downloads
Configuration Files

A tine control system application will need to make use of certain configuration settings. A pure client application for instance will need to be able to resolve addresses for the servers it needs to talk to. A server application on the other hand needs to identify itself and potentially change certain parameters away from their default settings.

All configuration information can be hard-coded within the application by making use of the pertinent registraion API calls. This is most often not the best way of establishing this information, and as long as the server has a file system, it should be avoided. In case of embedded servers, where there is no disk, the solution to use the API calls is sometimes warranted. See for instance Server Registration API Calls. Gateways will also frequently need to make use the API registration as much of the startup information needs to be queried before hand.

Historically the TINE configuration files were of the 'comma separated value' (csv) type, as they are human-readable ascii files, editable with any text editor or spreadsheet application. Typically, each subsystem in the TINE kernel looks for different .csv files, which necessitates some form of equipment-module based hierarchy where multiple servers are run on a given host. These files are described below. Another alternative (as of TINE Release 4.0) is to maintain the configuration information within a single .xml file called fec.xml, which naturally has the necessary hierarchy. This will be described at the end of this section.

Configuration by Environment

If csv files are used to configure a tine server (normally the case) then the server application must know where to look for the relevant files. Client applications as well as server applications need to find the equipment name server(s). The address of the configured equipment name server is typically contained in a csv file named 'cshosts.csv'. The application will look in the working directory for this file unless the environment variable TINE_HOME is set to point to the default location.

TINE_HOME = /usr/etc/tine/ (for example on a unix system)

Note:
TINE_HOME can also contain a local static address database to be consulted if 'all else fails'.

In lieu of this, the addresses of the equipment name servers can also be supplied via the environment variable TINE_ENS, for instance:

TINE_ENS = 131.169.120.41:131.169.120.46

If the ENS address is still not known at initialization time a request is made to the configured domain name server (DNS) for the address of 'tineens' on the current domain. If an address is is known, it is then used (however this technique will only provide a single primary ENS to the tine kernel, so there is no fail-over on error).

Another alternative (good for embedded servers) is to make use of the API call FindNameServerOnNetwork(), which issues a multicast request and waits for all equipment name servers to respond.

Note:
Address resolution might still succeed even if no ENS is configured! This is because, as a last resort, the local address cache is consulted for name resolution if an address is otherwise unresolved. Likewise if there is a static local database (in the TINE_HOME directory) this will be scanned for addresses as a last resort. However, this only applies to operating systems which have a disk!

If a server application uses csv configuration files it will look for them in its working directory unless the environment variable FEC_HOME is set (the legacy variable FECDB still works as well). For example (windows)

FEC_HOME = L:\server\database\

will instruct the server to look in the directory L: for all relevant startup files. In addition, if the server is maintaining a local history it will use the FEC_HOME area as a repository unless the variable HISTORY_HOME (legacy: HISTORYDB) is set (a good idea!).

HISTORY_HOME = /localhome/fecadmin/hepbpm/HISTORY/ (for example on a unix system).

A server will likewise put its log files inside the FEC_HOME directory unless the environment variable FEC_LOG is also set. For instance,

FEC_LOG=L:\Log

The default log depth (before rotating) is 500 lines. This also can be configured via an environment variable, FEC_LOGDEPTH, e.g.

FEC_LOGDEPTH = 5000

The default minimum allowable polling rate (or rather polling interval) is typically 200 msec. (This will help keep renegade clients from making impossible demands on your server). This can be set via the environment variable FEC_POLLRATE. For example

FEC_POLLRATE = 50

The default maximum allowable payload is typically 64 Kbytes. Some servers (especially video servers) will want to set this to a much higher value (although note that this will lock this much memory out of main memory). You can do this with an enviroment variable as well, namely FEC_WORKAREASIZE.

FEC_WORKAREASIZE = 512000 (for example)

The default maximal transport unit (MTU) which servers use in sending data grams is the standard ethernet MTU of 1472 bytes. All Operating Systems will be able to utilize datagrams of this size. Most modern operating systems can make use of MTUs up to 64KByte (65535 bytes), which places a good deal more of the packet reassembly necessary for large data payloads in the network kernel. Setting the MTU to larger values such as this can lead to a marked increase in performance. If access to the API call SetPacketMTU() is not avaialable, then this value can be set by making use of the environment variable FEC_PACKETMTU.

FEC_PACKETMTU = 65500 (for example)

Note however, than as all operating systems will not by default, be able to deal with such large datagrams (e.g. VxWorks) one should make use of such performance enhancements only when necessary.

The stock properties "SRVEXIT", "SRVINIT", and "SRVRESET" are only active if 'remote management' is allowed. (The stock properties are otherwise visisble but will return 'not_allowed' if accessed). By default 'remote management' is OFF and can be turned on via the server API call SetAllowRemoteManagement() or via the environment variable FEC_REMOTE_MANAGEMENT.

FEC_REMOTE_MANAGMENT = TRUE

The physical location of the FEC will be the same as the host computer on which the FEC process resides. This is generally a column in the fecid.csv or tag in the fec.xml configuration database, or it has been passed as a parameter in a call to RegisterFecInformation(). The text string entered in any of these cases can be forcefully overridden by supplying the environment variable FEC_LOCATION. For example

FEC_LOCATION = "Bldg 20 Rm 103 Rack 2"

In a similar fashion any 'sub system' information supplied via an exports.csv or fec.xml file can be forcefully overridden by supplying an environment variable of the form <local_name >_SUBSYSTEM. For example

BPMEQM_SUBSYSTEM = DIAG

where 'BPMEQM' is the local equipment module name of the device server.

Finally if you are not on Central European Time, you can set the time zone string printed in log files by using the environment variables STD_TIME_STR and DST_TIME_STR. For example,

STD_TIME_STR = JST

DST_TIME_STR = JST

sets the standard time zone and the daylight savings timezone to point to the same variable JST (Japanese Standard Time - there is no daylight savings time in Japan). If both setting are the same, as in this case, the check for daylight savings time is turned off on those operating systems that don't make this check automatically (e.g. NIOS, VxWorks). If the rules for daylight savings time differ from the Central European rules, a findDaylightHook() function should be supplied when linking the server application.

Note:
A Java alternative is to use a tine.properties file containing these variables (replacing underscores with '.' and using only lower case). A tine.properties file should then accompany the tine.jar library.

Additional environment variables used for configuration include:

TINE_STANDALONE

when set to 'TRUE' instructs a server to forgo registering itself with the ENS and to update its local entry in the cache tables with the loopback address (127.0.0.1). Client programs on the same machine will not attempt name resolution via the ENS but instead only consult the local address cache and therefore use the loopback address.

TINE_NETWORKADDRESS_RESOLUTION

when set to 'TRUE' instructs a server to responds to 'network' (i.e. multicast) requests for address resolution. It likewise allows client applications to resolve addresses by issuing a 'where are you' multicast in case all other attempts at address resolution fail. In cases where a small TINE system needs to run without any infrastructure (i.e. without a running ENS), clients will issue a 'where are you' multicast, and the targeted server will be able to respond if this has been set to TRUE. An API alternatives are (server-size) the function SetRespondToServiceRequests() and (client-side) SetAllowNetworkAddressResolution().

TINE_TRANSPORT

when set to 'TCP' instructs the client subsystem to use only connected sockets (TCP/IP) for communication.

TINE_QUEUEDEPTH

Can be set to an integer value which will establish the default client-side link queue depth (default = 10). This can be used in lieu of the API call SetClnRecvQueueDepth().

TINE_BURSTLIMIT

sets a server's burst limit to the value given. This can be used in lieu of the API call SetBurstLimit().

TINE_REMOTE_PIPE

when set to 'FALSE' will turn off local diagnostic access via a named PIPE.

TINE_USE_LOOPBACK (or TINE_USELOOPBACK)

when set to 'TRUE' will will cause all local communication to use sockets plus the local IP address instead of a named pipe (unix) or windows messages. An API alternative is SetUseLoopback().

TINE_USE_GLOBAL_SYNCHRONIZATION

when set to 'FALSE' will turn OFF the global time sychronization of data timestamps. This is sometimes a good option when a CPU has a 'bad' clock which is often being corrected by NTP and possibly causing negative jumps in the data timestamp offset.

RDATE

sets the address of a time server which can be used for time synchronization for some operating systems. If not set, an attempt is made to use 'time' on the local domain.

FEC_ADDRESS

sets the FEC process IP address explicitly. This should only be used if multiple ethernet cards are being used and the server should use an address that is not the highest configured metric.

FEC_GCAST_ADDR

sets the FEC process multicast address. This should only be used if the multicast address which should be used is not the same as its 'canonical' multicast address (e.g. using a software-failover with a redundant server). This can be used in lieu of the API call SetGCastAddr().

TINE_HISTORY_ALLOC_FILESET

if set to 'TRUE' instructs the local history subsystem to pre-allocate non-fragmented 'worst-case' local history files. This is an operation that can take some time. This envirnoment variable should be set and the cleared once the file set has been generated.

TINE_HISTORY_FREE_BLOCKS

sets the minimum disk space to maintain to the value specified (in blocks). This will guarantee that the amound of disk space given is always available. This setting is in lieu of the API call SetMinimumDiskSpaceInBlocks().

csv Configuration Files

TINE Server Startup Configuration CSV Files

We shall discuss the startup .CSV files in some detail below. In theory, a TINE server can run fine without using a single startup .CSV file (although in practice you probably will want to make use of some subset of them). The location of these files is generally given by the environment setting FEC_HOME. The exception is cshosts.csv, whose location is given by TINE_HOME. This is due to the fact that a server is momentarily a client to the name server upon startup (see discussion on Plug and Play).

Most servers will make use of the 'big three' .csv files, namely 'cshosts.csv', 'fecid.csv', and 'exports.csv'. As mentioned above, 'cshosts.csv' is a configuration file common to the client as well as the server substructure and serves only to provide the address(es) of the TINE Equipment Name Server(s) (ENS).

Common Configuration CSV Files

FEC-specific Configuration CSV Files

If a FEC contains a single equipment module and looks in a single location for its configuration files (i.e. it uses its working directory as a repository or otherwise has a process-specific FEC_HOME environment variable) then all .csv files can be kept in the same directory. Otherwise, it is advisable to keep a subdirectory for each equipment module, whose name is the local equipment module name:

Equipment Module-specific Configuration CSV Files

Equipment module related configuration files can be kept in the root (FEC_HOME) directory (where fecid.csv is kept) or in equipment module specific subdirecties (relative to the FEC_HOME directory) whose subdirectory name is give by the local equipment module name. Equipment module specific configuration files and examples are given below.

FEC-specific Security CSV Files

Property-specific Configuration CSV Files

Device-specific Configuration CSV Files

As an example of a typical FEC .csv configuration set (where much use is made of configuration files over API calls) consider the following directory structure, where FEC_HOME is set to c:\Servers\.

eg_fechome_config.jpg

For the equipment module with local name "BPMEQM", a set of configuration files might be:

eg_bpmeqm_config.jpg

xml Configuration Files

As of TINE Release 4.0 you can maintain a complete configuration description of FECs hosted on a computer via a single xml file. Namely, the hierarchy which otherwise existed via specific .csv Files in specific directories (as noted in the above section) can now be expressed as xml tags. This file must be called fec.xml, and if found will take precedence over any collection of FEC related .csv Files found.

Without further explanation, we show an example fec.xml file below.

<?xml version="1.0" encoding="UTF-8"?>
<FEC>
    <NAME>SINEGEN.19</NAME>
    <PORT_OFFSET>19</PORT_OFFSET>
    <HISTORY_HOME>L:/HISTORY</HISTORY_HOME>
    <ALIAS>
        <NAME>CoSine</NAME>
        <TARGET>Sine</TARGET>
    </ALIAS>
    <EQM>
        <NAME>SINEQM</NAME>
        <SERVER>WinSineServer</SERVER>
        <CONTEXT>TEST</CONTEXT>
        <SUBSYSTEM>DIAG</SUBSYSTEM>
        <GROUP></GROUP>
        <GROUP_INDEX></GROUP_INDEX>
        <ALARM_DEFINITION>
             <TAG></TAG>
             <DATA_FORMAT></DATA_FORMAT>
             <ALARM_TEXT></ALARM_TEXT>
             <DEVICE_TEXT></DEVICE_TEXT>
             <DATA_TEXT></DATA_TEXT>
             <URL></URL>
             <ALARM_CODE></ALARM_CODE>
             <ALARM_MASK></ALARM_MASK>
             <SEVERITY></SEVERITY>
             <ALARM_SYSTEM></ALARM_SYSTEM>
             <DATA_SIZE></DATA_SIZE>
        </ALARM_DEFINITION>
        <NAME_LIST>
             <NAME>SineGen0List</NAME>
             <MEMBER>Sine</MEMBER>
             <MEMBER>Amplitude</MEMBER>
        </NAME_LIST>
             <DEVICE_SPACE>10</DEVICE_SPACE>
        <DEVICE>
             <NAME>SineGen0</NAME>
             <NUMBER>0</NUMBER>
             <PROPERTY_SET>SineGen0List</PROPERTY_SET>
             <REDIRECTION></REDIRECTION>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen1</NAME>
             <NUMBER>1</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen2</NAME>
             <NUMBER>2</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen3</NAME>
             <NUMBER>3</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen4</NAME>
             <NUMBER>4</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen5</NAME>
             <NUMBER>5</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen6</NAME>
             <NUMBER>6</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen7</NAME>
             <NUMBER>7</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen8</NAME>
             <NUMBER>8</NUMBER>
        </DEVICE>
        <DEVICE>
             <NAME>SineGen9</NAME>
             <NUMBER>9</NUMBER>
        </DEVICE>
        <PROPERTY>
             <NAME>Sine</NAME>
             <DEVICE_SET></DEVICE_SET>
             <EGU>V</EGU>
             <XEGU>r</XEGU>
             <MAX>1000</MAX>
             <MIN>0</MIN>
             <XMAX>8092</XMAX>
             <XMIN>0</XMIN>
             <ID>0</ID>
             <DESCRIPTION>Sine Curve</DESCRIPTION>
             <SIZE_IN>0</SIZE_IN>
             <DTYPE_IN>null</DTYPE_IN>
             <SIZE_OUT>1024</SIZE_OUT>
             <DTYPE_OUT>float.SPECTRUM</DTYPE_OUT>
             <ACCESS>READ</ACCESS>
             <REDIRECTION></REDIRECTION>
             <ALARM>
                  <DEVICE_NAME>SineGen0</DEVICE_NAME>
                  <SEVERITY_HIGH>12</SEVERITY_HIGH>
                  <SEVERITY_LOW>12</SEVERITY_LOW>
                  <SEVERITY_HIGH_WARN>10</SEVERITY_HIGH_WARN>
                  <SEVERITY_LOW_WARN>10</SEVERITY_LOW_WARN>
                  <SYSTEM>100</SYSTEM>
                  <VALUE_MASK></VALUE_MASK>
                  <VALUE_NORMAL></VALUE_NORMAL>
                  <COUNT_THRESHOLD>3</COUNT_THRESHOLD>
                  <VALUE_HIGH>800</VALUE_HIGH>
                  <VALUE_LOW>50</VALUE_LOW>
                  <VALUE_HIGH_WARN>700</VALUE_HIGH_WARN>
                  <VALUE_LOW_WARN>100</VALUE_LOW_WARN>
             </ALARM>
             <HISTORY>
                  <DEVICE_NAME>SineGen0</DEVICE_NAME>
                  <TOLERANCE>10%</TOLERANCE>
                  <REDIRECTION></REDIRECTION>
                  <INDEX>1</INDEX>
                  <HEARTBEAT>900</HEARTBEAT>
                  <POLL_RATE>1000</POLL_RATE>
                  <ARCHIVE_RATE>1000</ARCHIVE_RATE>
                  <DEPTH_SHORT>600</DEPTH_SHORT>
                  <DEPTH_LONG>3</DEPTH_LONG>
             </HISTORY>
        </PROPERTY>
        <PROPERTY>
            <NAME>Amplitude</NAME>
            <DEVICE_SET></DEVICE_SET>
            <EGU>V</EGU>
            <MAX>1000</MAX>
            <MIN>0</MIN>
            <ID>1</ID>
            <DESCRIPTION>Sine Curve Amplitude</DESCRIPTION>
            <SIZE_IN>1</SIZE_IN>
            <DTYPE_IN>float</DTYPE_IN>
            <SIZE_OUT>10</SIZE_OUT>
            <DTYPE_OUT>float.CHANNEL</DTYPE_OUT>
            <ACCESS>READ|WRITE</ACCESS>
            <REDIRECTION></REDIRECTION>
        </PROPERTY>
        <PROPERTY>
            <NAME>Frequency</NAME>
            <DEVICE_SET></DEVICE_SET>
            <EGU>Hz</EGU>
            <MAX>60</MAX>
            <MIN>1</MIN>
            <ID>2</ID>
            <DESCRIPTION>Sine Curve Frequency</DESCRIPTION>
            <SIZE_IN>1</SIZE_IN>
            <DTYPE_IN>float</DTYPE_IN>
            <SIZE_OUT>10</SIZE_OUT>
            <DTYPE_OUT>float.CHANNEL</DTYPE_OUT>
            <ACCESS>READ|WRITE</ACCESS>
            <REDIRECTION></REDIRECTION>
        </PROPERTY>
        <PROPERTY>
            <NAME>Phase</NAME>
            <DEVICE_SET></DEVICE_SET>
            <EGU>r</EGU>
            <MAX>128</MAX>
            <MIN>0</MIN>
            <ID>3</ID>
            <DESCRIPTION>Sine Curve Phase</DESCRIPTION>
            <SIZE_IN>1</SIZE_IN>
            <DTYPE_IN>float</DTYPE_IN>
            <SIZE_OUT>10</SIZE_OUT>
            <DTYPE_OUT>float.CHANNEL</DTYPE_OUT>
            <ACCESS>READ|WRITE</ACCESS>
            <REDIRECTION></REDIRECTION>
        </PROPERTY>
        <PROPERTY>
            <NAME>SineInfo</NAME>
            <DEVICE_SET></DEVICE_SET>
            <EGU></EGU>
            <MAX></MAX>
            <MIN></MIN>
            <ID>4</ID>
            <DESCRIPTION>Sine Curve Info Structure</DESCRIPTION>
            <SIZE_IN>1</SIZE_IN>
            <DTYPE_IN>struct.SineInfo</DTYPE_IN>
            <SIZE_OUT>1</SIZE_OUT>
            <DTYPE_OUT>struct.SineInfo</DTYPE_OUT>
            <ACCESS>READ|WRITE</ACCESS>
            <REDIRECTION></REDIRECTION>
        </PROPERTY>
     </EQM>
</FEC>
Generated for TINE API by  doxygen 1.5.8