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:\server\database 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 TINE_HISTORY_HOME (legacy: HISTORY_HOME) is set (a good idea!).
TINE_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 allowable log file scanning is limited to the directories and sub directories defined by the FEC_HOME and FEC_LOG settings. That is, the stock properties 'SRVLOGILE' (log file retrieval) and 'SRVLOGFILES' (log file browsing) will only scan and allow access to those files in the FEC_HOME/FEC_LOG areas. This can be influenced via the environment variable FEC_FILES_ALLOW_SCAN. If set to 'FALSE' or 'NONE' then no log file (other than fec.log) can be read via the stock property. If set to 'FULL' then all files and directories where the running FEC process has permissions will be able to be scanned and read. If set to 'TRUE' or 'FEC' then the default conditions apply. The API alternative to the environment variable is SetLogFileAllowScan(). For example
FEC_FILES_ALLOW_SCAN = FEC
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_MANAGEMENT = TRUE
A running server must have a unique address and a unique name. This includes the server's exported name (Context and Server) as well as the FEC name. If a server attempts to register itself with the equipment name server with a name that is already assigned to another address a prelimary check is made to determine whether the server is still active at the other address. If so the new registration is NOT accepted and an 'address in use' message is returned to the server attempting to initialize. If no server responds at the old address then the new address is accepted. This can lead to the situation where the new server process is running but unavailable to the control system because some other process with the same server or FEC name is running. This is generally NOT a good situation and servers are configured to halt if an address in use message comes while initializing. On some occasions it is expected or in any not event not a serious situation if such a name collision occurs and this behavior needs to be overridden. The API call SetDieOnAddressInUse(FALSE) can be made to override this behavior as can the envrionment variable
FEC_DIE_INUSE = FALSE
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_MCAST_ADDR
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). Under some circumstances it might be desireable to make use of a specific multicast address (e.g. for failover of a globals variable). This environment variable can be used for this purpose. Care should always be taken to ensure that only the server process sees this environment variable. A configuration file alternative is the local file (see below) 'mcastaddr.csv'. An API alternative is the call SetMCastAddr().
TINE_MCAST_MASK
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). The initial two bytes constitute the 'mask'. The first byte signals a multicast if it falls between 224 and 239. The second byte can be used as a multicast 'metric' to offer further distinction amoung multicast senders if required.
This environment variable can be used for this purpose. Likely, all processes on a given host will need to see this environment variable (if used). A configuration file alternative is the local file (see below) 'mcastmask.csv'. An API alternative is the call SetMCastMask().
TINE_GCAST_ADDR
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). Under some circumstances it might be desireable to make use of a specific multicast address in produce-consumer mode (e.g. for failover of a globals variable). This environment variable can be used for this purpose. Care should always be taken to ensure that only the server process sees this environment variable. A configuration file alternative is the local file (see below) 'gcastaddr.csv'. An API alternative is the call SetGCastAddr().
TINE_GCAST_MASK
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). The initial two bytes constitute the 'mask'. The first byte signals a multicast if it falls between 224 and 239. The second byte can be used as a multicast 'metric' to offer further distinction amoung multicast senders if required.
This environment variable can be used for this purpose. Likely, all processes on a given host will need to see this environment variable (if used). A configuration file alternative is the local file (see below) 'gcastmask.csv'. An API alternative is the call SetGCastMask().
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().
TINE_CACHE
This special environment variable can be used to establish the TINE cache area on the local host. This provides the location for the the dynamic address cache used as a failover address resolution for client applications. It also provides the location for the FEC manifest, which keeps a dynamic FEC specific startup database. Ideally ALL TINE processes should see this variable if it is used. To this end, the TINE cache area should allow ALL users write access to the subdirectory 'tine' in this area. If not used (often the case), then Windows systems will use SystemDrive% as the TINE cache and UNIX systems will first attempt to use /var/lib/. If no directory /var/lib/tine exists, then /var/tmp will be used (as this is always open writable. However /var/tmp is regularly emptied by most unix systems, so any information stored there will regularly disappear. API calls such as GetPortOffset() will make use of the TINE cache area to ascertain the appropriate FEC port offset, etc. Thus "$TINE_CACHE/tine" (unix) or "%TINE_CACHE%\tine" (windows) must allow all processes write and read access.
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
- cshosts.csv the identity and address of the equipment name server (ENS).
This is a special server which resolves TINE names into server addresses and process names, and has nothing to do with the domain name server (dns). e.g.FecName,IPaddr,OS,Description,Location,ResponsibleENS#0,131.169.120.41,LINUX,Name Server,Bldg 30a 1st Floor,P.DuvalENS#1,131.169.120.46,LINUX,Name Server,Bldg 30a 1st Floor,P.Duval- IF MISSING: the FEC does not know the identity of the name server and cannot register itself as a server or query the name server for names as a client.
- ALTERNATIVES: 1) The server can explicitly set the ENS address by calling SetNameServerAddress() prior to _SystemInit(). 2) The server can call FindNameServerOnNetwork() prior to _SystemInit(). 3) Clients can fall back on the local database files. If a server is already entered in the name server's database, then it does not need to "plug" itself into the system. 4) Addresses can also be entered by hand on the name server or via the Fec administration tool.
- ENVIRONMENT: variable TINE_HOME points to location; if not set the working directory is searched.
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:
- FEC directory (contains fecid.csv)
- BPMEQM directory (contains exports.csv, alarms.csv, devices.csv, history.csv, etc.) for BPMEQM
- ALMEQM directory (contains exports.csv, alarms.csv, devices.csv, history.csv, etc.) for ALMEQM
- etc.
- BPMEQM directory (contains exports.csv, alarms.csv, devices.csv, history.csv, etc.) for BPMEQM
- fecid.csv the identity of the Front End Controller (i.e. server) you are programming.
The information in this file is sent to the name server. If a server tries to use a name in use by a running FEC, the name server will refuse to honor the second set of information. It must be unique for each server. e.g.In the above, the columns PORT_OFFSET, CONTEXT, SUBSYSTEM, and EXPORT_NAME are optional. If absent, the PORT_OFFSET is assumed to be zero (or supplied by an API call).# File fecid.csv for plug and play entry of fec into control system,,,,,FEC_NAME,CONTEXT,EXPORT_NAME,PORT_OFFSET,SUBSYSTEM,DESCRIPTION,LOCATION,HARDWARE,RESPONSIBLEFECSIMXP.1,TEST,MSTNTSINE,1,TST,Test Server,Bldg 1 Rm 1,none,John DoeFECSIMXP.2,TEST,BUFSINE,2,TST,Another Test Server,Bldg 1 Rm 1,none,John Doe
If present, the CONTEXT will supply the de-facto context for all equipment modules which are registered ONLY if they do NOT supply this information themselves. In the situation where this column is absent AND the registered equipment module does NOT supply its context information then this will not be sent to the equipment name server. Likewise, if present the SUBSYSTEM will supply the de-facto subsystem for all equipment modules which are registered and do NOT supply this information themselves. If absent AND if the equipment module does not supply this information then this will not be sent to the equipment name server. The EXPORT_NAME column (or LOCAL_NAME) can be used to match FECs to servers, if the same FEC directory is used for multiple servers. In this case, all servers will read the same fecid.csv startup file and scan the file to match the server's export name (or local equipment module name) with the EXPORT_NAME (LOCAL_NAME) column. Likewise, DESCRIPTION, LOCATION, HARDWARE, and RESPONSIBLE provide informational data and are optional.- IF MISSING: the FEC does not know its own identity and cannot register itself as a server.
- ALTERNATIVES: 1) Call RegisterFecName() prior to call to _SystemInit() will take precedence. 2) Call GetMyServerAddress() prior to call to _SystemInit() will query the ENS for the assigned export name (useful for embedded FECs).
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- ipbcast.csv gives the list of IP networks on which the server is to send broadcasts. The server can send data to the network as network globals (producer-consumer mode) or as a network link (publish-produce). If multicast is enabled this will occur via multicast. In addition, the data will be broadcasted on the subnets found inside the ipbcast.csv file. SUBNET131.169.150.255131.169.121.255131.169.120.255131.169.110.255131.169.9.255
- IF MISSING: The server will not honor requests to send data as IP broadcasts.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- ipxbcast.csv gives the list of IPX networks on which the server is to send broadcasts. The server can send data to the network as network globals (producer-consumer mode) or as a network link (publish-produce). If multicast is enabled this will occur via multicast. In addition, the data will be broadcasted on the ipx nets found inside the ipxbcast.csv file. NETWORK,NODE,ROUTER83A96E00,FFFFFFFFFFFF,0000EF01C27083A99600,FFFFFFFFFFFF,0000EF01C27083A97900,FFFFFFFFFFFF,0000EF01C270
- IF MISSING: The server will not honor requests to send data as IPX broadcasts.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- myaddr.csv - (optionally) assigns the ip address of the FEC.
The FEC will normally obtain its IP address from that used by the ethernet card with the highest metric. If this file is present, then the ip address contained within will be assigned to the FEC. This file is sometimes useful where more than one ethernet card or IP address assignments are in play, and there is no clear metric. The enviroment variable FEC_ADDRESS can also be used to this end (and will take precedence in case of conflict).ADDRESS131.169.9.107- IF MISSING: The server will use the ip address assigned to the ethernet card with the highest metric.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- mcastaddr.csv - (optionally) assigns the ip multicast address of the FEC.
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). Under some circumstances it might be desireable to make use of a specific multicast address (e.g. for failover of a globals variable). This configuration file can be used for this purpose.ADDRESS238.1.9.107- IF MISSING: The server will use the last 2 bytes of the ip address assigned to the ethernet card with the highest metric preceded by '238.1'.
- ALTERNATIVES: SetMCastAddr() can also be used to establish a server's multicast address. The environment variable TINE_MCAST_ADDR (see above) can also be used to establish this address.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- Note
- as the ENS and GENS both clear this environment variable, this file should be present in local working directory of these server processes on the rare occasions where it is necessary (e.g. the ENS is needed to reponds to network server queries).
- mcastmask.csv - (optionally) assigns the ip multicast address mask of a server's multicast group. A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). The initial two bytes consitute the 'mask'. The first byte signals a multicast if it falls between 224 and 238. The second byte can be used as a multicast 'metric' to offer further distinction amoung multicast senders if required. This configuration file can be used for this purpose. ADDRESS238.2.9.107
- IF MISSING: Servers and clients will use the last 2 bytes of the ip address preceded by '238.1'.
- ALTERNATIVES: SetMCastMask() can also be used to establish a server's multicast address mask. The environment variable TINE_MCAST_MASK (see above) can also be used to establish this address mask.
- ENVIRONMENT: variables FEC_HOME (first choice) or TINE_HOME to location; if not set the working directory is searched.
- Note
- as the ENS and GENS both clear these environment variables, this file should be present in local working directory of these server processes on the rare occasions where it is necessary (e.g. the ENS is needed to reponds to network server queries).
- gcastaddr.csv - (optionally) assigns the ip multicast address of the FEC.
when used in producer mode (i.e. sending 'globals'). A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). Under some circumstances it might be desireable to make use of a specific multicast address (e.g. for failover of a globals variable). This configuration file can be used for this purpose.ADDRESS238.1.9.107- IF MISSING: The server will use the last 2 bytes of the ip address assigned to the ethernet card with the highest metric preceded by '238.1'.
- ALTERNATIVES: SetGCastAddr() can also be used to establish a server's multicast address. The environment variable TINE_GCAST_ADDR (see above) can also be used to establish this address.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- gcastmask.csv - (optionally) assigns the ip multicast address mask of the FEC.
A TINE server will by default use the multicast address '238.1.c.d.' where the last 2 bytes 'c' and 'd' are obtained from the server's own IP address (in IPv4 notation). The initial two bytes consitute the 'mask'. The first byte signals a multicast if it falls between 224 and 238. The second byte can be used as a multicast 'metric' to offer further distinction amoung multicast senders if required. This configuration file can be used for this purpose.ADDRESS238.2.9.107- IF MISSING: Servers and clients will use the last 2 bytes of a server's ip address preceded by '238.1'.
- ALTERNATIVES: SetGCastMask() can also be used to establish a server's multicast address mask. The environment variable TINE_GCAST_MASK (see above) can also be used to establish this address mask.
- ENVIRONMENT: variables FEC_HOME (first choice) or TINE_HOME to location; if not set the working directory is searched.
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.
- alarms.csv gives the alarm definitions pertaining to the specified equipment function. (alternative: <eqm>-alarms.csv where <eqm> refers to the 6-character local (internal) name.) (see also commments in the TINE Alarm System). e.g. ALARMTAG,ALARMCODE,ALARMMASK,SEVERITY,DATAFORMAT,DATAARRAYSIZE,ALARMTEXT,DEVICETEXT,DATATEXT,URL,ALARMSYSTEMBPM SEDAC error,79,0,1,short,3,Replace sedac module,BPM Module,"line,crate,subaddress",mst.desy.de/hepbpm/alarms,650Threshold exceeded,512,0,1,short,14,Beam dump pending,BPM Module,threshold value,mst.desy.de/hepbpm/alarms,650
- ALIAS: <eqm>-a.csv is also searched for in case of (for instance) DOS or Win16 servers on a 8.3 FAT file system.
- IF MISSING: The FEC has no knowledge of alarm information. You can still set and clear alarms. But all alarms will have severity 0, and an alarm Tag of "undefined".
- ALTERNATIVES: AppendAlarmInfoTable() can also be used to add items to the local alarm definitions list.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- almwatch.csv gives a list of properties and value thresholds for setting value_too_high and value_too_low alarms. A 'warning' threshold can also be supplied to set warn_too_high and warn_too_low alarms. (See TINE Alarm System) for more options. LOCALNAME,DEVICENAME,PROPERTY,SIZE,FORMAT,SEVERITY,HIGH,LOW,HIGHWARN,LOWWARN,FILTERSINEQM,#0,Amplitude,10,Float,15,500,0,400,10,/DESY2/GLOBALS[ParticleType]=1
- IF MISSING: The server will not automatically check and issue 'threshold' exceeded alarms.
- ALTERNATIVES: AppendAlarmWatchTable() can also be used to add items to the local alarm watch table.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- devices.csv gives device name binding to device numbers. (alternative: <eqm>-devices.csv) e.g. In the above, the columns DEVICE_DESCRIPTION, DEVICE_LOCATION, DEVICE_MASK, DEVICE_OFFLINE, DEVICE_ZPOS, PROPERTY_LIST, and REDIRECTION are optional. One can specify a list of registered properties which apply to a given device by making use of the PROPERTY_LIST column (see also: AssignPropertyList()) where a file name points to (yet another) .csv file consisting of a single column (PROPERTY_NAME) defining the properties assigned to the device. Under most circumstances ALL registered properties apply to all registered devices for a given equipment module. The DEVICE_MASK can be used to assign a mask bit for particular categories of devices. Wildcard calls or calls using the .DMASK. meta-property can then selectively obtain a list of devices with the desired device mask. The API call SetDeviceMask() can also be used to set this information.DEVICE_NAME,DEVICE_NUMBER,DEVICE_DESCRIPTION,DEVICE_MASK,DEVICE_ZPOS,DEVICE_OFFLINE,DEVICE_LOCATION,PROPERTY_LIST,REDIRECTIONWR094.AUSSEN, 0, WR 94 meters outer colimator jaw,1,94.1,0,,,WR094.INNEN, 1, WR 94 meters inner colimator jaw,1,94.1,0,,,WR094.OBEN, 2, WR 94 meters top colimator jaw,1,94.7,0,,,WR094.UNTEN, 3, WR 94 meters bottom colimator jaw,1,94.7,0,,,WR105.AUSSEN, 6, WR 105 meters outer colimator jaw,2,105.2,0,,,WR105.INNEN, 7, WR 105 meters inner colimator jaw,2,105.2,0,,,WR105.OBEN, 8, WR 105 meters top colimator jaw,2,105.8,0,,,WR105.UNTEN, 9, WR 105 meters bottom colimator jaw,2,105.8,0,,,
The DEVICE_OFFLINE flag, if set to something other than '0', can flag the device as being 'off-line'. Wildcard calls or calls using the .ONLINE meta-property can then selectively obtain a list of only those devices which are ONLINE (i.e. not off-line). The API call SetDeviceOfflineStatus() can also be used to set this information. The DEVICE_LOCATION can provide specific information as the phyisical location of the hardware device. The information text can contain redirection and environment variable tags, so that the information request can be passed on to a 'location service' (if it exists). For example the device location text "<$TINE_LCTR/131.169.145.66" would automatically redirect requests via stock property "DEVLOCATION" to a server determined via the environment variable "TINE_LCTR". The API call SetDeviceLocation() can also be used to set this information. The DEVICE_ZPOS (Z or longitudinal position) is optional information which can specify the meter position of the device within the accelerator facility (read by stock property "ZPOSITION"). The API call SetDeviceZPosition() can also be used to set this information. One can also register a device locally, but redirect all access to the device to another remote server by providing redirection information in the REDIRECTION column (see also SetRedirectionParameters()). The redirection string should have the form "/<context>/<server>/<device>[<property>]". In this case (redirecting all properties for a device), one should most likely omit the property. If one omits the device name, then the same device name is called at the server given. If one omits the property name, then the same property is called at the server given. If one omits the context, then the same context is assumed. Omitting the server name is not allowed. e.g. "/PETRA/RF.SL" will re-direct all calls for the device given in the DEVICE_NAME column to the server "RF.SL" in the context "PETRA".- ALIAS: <eqm>-d.csv is also searched for in case of (for instance) DOS or Win16 servers on a 8.3 FAT file system.
- IF MISSING: The FEC has no name binding with equipment numbers.
- ALTERNATIVE: RegisterDEviceName() can also be used to bind device names to device numbers. The .csv file has precedence.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- exports.csv gives the equipment functions and properties that your FEC is exporting. If a FEC tries to export a device server name currently in use by another FEC, the name server will refuse to accept the information. The export name must therefore be unique. The local (internal) name can of course be identical to that used elsewhere in the control system, making it possible to use the same executable program on many FECs. In the above, the column ACCESS in general supplies the allowed access ("READ","WRITE", or "READ|WRITE") supported by the property to be registered. In addition, the string "NETWORK" can be appended to the access field. This should only be used when the server expects multiple clients for the given property and desires to enforce efficent data acquistion by all of those interested in the property's information. In effect, this instructs the caller that ONLY asynchronous persistent data acquisition is possible and that the communication should go via multicast. Any normal polling acquisiton mode (CM_TIMER, CM_DATACHANGE) will automatically be converted to multicast acquisition. An an attempt to access the property synchronously will fail if this flag is in effect. If the ACCESS string also contains "XREAD" then the exclusive read attribute is applied to the corresponding property (falling through the same security logic for a WRITE access, either permenantly (no "READ" string) or temporarily (i.e. during an access lock, if both "READ" and "XREAD" are present). If the ACCESS string contains "SAVERESTORE" then the save-and-restore logic for the corresponding property will be applied (restored the last property settings upon server start, and save any settings following a WRITE command to the property. If the ACCESS string contains "HIST" then a local history of the registered property will be maintained using the 'default' local history settings (10 minute short term ring buffer, 1 month long term, 1000 msec polling and archive intervals, 10 % tolerance). This offers a 'quick' method for including a property in the local history subsystem. If the default history settings are not appropriate then the a 'history.csv' should be employed. If the ACCESS string contains "MT" (and the server is running as a multi-threaded server) then the associated property will be accessed on its own thread and thereby not block attempts to access other properties, unless the current access is a WRITE call. If it nonetheless desireable not to block equipment module access even for WRITE calls, the ACCESS string can also contain "INDEPENDENT" signalling that the property's WRITE access is independent of concurrent activity. The column DESCRIPTION provides a short desciptions of what the property does. In addition it is also used to provide the range and units settings pertaining to the property in question. The description text is parsed acording to the format "[vscale=<min>:<max> <units>][hscale=<xmin>:<xmax> <xunits>][vplot=<plot style>][hplot=<plot style>] [url=<url string>][desc=<description>]". Omitted items are simply left blank. Legacy style decription texts such as "[<min:max> <units>][<xmin:xmax> <units>]<description>" are also parsed accordingly. If the property represents a spectrum type property (i.e. a waveform or trace) then the range settings and units and units should be provided.EXPORT_NAME,LOCAL_NAME,PROPERTY,PROPERTY_SIZE,FORMAT,PROPERTY_INSIZE,INFORMAT,PROPERTY_ID,ACCESS,NUM_MODULES,DESCRIPTION,MASTER,SLAVE_MASTERBPM,BPMEQM,ORBIT.X,300,float,0,NULL, 1,READ,300,[-30:30 mm]Horizontal Orbit,,BPM,BPMEQM,ORBIT.Y,300,float,0,NULL, 2,READ,300,[-30:30 mm]Vertical Orbit,,BPM,BPMEQM,Status,300,short,0,NULL, 3,READ,300,[0:16 ]Monitor Status,,BPM,BPMEQM,ONLINE,1,short,1,short, 4,READ,300,[0:1 ]turn monitor on/off line,,
The text part of the description (the 'desc' tag or following all brackets in the legacy case) is limited to 64 characters. Alternatively, one can also supply the csv columns UNITS, MAX_VALUE, MIN_VALUE as well as XUNITS, XMAX_VALUE, and XMIN_VALUE to supply the units and settings for the nominal property value as well as its range (if applicable). This method would obviate the need for parsing the description for this information in any way (but at the same introduce a number of extra columns in the csv file. If the additional columns are used then a pure description text is typically all that is needed. Also in the above, the columns PROPERTY_INSIZE, INFORMAT, PROPERTY_ID, REDIRECTION, GROUP, GROUP_INDEX, GROUP_DEVICE_PREFIX, GROUP_DEVICE_POSTFIX, MASTER, and SLAVE_MASTER are all optional.
If PROPERTY_INSIZE, and INFORMAT are missing, the property's input information is taken to be the same as the output information for WRITE access calls. If REDIRECTION is present and not an empty string, it gives the redirection information for calls to the property in question. Thus a particular property can be exported as if it belongs to the device server, when in reality it belongs somewhere else. The redirection string should have the form "/<context>/<server>/<device>[<property>]". If one omits the property name, then the same property is assumed at the server given. If one omits the device name, then it is assumed the redirection applies to all device input. If one omits the context, then the same context is assumed. Omitting the server name is not allowed. e.g. "HISTORY[ORBIT.X]" will re-direct all calls for the property given in the PROPERTY column to the server "HISTORY" (the central archive server) and to the property "ORBIT.X". This would make sense if the property being redirected were something like "ORBIT.X.HIST" (i.e. a registered local history meta property), in which case a call to the 'local history' of property "ORBIT.X" is simply redirected to the central archiver in the given context. GROUP and GROUP_INDEX can be used to signal that the device server should join a device group of the name given. If GROUP_INDEX is greater than 0 it signals the list priority of its devices within the group. In addition, GROUP_DEVICE_PREFIX and GROUP_DEVICE_POSTFIX can be used to further refine the group definition if necessary. Namely an optional prefix and/or postfix can be applied to the server's locally registered device names at the group server. This offers a means of distinguishing among specific device names for different instances of identical servers (where each physical server's device list is also identical). If the MASTER column is present and not empty it designates a server name to use as a 'failover' master. If the booting server itself is the 'master' then the associated equipment module is additionally registered under the server name given in the master column. If the SLAVE_MASTER column is also present and not empty it designates a server whose connectivity is to be monitored and signals that the booting server is a 'failover' slave. If the monitored server goes down, the slave will then register itself additionally as the failover master. An example failover master might be:in which case, the exported server "LxSineServer1" will register itself as the 'master' for "SineServer". A corresponding failover slave might be:EXPORT_NAME,LOCAL_NAME,PROPERTY,PROPERTY_SIZE,PROPERTY_ID,ACCESS,FORMAT,NUM_MODULES,DESCRIPTION,MasterLxSineServer1,SINEQM,Sine,8192,1,READ.SPECTRUM,float,10,[-1000:1000 V][0:1000 ms]Sine Curve,SineServerin which case, the exported server "LxSineServer2" will monitor "LXSineServer1" and only register itself as the 'master' if "LxSineServer1" goes down.EXPORT_NAME,LOCAL_NAME,PROPERTY,PROPERTY_SIZE,PROPERTY_ID,ACCESS,FORMAT,NUM_MODULES,DESCRIPTION,Master,SlaveMasterLxSineServer2,SINEQM,Sine,8192,1,READ.SPECTRUM,float,10,[-1000:1000 V][0:1000 ms]Sine Curve,SineServer,LxSineServer1- If <Local_Name>/exports.csv is not found, then an initializing FEC will look in the root (FEC_HOME) directory for this file.
- IF MISSING: The FEC will NOT export any of its properties and all requests for properties over the net will meet with "illegal property", unless properties are registered with the API call RegisterPropertyInformation() and the equipment module registration provides an export name.
- ALTERNATIVES: RegisterEquipmentModule() can specify the Equipment Module Export name, and RegisterPropertyInformation() can register property information. The exports.csv file has precedence.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched. An initial search is made in a subdirectory with the same name as the registered local name whether in the FEC_HOME directory or in the working directory. Thus it is possible for a single FEC to examine more than one exports.csv file to retrieve export information. RedirectProperty() can be used to redirect a particular property to another location. (But see also RedirectDeviceName()). JoinEquipmentGroup() can be used to join a device group.
- If <Local_Name>/exports.csv is not found, then an initializing FEC will look in the root (FEC_HOME) directory for this file.
- history.csv gives properties that are to be used for in the local archive server (see also commments in the TINE Archive System). e.g. Index,Export Name,Local Name,Property,Device,Data Length,Format,Heartbeat,Polling Rate,Archive Rate,Tolerance,Short Depth,Long Depth,Filter1,BPM,BPMEQM,ORBIT.X,WL197,300,float,18000,1000,10,10%,600,1,/PETRA/GLOBALS[BeamCurrent]>0.52,BPM,BPMEQM,ORBIT.Y,WL197,300,float,18000,1000,10,10%,600,1,/PETRA/GLOBALS[BeamCurrent]>0.5
- IF MISSING: The server will not maintain any histories configured via this method in its local archive server.
- ALTERNATIVES: AppendHistoryInformation() can also specify the properties that are to be used for in the local archive server.
Properties can registered with the 'CA_HIST' access flag (API) or "HIST" string with exports.csv. This will maintain a local history of the designated property using the default local history settings (1 month long term, 10 minutes short term, 10% tolerance). The history.csv file has precedence in case of conflicts. - ENVIRONMENT: variable TINE_HISTORY_HOME points to location of the stored local history files; If not present the "../HISTORY" is assumed. The FEC_HOME points to location of the FEC's configuration files. If not set the working directory is taken as the root location. 'history.csv' is first searched for in the 'local name' subdirectory followed by the root location.
- users.csv gives the list of allowed users with WRITE access to your equipment module. e.g. This provides a 'soft' security against the accidental changing of settings from unauthorized users. It is however easy to circumvent this security layer. If this file is found directly in the root of FEC_HOME, then all equipment modules allow the same user access. An entry in 'users.csv' can also be of the form '</em domain:group>'. In such cases the given 'group' is scanned for its member list. In windows this amounts to a query against the given 'domain'. In unix the group members are acquired according to the NIS, LDAP, or local group scanning rules in place on the host machine (no matter what non-NULL domain text string is used). If no 'domain' is specified, then a local group member databaseUSERNAMEHERA_CONSOLESMITHJONES
with the name '<group>-members.csv' is scanned and read. If such a file does not exist, then the default scanning rules are again used. On a Windows system an attempt to determine the default domain is made by examining the environment variable USERDOMAIN. For examplewill ask the 'win' domain for the group members of group 'mhfe_user'.USERNAMESMITHJONES<win:mhfe_user>- IF MISSING: All users have WRITE access to your FEC.
- ALTERNATIVES: AppendRegisteredUserList() can also be used to add users to the users list. This works by either creating or updating the users.csv file. So a file system is currently needed to use this API call.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- alias.csv gives a list of alias names which the server will honor. If present, this list is maintained in a hash table and is checked against the requested PROPERTY, the requested DEVICE, and the requested local equipment module name. NAME,ALIASSINE,COSINETEST,LINESINEDEV_0,DEV0SINEDEV_2,DEV2
- IF MISSING: The server will not make use of any alias names.
- ALTERNATIVE: See RegisterPropertyAlias().
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
FEC-specific Security CSV Files
- ipnets.csv gives the list of IP networks (and/or hosts) with WRITE access to your server. e.g. This provides a 'hard' security against the changing of settings from unauthorized networks or stations. The list of IP address can refer to an entire subnet (last byte = '.255') or specific stations.SUBNET131.169.150.255131.169.121.255131.169.120.255131.169.110.255131.169.9.255
- IF MISSING: All ip addresses have WRITE access to your FEC.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
- ipxnets.csv gives the list of IPX networks (and/or nodes) with WRITE access to your server. e.g. This provides a 'hard' security against the changing of settings from unauthorized networks or stations. The list of IPX address can refer to an entire subnet (all 'FF's) or specific mac addresses.NETWORK,NODE,ROUTER83A96E00,FFFFFFFFFFFF,0000EF01C27083A99600,FFFFFFFFFFFF,0000EF01C27083A97900,FFFFFFFFFFFF,0000EF01C270
- IF MISSING: All ipx addresses have WRITE access to your FEC.
- ENVIRONMENT: variable FEC_HOME points to location; if not set the working directory is searched.
Property-specific Configuration CSV Files
- <property>-names.csv gives a device list for a multi-channel property. e.g. DEVICE_NAME,DEVICE_NUMBERWR094.AUSSEN, 0WR094.INNEN, 1WR094.OBEN, 2WR094.UNTEN, 3WR105.AUSSEN, 6WR105.INNEN, 7WR105.OBEN, 8WR105.UNTEN, 9
- IF MISSING: The multi-channel array falls back onto the equipment module's registered device list.
- ALTERNATIVE: A Meta-property '<property>.NAM' can be registered and handled at the server level. Such properties are required to return a list of NAME16 name objects giving the device names for the array elements of the specified <property>.
- ALTERNATIVE: The API call AssignDeviceListToProperty() may also be used to assign a device list to a property.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location.
Files are first searched for in the 'local name' subdirectory followed by the root location.
- <property>-users.csv gives a users access list for a specific property. e.g. Groups can be used here just as with the server specific users.csv file.USERNAMEHERA_CONSOLESMITHJONES
- IF MISSING: The access for the property is given by the general FEC and equipment module access lists.
- ALTERNATIVE: The API call AssignPropertyAccessList() may be used to assign a users access list to a property.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- NOTE: A file of this format specifically named 'property-default-users.csv' can be used to provide a default access list for all properties where a specific file is not found. This is useful in cases where all properties are allowed access to a general list except for a single (or a few) property (properties). Otherwise a large collection of 'repetitive' files would be necessary.
- <property>-ipnets.csv gives a network address access list for a specific property. e.g. SUBNET131.169.150.255131.169.121.255131.169.120.255131.169.110.255131.169.9.255
- IF MISSING: The access for the property is given by the general FEC and equipment module access lists.
- ALTERNATIVE: The API call AssignPropertyNetsList() may be used to assign a network address access list to a property.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- NOTE: A file of this format specifically named 'property-default-ipnets.csv' can be used to provide a default access list for all properties where a specific file is not found. This is useful in cases where all properties are allowed access to a general list except for a single (or a few) property (properties). Otherwise a large collection of 'repetitive' files would be necessary.
Device-specific Configuration CSV Files
- <device name>-users.csv gives a users access list for a specific device. e.g. Groups can be used here just as with the server specific users.csv file.USERNAMEHERA_CONSOLESMITHJONES
- IF MISSING: The access for the device is given by the general FEC and equipment module access lists.
- ALTERNATIVE: The API call AssignDeviceAccessList() may be used to assign a users access list to a device.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- NOTE: A file of this format specifically named 'device-default-users.csv' can be used to provide a default access list for all devices where a specific file is not found. This is useful in cases where all devices are allowed access to a general list except for a single (or a few) device(s). Otherwise a large collection of 'repetitive' files would be necessary.
- <device name>-ipnets.csv gives a network address access list for a specific device. e.g. SUBNET131.169.150.255131.169.121.255131.169.120.255131.169.110.255131.169.9.255
- IF MISSING: The access for the property is given by the general FEC and equipment module access lists.
- ALTERNATIVE: The API call AssignDeviceNetsList() may be used to assign a network address access list to a device.
- ENVIRONMENT: variable FEC_HOME points to the root location; if not set the working directory is taken as the root location. Files are first searched for in the 'local name' subdirectory followed by the root location.
- NOTE: A file of this format specifically named 'device-default-ipnets.csv' can be used to provide a default access list for all devices where a specific file is not found. This is useful in cases where all properties are allowed access to a general list except for a single (or a few) device(s). Otherwise a large collection of 'repetitive' files would be necessary.
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\.
For the equipment module with local name "BPMEQM", a set of configuration files might be:
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.
A basic straightforward example of a fec.xml file is shown below.
Generally, properties which are associated with the entire FEC process have sections directly below the <FEC> tag (e.g. the FEC name, port offset). The FEC process will have one or more equipment modules (<EQM> sections). Within an <EQM> section, the equipment module name <\NAME> is given along with its exported server name <SERVER>, context <CONTEXT>, subsystem <SUBSYSTEM>, any grouping information (<GROUP>, <GROUP_INDEX>), alarm definitions <ALARM_DEFINITION>, total device capacity <DEVICE_SPACE>, and global access control lists.
To specify the later, one includes a <NAME_LIST> with a <NAME> tag specifically called with "USERS_ALLOWED" and/or "NETS_ALLOWED" depending on the form of access that is being restricted.
For example:
Note that in the above, both a users list and a networks list are being applied. Also note that the users list given contains the users group "<win:mcs_user>". The xml parser ultimately needs to apply the string "<win:mcs_user>" which itself contains '<' and '>' symbols, which necessitates the standardized '<' and '>' coding conventions.
If such access lists are to be applied to specific devices or properties, the equivalent sections need only be embedded within the corresponding <DEVICE> or <PROPERTY> sections.
To assign, for example, a specific property list to a device, one includes a <NAME_LIST> section within the associated <EQM>, which should list those properties belonging to the list. For example:
Then within the appropriate device section, one includes a <PROPERTY_SET> tag:
In a similar fashion, one can assign device lists to properties (in the case of 'property servers') by assigning a specific <NAME_LIST> containing device names to a <PROPERTY> via an embedded <DEVICE_SET> tag.
