Getting Started

Setup

There is currently no set of platform-specific setup executables capable of providing a working TINE installation on the designated platform. The 'shrink-wrapping' of TINE for the various supported platforms will improve with time. In the mean time, there are none the less install scripts which do a good job of installing TINE on Windows platforms and linux plaftorms. We will describe these below as well as provide all information necessary to insure that an installation by hand will function properly.

You might wish to first visit Quick Tutorial (Windows) if your target platform is a windows (XP) host or Quick Tutorial (UNIX/Linux) if your target platform is a linux host. These quick tutorials provide step-by-step instructions for getting going on these platforms.

On a Windows platform you should download and run the 'Windows Setup Installer' setup.exe (use the Daily Build if you want the absolute most up-to-date distribution). This will allow you to choose and install the specific libraries for you favorite development environments, including LabView, MatLab, Python, Java, etc. On other platforms, you should download and unzip and untar the relevant tar ball for your chosen platform. In the 'tine' directory you will find a 'setup' script that will build all relevant tine libraries. Note: on Linux you should run 'setup64' if you have a 64-bit version of Linux.

In the discussions which follow, frequent mention will be made of the environment variable TINE_HOME and its relationship to the TINE Equipment Name Server (ENS). Namely, this environment variable points to a repository on the local file system. A single file called cshosts.csv contains the address(es) of the configured TINE equipment name servers. This same repository can also be used as a local cache of TINE server addresses in case there is no running ENS. However, one of the first things you will want to do is decide where the TINE ENS(es) should run, and note their IP addresses. A frequent choice is to run the ENS on a linux machine, although Solaris and Windows are also used. If windows is chosen, there is a Windows 32-bit ENS service or console program which is already compiled and ready to use. On linux or unix, you will first have to build it on the machine you have decided upon. However, this is easy and happens automatically when you run the makeall script from the "servers" directory after you've un-tarred the download file.

Note

There are several strategies for running an ENS (or not). The most common for a TINE site is to run two instances of the ENS (a primary and a secondary) on different hosts. Then in case the primary ENS is unexpectedly unreachable, the secondary will still provide naming services. If you are simply 'trying things out', you will likely be running a single instance on the 'local host'. This is fine. Be aware that the ENS will always make use of TINE 'port offset' = '0'. So any other servers running on the same host will have to use non-zero port offsets. The ENS maintains the address database for all servers including itself! The ENS is therefore 'trained' to self-correct its own entry. Where the ENS is running under exotic circumstances such as under VMWare or on a host with multiple ethernet cards or addresses, it might be necessary to make use of the 'myaddr.csv' file to target a specific IP address.

Windows NT, 2K, XP, Vista, Win7 Win8, Win10

What does setup.exe do?

• It will allow you to choose whether you want a private installation for the logged in user or not. This is in fact the default, whereby all relevant DLLs etc. will be copied into the .\AppData\Local\tine directory of the local user. This location will then be 'subst'ituted as the local drive 'L:', and 'L:\System32' will be appended to the user's path. Note that all the 64-bit DLLs are also placed in the 'System32' directory (a la Windows).
• Some legacy 32-bit applications are provided, and these make use of ActiveX controls. Hence these ActiveX controls are also registered.
• If 'java' applications were 'checked' in the installation process (a very good idea) then both the java and native windows applcations will appear in the Windows 'Start' shortcuts.
• It provides a cshosts.csv the database subdirectory and sets the 'TINE_HOME' environment variable to point to this location:
  
  TINE_HOME = L:\database\
  
  IMPORTANT: The entries in the cshosts.csv from the TINE distribution point to equipment name servers at DESY. You must edit this file to contain the IP Address(es) of your equipment name servers, once they are known.

Windows 95, 98

Here you should make use of the '32-bit Windows and Resourceds' .ZIP File. Download and unzip this file and run the setup32.bat file. This will parallel the actions taken in the discusion of the 'setup.exe' installation above, except that this will be a Windows only (no java, LabView, Python, etc.) installation. The Dlls and OCXes used in setup32.bat work fine in Windows 95 or 98, and the setup install script works in spirit but not in practice. Namely, ROBOCOPY.EXE and SETX.EXE do not work here. This batch setup will have to be copied and modified for windows 95 or 98 such that xcopy is used in place of ROBOCOPY and the system envrionement variables are set in autoexec.bat.

