VB Programmers:
A "do-nothing" server
Start Visual Basic and choose a "Standard EXE" project.
You should see a brand new project with form1 staring you in the face. Before you begin adding code, you'll need to add tine.bas module to the project. In the Project Explorer, right-click on the Project (probably still named "Project1") and select Add -> Add File. Browse to Z:\Projects\Service\Vb\Forms and select tine.bas from the list.
Double click on form1 and you will be able to add code to the form_load() routine of form1.
To run your server you'll need to 'attach' it to your database files, so add the following line of code to the form_load() routine:
AttachServer "MYSINE", "", 0
Now run your server.
You might have noticed something important right away. The device server "Export Name" appears again in this code snippet. This must be the name (case sensitive !) as appears inside of the exports.csv file (and if you're following this tutorial by the letter, also in fecid.csv). If this isn't the case, the server will not find itself in the local database and it will not initialize correctly. As noted earlier, the fecid.csv does not have to even have a column called "Export_name", but if it's there it has to match. This call to 'Attach' inside the above code snippet is a more serious violation of the "A name belongs in one place only" ansatz of a configuration database. In the case of the standard tine server, this violation does not appear, since the standard server does not 'attach' to a database. However this is a small price to pay for an enormous simplification in the server API. And starting with the buffered server will help us understand more of the tine features early on, without having to plough through arcane configuration API calls.
Check the Log file (please !)
Before rushing to the Instant Client, have a look at the server's log file. This will be called 'fec.log' and should be located in c:\tine\log (if that's where FECLOG is pointing to!), or directly in the working area, if there's no FECLOG environment.
Near the end of the log file you should see a message saying that your equipment module was "registered with equipment name server". If you see this then everything went reasonably well so far.
Browsing your server
Now try to find your server in the Instant Client under the context name you assigned. You will more than likely need to click on the "Reload Names" menu item under options (if the context itself is new) or at a minimum open up and close again the context combo box (this will force a reload of the names under the given context).
You should see your device server and be able to browse the properties and devices you entered in the setup wizard.
You should be able to read a lot of '0' values (not very interesting).
A "do-something" server
So let's give the properties something to read back. In VB, you can accomplish this by putting some global variables in a new .bas Module. So please add a new .bas Module (you'll see why we need to have a new .bas module in a moment). and add
to the new .bas Module.
To Form_load add:
Now restart your server and see that the properties return something. This is because you have 'pushed' something (namely the data we prepared in our global arrays) into the property buffers.
Making your server dynamic
The data returned from the server are now static, initialized in form_load and that was it. This is probably okay for 'Amplitude' but 'Sine' and 'Amplitude' correspond to quantities that we might be reading out of our hardware, so let's simulate hardware readout by adding so dynamic jitter to both 'Sine' and 'Amplitude'.
In VB, you can use a VB timer to simulate your io. Add a Timer to your form1, set it up to be called every 1000 msecs, and set it to be initially disabled, and include the following code in the timer routine:
In form_load enable the timer after (!) you have called AttachServer().
Now if you restart your server, you should see some jitter at 1 Hz. Try making it update faster by decreasing the polling interval to 500 or even 200 msecs. When you poll in the InstantClient you can also change the default polling rate to 500 or 200 as well.
Adding device names
Unless you thought in advance while using the server wizard, there are probably no device names registered. The instant client will just show a "#0" as a device name. You can re-visit the wizard and enter "100" for the "Number of Devices" (in the device server information frame).
After entering this number, click on the Property Name field, that will signal the wizard to fill in the Device Panel with some device names ("Device 0", "Device 1", etc.) which you can either just leave as it is, or provide some of your favorites.
Also let's specify what kind of array property "Amplitude" and "Sine" are.
Click on Property "Sine" in the display panel on the right hand side, so that all of the text and combo boxes are filled with it's parameters. Now for "Output Array Type" choose "SPECTRUM". And click on the "Edit" button on the right (If you try to "Add" this property, you'll get a message telling you it is already there, but you can edit it!). Click on property "Amplitude" on the property display panel and choose array type "CHANNEL". And then click on "Edit" again.
When you're finished, click on "Done" once more.
If you have a look at the new generated "exports.csv" file, you should see that the number of modules is now 100, and the format type for property "Sine" is now float.SPECTRUM and for property "Amplitude" float.CHANNEL.
Channel versus Spectrum Arrays
Copy this new exports.csv into your FEC_HOME database area and restart your server.
Now when you browse for it with the instant client, you should notice that when you click on property "Sine" the display type automatically changes to "PolyLine", i.e. a SPECTRUM data type automatically gets displayed as a trace.
- Note
- you should open up and close the Device Server Combo Box on the instant client, before you re-browse for your server. The reason is that the instant client will cache the property information for a server and not know about the array type changes you just made unless you force it to re-acquire this information.
Click on the "Amplitude" property. The display type automatically changes to "Histogram", i.e. CHANNEL array data generally refer to an array where each element refers to value of the property for a particular channel. And this is best displayed as a histogram.
If you make the instant client read the Amplitude, you will also see that the x-axis label also includes the device names and the element positions.
- Note
- When a property returns a spectrum array (also known as a waveform or trace), it usually has x-axis units as well as y-axis units. (Voltage versus time for instance). The Wizard currently doesn't have room for x-axis units, but you can add it by hand by editing the export.csv file yourself. You need to find the description of the property in question (for instance "Sine" in our case). And instead of "[-100:100 V]Sine Curve", you would expand it to read for instance "[-100:100 V][-100:900 usec]Sine Curve". A client program reading this information would then know how to position the min and max settings for the horizontal axis as well as what the x-axis units are. HOWEVER: only make these kinds of changes when you're finished using the server wizard, otherwise you'll have to copy-and-paste them back in.
Before leaving the server wizard, let's have a look at local history files (followd by alarm files). Use the wizard to call up your database again and select the Amplitude property. Now check the "Keep History" check box, followed by clicking the "Edit" button and then the "Done" Button. You can also edit the history panel if you wish. The default settings should be good enough for our demonstation purposes.
Local histories
You should have generated a "history.csv" file, which you can now copy to your FEC_HOME area as well. Now restart your server and have a look at the log file. It should now tell you that it is keeping a history of "Amplitude". If you re-browse your server in the Instant Client, you should see a "history" check box appear, which will let you trivially check the history of the selected device. A better way to see what is going on, is to add by hand ".HIST" to the property name in the combo box (make sure the history check box is NOT checked), and then hit the read button. Without any further input the local history server will ask for history data starting from "now" minus the depth in seconds given by the data size in the request. You can also have some fun by repeating the call with a format type of "FLTINT" which will return an array of data-timestamp pairs.
If you want to hava sneek preview of the local history viewer, you can call it up and under "Options" choose "Data Sources" and then choose the "Local History Chooser". You can then navigate via the Context combo box to the "WORKSHOP" context and find your server. It should display everything you are keeping a local history of. Choose one of your properties and devices and the click on "Add Selection".
Local Alarm Server
Now let's have a look at the local alarm system. A tine server can automatically set threshold alarms for you if you provide an alarm watch file. Let's see how this works. Start the wizard again, select "Amplitude" and check the "Alarm Watch" check box. You should change some of the settings in the alarm watch panel, namely the "Value too high" Threshold, you can set to 24, with a warning at 22 and the "Value too low" threshold to 16, with a warning at 18. Click the "Edit" button and then the "Done" button.
A tine server can also set 'invalid data' alarms for you if you like. In the alarm watch panel, instead of providing threshold settings, you could provide a 'normal' value (which a property should have) along with a 'mask'. This category of alarms generally applies to 'status' data (typically integer values) where a mask is applied to the data read and the result is compared against a 'normal' setting. If the data read doesn't match an 'invalid data' alarm is set. Other categories of alarms require the use of the tine local alarm server API.
You should now have generated an "almwatch.csv" file. Have a look at this file (if you like) and copy it into your FEC_HOME area and restart your server.
You can check the alarms on your server via the instant client, by including the "Stock Properties" in the property list. The relevant properties are "NALARMS" (number of alarms as a 5-parameter snapshot - when the first number > 0 then you have local alarms) and "ALARMS", which will return the current local alarm list (you might want to ask for fewer then the default 512 alarms).
Another simple way to view the alarms is to start the Remote Fec Control panel, find your server and click on the Alarms tab.
Commands (changing settings)
Now let's see how we can set the amplitude. So far we can only read it. Use the server wizard to make sure that the "Amplitude" property is a READ/WRITE property. Click on the "Amplitude" property in the right-hand side display, change the access to READ/WRITE and make sure the input parameters allow 1 float (Single) values to be sent. Click on "Edit" and then on "Done". Copy the new exports.csv file into the FEC_HOME area.
We're not through! Now a client will send us data, so we have to examine what was sent, decide whether to use it or not and then return.
Add the following subroutine to that extra module you added to the project:
Then add the following line in form_load:
The "AddressOf" function only works on Sub routines inside their own .bas Module.
The callback routine will let you pull the data sent to your server into the application and examine it if you wish before you accept the new setting. You should push the data back into the readback befores so that callers will be able to read the new setting as well.
Property Scheduling
You may be wondering what the final "0" refers to in calls to pushBufferedData.
This is a scheduling flag. If you pass "TRUE" here, it calls the TINE scheduler, which has the effect of notifiying all clients listening to the property in question immediately. That is, NO LATENCY.
To test this, change one of the pushBufferedData calls to pass TRUE. In LabView, this is an optional input to the push VIs.
Now recompile and restart your server and poll the property in question with the Instant Client, BUT .... pull it with a polling interval of 30000 msec. Ordinarily, you wouldn't expect data updates any faster than once every 30 sec. But you'll be updating whenever the value changes at the server, no matter what! Scheduling a property is sometimes a very useful way to ensure a display update on the client side as soon as an important data change has occured.
device-oriented versus property-oriented
Most classic device servers have many instances (devices) and each device supports the same set of properties. Many servers however are more "property-oriented" than not. Still others are more "device-oriented" than not.
Property-oriented would mean that each property potentially has a completely different set of devices. This is typical of middle-layer gateway servers, where there might be a property "VacPressure" and a property "Orbit-X". The getter pumps in the one case have nothing to do with the bpm monitors in the other.
The wizard is capable of setting up this kind of behavior in the configuration database. That is the purpose behind the Server or Property option button in the device panel. The default is "Server-oriented" device lists, where the devices given are valid for all properties on the server. If you select "Property", then a separate list is made specifically for the property in question. If you try this, you will generate an addition .csv file with the name <Property>-names.csv. In our case, "Amplitude" might be such a property, so you would generate a Amplitude-names.csv. (Of course if everything is called "Device 0", etc. you won't see the difference.
Device-oriented would mean that the device server supports all devices listed, but some devices might have a different property set than others. The wizard is not capable of setting up the Device-Oriented behavior, but you can add it yourself (fairly) easily.
You need to modify your <eqpmod>-devices.csv file. For instance, if this is called MYSEQM-devices.csv, it might look like:
You need to add by hand another column called PROPERTY_LIST. If the device in question deviates from the default property list (all registered properties), then you need to supply a file name (your choice) for the entry in this column. For instance, let's say that "Device 3" only supports property "Amplitude". Then you would have:
- Note
- The above editing might be easier in Excel.
Then you need to create the file called Device3-properties.csv. This is a .csv file with one important column, namely "PROPERTY_NAME".
So you would have
And that would be that.
- Note
- You can't do both! Your server is going to be classic (one device list, one property list) or it is either device oriented or property oriented.
Once again, when you start editing the .csv files yourself, you'll probably want to stop using the wizard (or else get used to copy-and-paste).
Redirection
It's time to try Redirection. The wizard doesn't offer this, but you can do it again by hand.
Often it is the case that a server will offer a property which lives on another server, or a device which lives on another server.
Let's look at the device case first. Suppose you want to redirect any request involving Device 1 to your neigbor's server. Ask your neighbor what his server is called. Open up the <eqpmod>-devices.csv file and add a column called REDIRECTION and leave all the entries in this column blank except for the row corresponding to Device 1. In this row, put your neighbor's server. For example, if his server is called "MYNEIGHBORSERVER",you might have:
Copy this new -devices.csv file to your FEC_HOME area and restart your server. When you (re)browse your server and access Device 2, your call will be redirected to MYNEIGHBORSERVER.
ONE IMPORTANT THING: If the "MYNEIGHBORSERVER" Server isn't running or doesn't have a device namded "Device 2" or a property equal to one you're trying to access then you will get an error code returned.
Redirecting a client's contract to another server is in some cases very useful. A client program can thus be written to address devices and properties as if they are available on a single server when in reality they are distributed among many servers.
On to the Standard Server
We're finished with Buffered Servers, which maybe illustrate just how far you can get with databases alone. Sometimes you might already have a different database structure or more complicated needs, So you should now move on to the generated servers.
