Working with a Buffered Server

Before you start coding ...

You might want to have a quick look at the PowerPoint presentation before proceeding.

The buffered server API is probably the easiest to use to generate functional TINE servers. As a server programmer you have to deal with a miminum of API calls in order to export your data or accept commands. We'll start by using this interface, since it will exercise most of the server configuration possibilites via the commas-separated-value (.csv) configuration files.

This is called a "buffered" server as the caller's input and output buffers are managed for you. This makes life easy, but removes a lot of flexibility (but also sources of error) from you.

Fully coded servers can continue to use the same configuration files to initialize the server. We shall progress to these later.

FEC configuration files

Determine where your test FEC's configuration files will be. Check the environment variable FEC_HOME. If not set (this is also okay) then the working directory will be used. However, if set the configuration files must be found where this environment variable points.

The suggestion, however is to use FEC_HOME=c:\tine\server\ in windows and ignore it in Linux.

Tine servers can in general run without any configuration files. In this case, however, all startup information must be provided via using the registration API calls. Although this is also possible with the buffered server, it is generally much, much easier to make use of startup configuration files. These can for the most part be generated for you by using the FEC and Server setup wizards.

As a bare minimum, you will need two configuration files to get your buffered server to run properly. These are

• fecid.csv

which provides information pertaining to the Front End Controller itself, the most important of which are its name and its port; and

• exports.csv

which provides information pertaining to the device servers which run on this FEC, such as which equipment modules and which properties are supported.

An example fecid.csv file might be:

FEC_NAME,CONTEXT,PORT_OFFSET,SubSystem,DESCRIPTION,LOCATION,HARDWARE,RESPONSIBLE
SINESRV.0,TEST,0,TST,Sine Test Server,Bldg 1 Rm 1,none,John Doe

An example exports.csv file might be:

EXPORT_NAME,LOCAL_NAME,PROPERTY,PROPERTY_SIZE,FORMAT,PROPERTY_INSIZE,INFORMAT,PROPERTY_ID,ACCESS,NUM_MODULES,DESCRIPTION,NUM_STEPS
SINEWAVE,SINSIM,SINE,1024,float,0,NULL, 1,READ,0,[0:256 A]Sine Curve,0

These are just example files. You can make them by hand, but we'll be using the FEC wizard and Server wizard to generate them for us.

The tine csv parser will treat the first non-comment line as a header and look for the column locations in the header. The position of a column in the header is unimportant, but if it is required it must be there! Some columns are optional, and it ommitted, a default action will be taken. When using a spread-sheet such as Excel to examine or edit a csv file, the columns will line up visually very well and it is easier to see what belongs to what.

Other configuration files which we will be using as we go along include (but are not limited to):

• devices.csv

which provides a device list to the designated equipment module. This has the effect of assigning names to numbers.

• history.csv

which provides a list of properties which should be accessed by the local history subsystem.

• almwatch.csv

which provides a list of properties which should be accessed by the local alarm subsystem.

• users.csv

which provides a list of users who have WRITE access to those properties which change settings.

• ipnets.csv

which provides a list of subnets or individual ip addresses which have WRITE access to those properties which change settings.

All of these files should be found in the FEC_HOME area if they are to be read by the tine server. Or if FEC_HOME is not set, they should be found in the working directory.

Note:

: The FEC setup wizard does nothing other than manage the fecid.csv file. It will edit and maintain this file directly in the FEC_HOME area. The Server setup wizard however will not only manage the exports.csv file (and history.csv, almwatch, devices.csv files), but will also generate code if you tell it to (we'll get to this later). In other words the Server wizard will manage the behavior of your server (to some extent anyway) and will put all of its files (code and the .csv files) in the directory you give as your working directory. You can set this working directory to be the same as your FEC_HOME area and everything will be there. This may or may not be a good idea. It is probably a better idea to keep a project directory and copy the .csv files resulting from any changes into the FEC_HOME area when you are satisfied will them.

A Name for your server

Decide on the names of your FEC and your device server. If there's only going to be one device server attached to the FEC then they can be the same name. You can also use the computer host name (maybe appended with a ".<port offset>" such as "zitschl04e.0" as your fec name. And let's use the context "WORKSHOP" instead of the default "TEST".

Everyone will be able to see and browse for your device server name so choose a good one! For the sake of this example we'll pretend you chose "MYSINE" (we can't all choose this name, because the ENS will prevent more than one server from using an export name at a time).

Note:

: The Equipment Module "Local Name" for historical reasons is limited to 6 characters (think of that old 8.3 file system on MSDOS and 16-bit windows). The other names can have up to 16 characters. A property name can be up to 32 characters, but it is also suggested to stick to 16 characters or less. The server wizard will choose a suitable local name for you. The suggestion is to use it. This name is not visible at the control system level and does not need to be system-wide unique. It only needs to be locally (i.e. within the server process) unique.

fecid.csv

Use the Fec Setup Wizard to make a fecid.csv file. Note this wizard will automatically set FEC_HOME to c:\database\ if FEC_HOME is not already set.

Note:

The FEC wizard has a combo box for the "Exported Device Server Name", which is actually more of relevance for the Server wizard and not the FEC wizard. So why is it there? It turns out, you can leave it blank! The wizard will automatically create an optional column "EXPORT_NAME" in the fecid.csv if this item has an input. And this will allow multiple servers to use the same fecid.csv file. The problem is that if more than one server reads the same fecid.csv file it has to know which FECNAME belongs to it. It does this by trying to find a match in its exported device server name and an entry in fecid.csv file. If this item is absent, or the column is missing, the the first FEC name in the list is used. In the UNIX (i.e. non-Windows) world this is actually the usual strategy. There is no "Export_name" column in fecid.csv and fecid.csv contains only one line. This works if there is no FEC_HOME environment and the working directory is used, or if FEC_HOME is set individually for each server. In the windows world, FEC_HOME is usally set for the machine and all running servers read the same fecid.csv file. What this means though, is that the same Export Name is kept in two different configuration database files, which is a potential source of startup errors. This kind of error is usually fairly easy to find, however.

The Unix world is currently at a disadvantage here. There is a tcl script which can generate the fecid.csv file for you, but you are probably better off generating it by hand.

exports.csv

Use the Server Setup Wizard to make an exports.csv file. Don't generate any code yet! Leave the "C" and "VB" check boxes un-checked. If you're using the tcl script, this isn't an option (and you're using something about 5 years old!), so just ignore the generated code for now. Under Linux, try typing "TServerWizard" and if you're lucky the script will run.

As Properties, let's add our old favorite "Sine" as a property which can return 1024 float values with a range from -100 to 100 (choose your favorite units).

Also add a property "Amplitude" which returns 1 float value between 0 and 500 (same units).

Finally add a property "Temperature" which return 100 float values (choose 'C as units) with a range from 0 to 100.

Note:

In the Server wizard, the format type "Single" is a "float".

Don't worry about "history" or "device names" or "alarms" just yet.

The Above example has used the exported device server name "WKSineGen" instead of "MYSINE", just as your case will also have some other 'unique' name. Click "Done" on the wizard. It should produce an exports.csv file in the working directory indicated in the upper right hand corner (probably a folder in your home directory).

Find your platform

Copy this file into your FEC_HOME directory. We're now ready to actually start doing something. But what we do will depend on what platform you have chosen for your buffered server.

C Programmers will want to go here.

VB Programmers will want to go here.

LabView Programmers will want to go here.

Java Programmers will want to go here.

Proceed to the Standard Server

Take your time going through all of the steps highlighted for your platform. When you have finished you should procede to the C Standard Server or the VB Standard Server