• Finally, you need to ensure that the latest patches and service packs for WIndows 95 and 98 are installed. Make sure that scr55en.exe, dcom95.exe have been applied.

Windows 3.1, 3.11

In the TINE distribution there is a node kernel\windows. In this directory there is an install script setup16.bat which should install the appropriate DLLs and VBXes on the target machine based on the contents of the TINE distribution, and assuming that the working directory is the directory containing setup16.bat.
You can have a look inside the batch files and change the directory structures, etc. once you know what needs to go where.

What does setup16.bat do?

• It copies all control DLLs and VBXes from .\dll16 to the Windows system directory.
• It creates a directory tine on the system drive. For the sake of argument, let's say that this is drive c:. Thus the directory 'c:\tine' will be created. In addition, it creates the directories 'c:\tine\database', and 'c:\tine\bin'.
• It copies cshosts.csv from the database node of the TINE distribution into the 'c:\tine\database' directory. You MUST set the environment variable
  
  set TINE_HOME=c:\tine\database\
  
  in the autoexec.bat of the local machine.
  IMPORTANT: The entries in the cshosts.csv from the TINE distribution point to equipment name servers at DESY. You must edit this file to contain the IP Address(es) of your equipment name servers, once they are known.
• It copies the 16-bit 'Instant Client' to 'c:\tine\bin\client'
• It starts the Instant Client. Note that in Windows 3.1, all applications share the same address space and in particular, all control applications share the same network resources. Thus is very IMPORTANT that the first control application to load a controls DLL (such as tinecl16.dll or tinesv16.dll) remain resident throughout the windows session, or in an 'emergency' to be the last control application to be removed.

The important aspects of the Windows installation are that 1) the local control database directory is fixed and that an environment variable TINE_HOME exists and points to this directory. This directory should have at least one file called 'cshosts.csv' and this file should contain the address(es) of the equipment name server(s). This is loosely analogous to specifying the address of the DNS on a given workstation. 2) The TINE DLLs and VBXes from the service\dll16 node are copied to a location on the path.

Linux

Linux comes in many flavors, each with its own administration strategy. You can download the Debian Linux package for the TINE Web page and use it with Debian Linux. Otherwise you should download the Linux Source zip file (tineLinux.tar.gz). If unzipped and untarred, this will create a directory called 'tine'. In this directory is a 'setup' script which should make the tine libraries (both static and shared libraries) as well as various command line tools for your system.

The 'setup' script is designed to make libraries for 32-bit linux. If you have a 64-bit linux OS, then you should use setup64 instead.

After running this script, you can either become root or use sudo to run the 'installAsRoot' script, which will copy libtine.a and libtinemt.a into /usr/lib and all tine include files into /usr/include/tine as well as the command line tools into /usr/bin.

You can then enter the servers directory and run the makeall script. This should compile and link all of the central servers found in the servers subdirectory.

What is NOT done is the copying of a valid 'cshosts.csv' into /usr/etc/tine which is the standard location for this file. After you decide on a machine (or machines) where to run the ENS(es), you should prepare a valid version of this file (by simply editing the example copy in the linux/database directory) and copy it into the /usr/etc/tine directory.

Depending on what shell you use you will need to see to it that the environment variable 'TINE_HOME' is set to '/usr/etc/tine'. If crontab is used to run tine servers (or clients) in the background, make sure this variable is likewise set for crontab as well. As an alternative, you can make sure a local copy of cshosts.csv is distributed with each of the tine servers, etc.

Otherwise, see the instructions for a generalized Unix installation below.

MAC OS X

An installation of TINE on a MAC parallels that of Linux or any other Unix like system.
The tools and libraries are NOT pre-compiled. So you will have to have installed a C compiler on your MAC in order to run the 'setup' script, which you will find upon unzipping and untarring the tineMac.tar.gz download package.

Solaris

The solaris install parallels the instructions for the Linux install and won't be repeated here. We note however, that the scripts and make files present in the Solaris zip file (tineSolaris.tar.gz) use the gnu c compiler. You can use the Solaris CC compiler is you like. If so, it is convenient to force a C++ compile of the tine libraries and applications by adding the line #define FORCE_CPP inside the project.def file found in the source directory.

