TINE Naming Conventions

Name Resolution

A TINE link endpoint is given unambiguously by its full device name and the requested property. The device name is a hierarchical combination of the Device Context, the Device Server or Group, and the targetted Device Name. The Device Property is the targetted action or characteristic of the device.

As of TINE Release 4.0 these names have the following length restrictions, which we show below for completeness:

Visible names:

• device context minimum 1 character and up to 32 characters long.
• device server minimum 1 character and up to 32 characters long.
• device name up to 64 characters are registered (and returned from device name queries). Up to 1024 characters can be transferred client to server (useful for sending e.g. device lists or long file name paths)
• device property minimum 1 character and up to 64 characters long.
• device subsystem minimum 1 character and up to 16 characters long. (not part of name space)

Hidden names:

• fec name minimum 1 character and up to 16 characters long. (must be site-wide unique)
• eqm name (equipment module name, sometimes refered to as 'local name') minimum 1 character and up to 6 characters long. (must only be process-wide unique).

The Device Context and Device Group/Server part of the data access will be resolved by the equipment name server (ENS). The client process will then cache the results of the name resolution for future calls. Essentially, the Device Context and Device Group/Server will get resolved to a specific instance of an equipment module on a specific FEC (including Network address and port). The ENS in general knows nothing about the Device Names and Device properties found on a device server. The execption is the Group Equipment Name Server (GENS) which does maintain a device list of the members of a group.

What is the difference between a Device Group and a Device Server?
A Device Server is a physical process managing a collection of devices on a Front End Controller (FEC).

A Device Group can be thought of as a logical (or virtual) Device Server in that is appears in API calls and browsing tools as though it were a standard device server.
In reality, a Device Group might point to a number of different Device Servers depending on the device requested.

A Device Server called "LLRF.CONTROLLER.1" will offer properties for a set of devices it controls.

A Device Group called "LLRF.CONTROLLER" might consist of the group member device servers "LLRF.CONTROLLER.1", "LLRF.CONTROLLER.2", "LLRF.CONTROLLER.3", etc. which are different physical device servers and could be residing on different host machines. Device Group "LLRF.CONTROLLER" is managed by the GENS and might appear to have a large number of devices.

The devices themselves are managed by Choosing a particular device on Device Group "LLRF.CONTROLLER". The GENS will redirect the call to the appropriate physical device server when the call is made. The redirection information is of coursed cached at the client.

TINE Data Acquisition APIs

There are several possible APIs which access TINE endpoints. Basically one is either acquiring or sending data as a synchronous transaction via an execute() method or as an asynchronous monitor via an attach() method, whereby the remote data is 'attached' to the data sets referenced in the API call.

The standard C and Java TINE APIs offer execute() and attach() methods (or ExecLink() and AttachLink() functions) which take two independent character strings providing the full device name and the device property. The Python API breaks the execute() method up into individual get() and set() methods along with an additional call() method (for non-attribute property access).