Unix

The standard TINE install for Unix consists of installing the TINE libraries and include files for development purposes, defining the database repository for important files such as 'cshosts.csv' and setting the TINE_HOME environment variable to point to this location. The command line tools are also installed on the path.

You should download the tine source modules. You will have a source directory as well as specific platform subdirectories. Let's assume your target platform is HP.

This is itemized below:

• Build the relevant tine libraries for the Unix platform in question.
  • Decide on a build directory on the target platform and copy all files from the source node into this directory. For the sake of argument lets say this is ~/tinebuild/. You should copy all files from the source node to ~/tinebuild/. Then copy all files from the source/platform/<platform> node to ~/tinebuild/, (e.g. from source/platform/HP).
  • The files in the platform sub-nodes contain the 'project.def' file for the platform in question, plus assorted make files. You should begin by building the TINE library(ies). Use
    • make -f libtine.mak \t\t to make the standard tine library.
    • make -f libtineg.mak \t\t to make the standard tine library with debug symbol tables.
    • make -f libtinex.mak \t\t to make the extended tine library with ipx functionality.
    • make -f libtinexg.mak \t\t to make the extended tine library with ipx functionality and debug symbol tables.
    • make -f libtinemt.mak \t\t to make the standard tine library with multi-threaded background tasks.
    • make -f libtinemtg.mak \t\t to make the standard tine library with multi-threaded background tasks and debug symbol tables.
  • Build the attachfec access program by using
    • make -f attachfec.mak
  • Build the command line client tools by using
    • make -f clntools.mak
• copy the library files to /usr/lib; the *.h and *.def files to /usr/include/tine; and the client tools to /usr/bin
  • cp *.a /usr/lib
  • mkdir /usr/include/tine
  • cp *.h /usr/include/tine
  • cp *.def /usr/include/tine
  • cp tget tmonitor tinfo tservers tprops tdevs tdevlist thistory /usr/bin
• Make the directory /usr/etc/tine and copy the relevant .csv files from the database node to this directory, in particular the file cshosts.csv should be copied here.
  • mkdir /usr/etc/tine
  • cp <tine distribution>/database/* /usr/etc/tine
• set the environment variable TINE_HOME so that it points to the above directory
  • e.g. put 'export TINE_HOME=/usr/etc/tine' in .bash_profile for the bash shell

Development

After the tools, libraries, and environment have been successfully installed, you can begin developing control system applications. Primarily, applications falls into one of two general categories. Namely, the application is either a 'server', which has a system-known identity, exists only once at a system-known address, and offers services in the form of device names and properties. Or the application is a 'client', which does not have a system-known address or identitiy and makes use of the services offered by the servers in the control system.

Servers usually run 'all the time' as a process on a computer 'somewhere' and seldem have any GUI requirements. On most platforms a server is a background processes. TINE does offer a user interface to the server for those occassions, where direct interaction with a running server is necessary.

Clients usually run when someone starts the application. An execption to this are 'middle layer' servers which are servers in the own right, but must have client access to other running servers, for example archive servers or alarm servers. Otherwise, 'user' application programs which access the control system are clients. Such applications usually have extensive GUI requirements, as they must deal in offering the possible access points a server might have in some reasonable manner and they must deal in general in fulfulling the control system user's immediate wishes.

TINE Server Wizard

A good way to begin writing a server application is by using the TINE Server Wizard. This is a simply program which will let you input the general behavior your are asking from your server. That is you should decide on what device server name your server should have and what properties your server should export, including details such as input and output data size and format, engineering units, value ranges, etc. You can also indicate whether the server should maintain a local history of a particular property. In the Windows distribution, the windows\apps32\FecSetup\bin directory contains a Windows program called fecsetup.exe (In the Linux distribution, there should be a Visual TCL Script tine/bin/fecwiz.tcl). These can be used to set up the FEC environment according to yor wishes.
Basically this create an appropriate 'fecid.csv' file according to your input specifications and set the environment variable 'FEC_HOME' to point to the appropriate locations. No code generation occurs here. This is basically a trivial action and if you know what you're doing and want to create or append the fecid.csv file yourself or if you intend on setting the FECNAME via an API call, then you can ignore this step (unless you want to create the FEC_HOME environment variable via this application).

Likewise, the windows file windows\apps32\ServerSetup\bin directory contains a program called srvsetup.exe ( tine/bin/srvwiz.tcl on Linux). By using this tool you will see a panel where you can supply the server name for the device server you wish to generate, as well as the Properties you wish to export and their general behavior (data size and format, engineering units, maximium and minimum set points, etc.). When you are finished specifying the properties and their behavior, you can indicate whether you wish to generate a Visual Basic (Windows GUI) server or a C (Console) server. The appropriate code to provide a working server will then be generated by the server wizard in the directory you specify. Please refer to the section on the TINE Server Wizard for more options you can supply. This program generates a number of startup configuration files according to your specifications. You can forgo generating a C or VB server application and click on the 'DONE' button. This will create the database files but not generate code. This step is not the less extremely useful for running 'buffered' servers (see TINE Buffered Server). Namely, this is a very good first step toward generating a LabView Server.

In order for srvsetup.exe to generate code, you will need to provide the generator programs vbsrvwiz.exe and csrvwiz.exe on the path, as these programs will be shelled after you finish setting up the server behavior. On Unix, you will need to provide the csrvwiz binary on the path. You will also need to generate this for your platform. The code module srvwizard.c can be found in the 'source' area and the Make-file which generates the wizard is found in the platform directory (e.g. source/platform/linux/wizard.mak).

Note that the generated code will (can) only supply simulated data behind the exported properties. There are a number of 'TODO' comments at strategic locations which indicate where you should supply real data coming from your hardware, etc.

Also note that the Make-file generated for a console build assumes a Linux build with the TINE libraries and include files in the suggested locations (/usr/lib and /usr/include/tine). You might have to adjust some of the parameters to suite your needs.

Finally, the code generated by the server wizard should by regarded as a 'template' which you can use to further the development of your server. Issues of hardware timing, synchronization, etc. can only be dealt with by you, the developer. At the time of this writing, the server wizard is a 'one-pass' wizard, which means that if you run it again in the same location, it will re-read the server's behavior input previously (by re-reading the 'exports.csv' file), but will not remember any changes to the generated code you might have made and will simply re-generate the code modules again.

Server Development

A FEC, that is, a front end controller (or rather front end process), consists of a TINE engine which can manage many device servers, within the same address space. These can be either single or multi-threaded, but are contained within one process. For some operating systems (Win32, Unix, MAC, VMS) you can have more the one FEC running on the same computer, hence 'front end process' is a more apt description even if 'FEC' is the term of choice.

Find the FEC setup program from the distribution windows\apps32\FecSetup\bin\fecsetup.exe and run it on a Windows machine.
The setup program will query the TINE ENS for the currently available contexts and subsystems fill in the appropriate combo boxes. If you wish to use an as yet undefined context or subsystem, just type in the name. The FEC setup program will offer the context "TEST" and subsystem "TST" by default. Input "MYSERVER" for the Exported Device Server Name field and "MYFEC" for the Fec Name field so that the panel looks something like:

If you really want the initialized server to latch onto the export name "MYSERVER" click on the 'Add' button. (Do this). The FEC Setup program will also determine whether the local environment variable 'FEC_HOME' has been set or not. If not it will set it for you if you check the 'set FEC_HOME' check box. (Do this if it has not been set). Then click 'Done'. Verify that an environment variable 'FEC_HOME' now exists and points to a directory 'c:\database\'. Furthermore, this directory should now exist and contain the file 'fecid.csv'. If the directory 'c:\database\' is not a suitable location, you can set this variable to some other preferred location where the local database files should be maintained.

Note that by specifying an 'exported device server name' you are allowing for the possibility of having multiple server processes on the same computer and using the same fecid.csv file. In this case, if a server needs to locate its FEC name from the fecid.csv file, it can only do so by finding its exported device server name in the list. An alternative is to either forgo the environment variable FEC_HOME entirely so that the fecid.csv must reside in the working directory of the server executable, or set the environment variable to point to different locations via a shell script which starts the server, or to set the device server's FEC name via an API call.

Device servers consist of equipment modules, and an equipment module needs to be registered with the TINE engine in order to provide its services. See RegisterEquipmentModule(). The device server will be recognized over the net by all clients via an "Export" name. Internally, a device server does not make use of this name at all, but instead uses the local name of the equipment module. Indeed the equipment module is identified in the TINE engine by this local name and many of the C-interface routines take this local name as an input. (In an object oriented interface (see java, .NET interfaces), where the interface routines are methods of a class, the local name would not be visible to the developer at all).
The Export name is usually assigned to an equipment module via the local database file exports.csv. Thus it's an easy matter to run the same server at several locations each with a different Export name. It is of course also possible to supply the Export name via the API call to register the equipment module. If you do so and your server runs on more than one station then you might need to take other steps to decide which Export name to use (remember, there can only be one Export name registered with the equipment name server). For instance and command line argument could provide the Export name or another file besides exports.csv, etc.

Find the Server setup program from the distribution service\ServerSetup\srvsetup.exe and run in on Windows. Enter "MYSERVER" for the Export Name, "100" for the number of devices and choose a directory where you would like your project to be generated. Then type in a new property "SINE" for property, give a description, units, maximum and minimum values, choose the output data type as "Single" (i.e. float). Now click the "Add" button and you should see this property appended to the list of Properties. For the time being, let's stop right here, so decide whether you want to work with a "C" project or a "Visual Basic" project and click "Done".

The panel should look something like the following (it will disapear after you hit the "Done" button):

When you click on the 'Done' button, the setup wizard will ask you if you would like a copy of all configuration files in your FEC_HOME repository. Say 'Yes' to this dialog. If you answer 'No', all generated configruation files will be in your project directory. You can copy them by hand to FEC_HOME if you want. Otherwise these files are used for the code generation wizard, even if you don't intend on using them. Have a look at the project and code generated in the directory you indicated. This should compile and run. However, the property "SINE" does not deliver a sine curve at all. Instead it just sends an array of random numbers between the maximum and minimum end points you input. As a first task to get your feet wet, edit the code to make property "SINE" indeed return a sine curve. This will involve finding the background function and editing the code at that point.

The template code generated by the server wizard supplies many of the checks and balances you might otherwise forget if you're in a hurry. For instance, when a particular property is accessed, the proper bounds checking, range checking, access checking, etc. is pre-coded and the appropriate error code is returned if there is an error condition. Likewise format conversion, array-wrapping, etc. is also provided. Designating a property to behave in a certain way, for instance to automatically include 'save and restore' logic, can easily be post-facto indluced by adjusting the assigned access parameters during registration (see RegisterPropertyInformation() or the discusion of exports.csv in the Configuration Files section.

There are, however, a number of ways to 'write a server' and these depend on your specific needs and wishes.

For instance, whether your servers provides 'device names' is entirely up to you as is what the device names are. Note that 'device name' refers to a specific instance of a device managed by your server (some refer to this as a 'location'). You might have a BPM device server managing 300 different BPM modules. In this case a device name is the name of one of the BPM modules. Other servers might have only one 'instance' namely the device server itself. For example a beam current monitor. In this case, it might seem superfluous to supply a device name, and a TINE server can work just fine without it. Nevertheless, it is advisable even in such cases to supply a single device name (for instance "MONITOR"). For one thing, it is aesthetically pleasing to see a query for device names to return with a name and not a number (note that all devices have a default representation using #<number>). For another it is in generally good practice to provide all servers with the same functionality and supplying device names by practice will protect your coding efforts against the day when supplying device names is no longer optional but required. Device names can either be registered via API call (RegisterDeviceName()) or by supplying a local database file <local name>-devices.csv containing a list.

Having said all of that regarding device names, we should point out that this covers the simplified generic case where a device server is composed of a set of identical instances all having the same properties. Indeed, most servers follow this ansatz. However, this is not necessarily true in general. In such cases, a particular device might have a different property list as another. We'll cover this case below. In other cases, a particular property might have a completely different device list as another property. This is true for instance of middle layer servers such as archive servers where an archived property such as "VacuumPressure" will have a completely different set of devices as an archived property "Orbit".
To handle such non-trivial cases, it is the server's duty to supply a registered property <Property>.NAM for each property requiring an independent list and returning a list of NAME16 entities, for instance "VacuumPressure.NAM" and "HorizOrbit.NAM".

The registration of a device server's equipment module must provide the local name under which the equipment module is to be addressed by the TINE engine. It must also provide a reference to the equipment module function handler (the equipment function) which is called by the TINE engine schedule when a property needs to be accessed. This routine is of paramount importance as it essentially defines the behavior of each property. Equipment module registration can also provide references to an initialization routine, an exit routine, and a background task plus scheduling rate. The background task can either run as a separate thread (where threads are available) or within the equipment module's thread in a cooperative 'multi-tasking' sort of way. The usage of any of the initialization, exit, or background routines is entirely optional, although frequently very useful. You can also supply the Equipment module's Export name with the registration call, although it is usually more desireable to make use of a local exports.csv file for this purpose.

In most examples found through this documentation, the paradigm of including an infinite for-loop surrounding a call to SystemCycle() is maintained. This does in fact constitute the TINE engine, and this cycler must in fact be running. However, multi-threaded builds also have the option of launching an independent thread where this cycler activity occurs (see SystemStartCycleTimer()). In fact when one makes use of shared libraries, this thread is generally launched automatically. Note, that in such cases, any additional cyclic activities must occur elsewhere.

It is the duty of the assigned equipment function to respond to Property requests. TINE Properties can be thought of as 'methods' in the object-oriented sense, meaning that device server Properties involving reading and writing attribute data are properties with get/set methods where the read or write access can be ascertained and responded to. Properties involving a more complicated calling interface should cleary be regarded as method calls. For instance an orbit server is likely to be a property server (as opposed to a device server) and take complicated input (likely a structure) and return complicated output (likely another structure). Other properties not involving data (e.g. "INIT", "TRIGGER", etc.) are clearly methods.

Device servers are required to register their exported Properties. This can be accomplished either via the exports.csv file or via explicit registration through the API call RegisterProperty() or RegisterPropertyInformation().

As mentioned above, there are cases where it cannot be assumed that all registered devices have the same property list, in which case simple Property registration will not suffice. In these cases, you can register a 'Property Query Function' by calling RegisterPropertyQueryFunction(). If you do so, you are then responsible for providing a function which will not only respond to property queries but will determine the validity of incoming Property calls.
A better alternative is to register all properties 'normally' using the TINE property registration API and to then 'assign' properties to relevant devices. This is accomplished by making use of the AssignPropertyList() call.

TINE also allows the alternative view, where a server's properties are paramount, and an individual property might have a different 'device' list than another property. This would correspond to a property server view (typical of services) as opposed to a device server view. In such cases, the use of the term device name is likely a misnomer, where the term keyword is much more apt. Making use of a call to AssignDeviceListToProperty() is an easy way to achieve this scenario.

All Properties you register either directly by using either exports.csv or the RegisterProperty() API call or indirectly by registering a Property Query Function are designated as 'user-defined' properties. They are, after all, the properties specific to the server you are writing. In addition, all TINE servers have a large set of so-called 'stock' Properties, which handle a number of client-side queries for the registered information or current activity and statistics.

All TINE servers have a built-in ready-to-use local alarm server and a local history server. Maintaining local histories of registered properties is as easy as supplying a history.csv file with the relevant information (there is also an API call to accomplish the same). See TINE Archive System. Certain types of alarms (namely value_too_high, etc.) can also be set by supplying an almwatch.csv file. Most kinds of alarms are best set by making use of the SetAlarm() family of API calls in your server code. See TINE Alarm System.

Client Development

(coming soon to a theather near you! will include:)

• asychronous vs. synchronous access
• access modes (SINGLE, TIMER, DATACHANGE, EVENT)
• best choice of polling intervals
• efficient access via NETWORK subscriptions (how to enforce at the server)
• notification tolerances
• grouping callback events
• data timestamps, data system stamps, data user stamps
• error handling + data with status
• quality of service (UDP, TCP, PIPE, MMF)
• Reference to Data Flow Tips