• C code example:

  #include "tine.h"
  ...
   
  float orbitx[141];
  DTYPE dout, din;
   
  ...
   
  dout.dFormat = CF_FLOAT;
  dout.dArrayLength = 131;
  dout.dTag[0] = 0;
  dout.data.fptr = orbitx;
   
  din.dFormat = CF_NULL;
  din.dArrayLenth = 0;
  din.dTag[0] = 0;
  din.data.vptr = NULL;
   
  // simple synchronous link:
  cc = ExecLink(“/HERA/BPM/WL167”, ”ORBIT.X", &dout, &din, CA_READ);
   
  ...
  // simple asynchronous link with callback:
  idOrbitX = AttachLink("/HERA/BPM/WL167", "ORBIT.X", &dout, &din, CA_READ, 1000, cbOrbit, CM_POLL);
   
  ...
   
   

• java code example :

   
    float[] orbitx = new float[141];
   
    TLink orblnk = new TLink("/HERA/BPM/WL167","ORBIT.X",new TDataType(orbitx),null,TAccess.CA_READ);
   
    // synchronous link with timeout of 100 msecs, retry the link on error
    orblnk.execute(100,true); 
   
    ...
   
    // asynchronous link with polling interval of 250 msecs, fire callback cbOrbit on data receipt or link error
    orblnk.attach(TMode.CM_POLL,cbOrbit,250); 

In these cases, the full device name is parsed according to the convention:

/<device context>/<device group>/<device name>

and the device property is provided as an independent parameter. In principle, both the Device Context and the Device Name are optional! If the device context is omitted, then the address resolution in force will simply look for any match of the device group/device server provided. [Release 4.0] If the result is ambiguous (because the server name shows up in more than one context) then an error code of 'ambiguous' will be returned to the caller.

If the device name is omitted, then an empty device name is passed to the targetted device server and property. In this case it is up to the device server to service the request or not.

It is strongly advised to always use the device context and device name in all data access!

Some APIs use a single string argument to specify the TINE endpoint, for example LabView.

Here the single string argument "\TEST\Sine\#0[MODE]" is parsed as

/<device context>/<device group>/<device name>[<device property>]

where the "[" and "]" clearly delineate the device property.

When TINE endpoints are accessed via DOOCS APIs or the connection parameters of the java ACOP beans, the string is parsed as

/<device context>/<device group>/<device name>/<device property>

That is, no brackets delineating the device property.

Finally, Command line APIs typically have separate arguments for the full device name and the device property.

Naming Style Guide

As noted above it is strongly advised to give every aspect of a TINE endpoint a name! This means supplying a context and device name in all cases.

In addition, the subsystem to which the device server belongs should also be supplied. This is not part of the name space but is often used as a filtering criterion when browsing the control system or otherwise offering a range of possible choices in an application. When a subsystem is not provided, a device server is assigned the subsystem "TEST" by the equipment name server.

In assigning names, note that the following conventions are commonly in play:

• The device context is typically provided in all upper case and usually descibes a facility or machine, infrastructure, or simply a context for a collection of device servers. Examples might be "HERA", "HERA.TEST", "HERA.CDI", "SERVICE", "TEST", etc.
  • illegal characters: '/' (slash), ',' (comma), white space characters.
  • avoid : '\' (back slash) It causes parsing problems in many APIs.
  • avoid : '_' (underscore) Use a '.' instead.
  • special : '.' Use a dot separator to decorate a previously assigned context in order to denote a related context. For example "HERA.TEST" (test device server relevant to "HERA") or "HERA.CDI" (CDI servers relevant to "HERA").
• The device server name is likewise usually given in all upper case and, as long as the context and subsystem are provided, does NOT need to repeat the context or subsystem in the name. For example "PBPM" (for proton Beam Position Monitors), but NOT "HEPBPM" or "DIAGPBPM".
  
  • illegal characters: '/' (slash), ',' (comma), white space characters.
  • avoid : '\' (back slash) It causes parsing problems in many APIs.
  • avoid : '_' (underscore) Use a '.' instead.
  • special : '.' Use a dot separator to decorate a previously assigned device server in order to denote an associated device server. Several generic servers make use of this automatically. For example "HISTORY.RPT" (repeater for the device server "HISTORY").
• The device name often refers to a location of a device or is simply the name of a channel or a tag (for instance "Bunch1" in the case of a bunch current monitor). A device server ALWAYS has at least one device. In the case were there is only one device, then in lieu of a better alternative, the Device Server name should be repeated as the device name. The device name is frequently given in CamelCase (please avoid the use of underscores "_") when applicable. For example "CavityRegulator" and not "CAVITY_REGULATOR". In many cases, systematically understood abbreviations are preferred and should be given in upper case. For example "WL167" instead of "WestLeft167" or "Wl167".
  • illegal characters: leading or trailing blanks, newline, tab.
  • avoid : '/','\' (back slash), ' ' (blank) They all cause parsing problems in many APIs. However, in many cases a '/' is frequently desired so as to 'extend' the device hierarchy. In such cases an equipment module handler will see this hierarchy and must be able to parse the incoming 'device name' accordingly. LIkewise, '/' or ' ' (a blank) are often desired, when the 'device name' actually represents a file path (which may contain slashes and spaces). In any case, the standard TINE application and parsing utilities are able to seperate the context and server name from the beginning of the full device string as well as the property from the end of the full device string. We mention only that other parsing tools might give unexpected results when slashes and blanks are used.
  • avoid : ',' (comma). Many servers (e.g. CDI servers) accept systematics where a device list is passed as the 'device name' where a ',' is used as the list separator.
  • avoid : '_' (underscore) Use CamelCase.
  • special : '.' Use a dot separator to form categories of devices. For example "WL94.left", "WL94.right", "WL94.top", "WL94.bottom".
• The device property is the name of an attribute or method for which the device server provides an action or response. In general, this always calls a handler at the device server and should be thought of as a "method", i.e. a "get" or "set" method when accessing an attribute. The property name should also be registered in CamelCase. For example, "Orbit.X" instead of "ORBIT.X", "AbsTemperatureNorth" and not "ABS_TEMP_NORTH", "Reset" and not "RESET", etc. Avoid using tautological prefixes such as "Rd" for "read" or "Wr" for "Write". Reading or writing a property is governed by the requested access to the property. For example a power supply has a current which can be read or written and should correspond to a single property. Do NOT prefix property names with "Rd", "Read", or "Get" for read-only properties or "Wr", "Write", or "Set" for write-only properties! This generally is a bad style and pollutes the property name space. Let the requested access indicate a read or write and process the request accordingly at the server. Attribute properties commonly allow read access and may or may not allow write access. The name of the property should indicate what the property is or what it does and not what read or write actions may be taken.
  • illegal characters: '/' (slash), white space characters.
  • avoid : '\' (back slash) It causes parsing problems in many APIs.
  • avoid : '_' (underscore) Use a '.' instead.
  • avoid : ',' (comma) It causes parsing problems and might interfere with other systematics.
  • special : '.' A dot + meta property tag is used when accessing meta properties. A meta property is a property of a property, for instance "Orbit.X.HIST" is the history of "Orbit.X" and "Orbit.X.NAM" are the device names associated with multichannel property "Orbit.X", etc. If you (either intentionaly or accidentally) make use of a meta property tag in your property name, this will have the effect of overriding the meta property handler, and the requested property will be passed on the the server's property handler. In addition, a '.' is often used to 'decorate' associated properties, e.g. 'Trace', 'Trace.INFO', 'Trace.XAXIS', 'Trace.SCHED'. In fact, it is good practice to denote those properties which are systematically scheduled by the addition of '.SCHED' and to supply an un-scheduled property without this decoration.

In most cases it is usually clear as to "what is a device" and "what is a property". A device name, as noted above, generally describes "where it is" or "what it's called", whereas a property describes "what it is" or "what it does". For instance "Voltage" or "Initialize" are properties. "Cavity", "Bunch1", "WL167" are devices.