The client and server interfaces for Python applications follow the Buffered Client and the Buffered Server paradigms. In addition, several utilities for browsing and for retrieving archived data, etc. are also available. These will be covered in the sections which follow.
Specifically these are:
- An overview of the Client API
- An overview of the available Browsing Utilities
- An overview of the available Archive Utilities
- An overview of the available Event Archive Utilities
- An overview of the Server API
Note that you should install the python tine library to the correct location for the python installed on your host machine. On a windows machine, make sure that PyTine.pyd is copied into the Python34\DLLs directory or possibly the Continuum\Anaconda3\DLLs directory. On Linux systems this will be a PyTine.so library (possibly PyTine.cpython-34m.so if you have an anacondo installation) and on MAC this will be a PyTine.dylib library. An up-to-date TINE installation on the relevant platform is also necessary.
Client API
On the client side, dedicated 'get' and 'set' calls generally allow for easy access to control system variables from python.
In their most basic forms, the calls appear to be 'transactional', which in fact they are for 'write' commands. 'get' calls generally start an asynchronous static listener (i.e. a local monitor) on the desired variable, which is then stored in a local buffer, thereby locally 'reflecting' the associated memory for the value(s) in question at the remote server. Thus, repeated 'get' calls merely retrieve the most recent updated value from the local buffer. The update rate can of course be influenced by the calling parameters. A 'get' call can likewise be constructed to in fact issue a synchronous transactional read request.
We shall expore these get calls in some detail below.
List of API Calls (details below)
- PyTine.get gets the current value of the target address and property.
- PyTine.stop_get will stop any underlying listening monitor associated with the given address and property.
- PyTine.set sets value of the target address and property
- PyTine.call will send the given input and retrieve the designated output to/from the target address and property in an atomic call.
- PyTine.attach monitors the current value of the target address and property and calls the assocated callable Python function when an update arrives.
- PyTine.detach detaches the monitor assocated with the given attached link handle.
PyTine.get (see also PyTine.attach)
With 'PyTine.get' you can access the current readback value of any targeted endpoint which contains readback data. If you import PyTine at the python command prompt and Simply type 'PyTine.get()' you will generate a syntax error exception, whose error message will remind you of the calling parameters.
One sees that the API support 'key-value' input and that there is are only two required arguments, namely the target 'address' and target 'property'. Actually if you provide the property in the target address (appended inside brackets) then you can make the call with a single parameter. That is address = '/TEST/SineServer/SineGen0[Sine]' will suffice, in lieu of address = '/TEST/SineServer/SineGen0', property = 'Sine', although the latter makes a clearer distinction between 'where' and 'what'. If you use a GUI variant, then helper text is also available:
The parameter description is given in more detail below:
- Parameters
-
address is the initial parameter and must be a string of the form /<context>/<server>/<device>. This essentially follows the TINE naming hierarchy. If NO other input parameters are given, the default 'read' data type and data size (for the target property as established by the targeted server) will be acquired. See below. property is a string giving the desired property to be obtained from the target address. If the property is not 'static' then an asynchronous listener will be established updating the value every 1000 msec. No 'callbacks' events will be issued. It is assumed that the application will continue to issue the same read requests for its life cycle. If this is not the case, then after an idle period of 5 minutes without any subsequent 'read' requests on the same parameter will cause the listener to be canceled, thereby notifying the corresonding server that this client is no longer interested in the parameter. format (string) is optional. If used it can specify the desired data acquisition format. If this is omitted, then the call will try to ascertain the default data output format. Make use of this parameter to override the default data type. Additionally, if it is known that a property has been multiply exported with different data types (i.e. overloaded) then this parameter can be used to determine which specific call is intended. This is often true in the case of structures. If a structure is wished for and the structure tag is known, then the property form of this parameter follows the paradigm: 'STRUCT.<tag>' (see example below. If the canonical data type is a structure, this parameter may be omitted, in which case the data structure will be 'discovered'. size (optional integer) is the requested data size. Many servers prefer by default to deliver 'multi-channel' arrays of all elements of the desired property (for instance an array containing ALL vacuum pressures beginning at the index determined by the 'device name' input). If the application only needs a single value (or subset), the size can be used to specify the precise number of elements required. timeout (optional integer) is the requested timeout (in milliseconds) which also determines the polling interval of the underlying 'listener', if an asynchronous listener is employed. By the default this is 1000 msec. If a faster update of the local buffers is desired, then this value may be adjusted accordingly. Note: if the the desired property is being 'scheduled' by the server, then the underlying listener will ALWAYS be updated 'immediately'. If the call needs to complete synchronously (e.g. some stock properties) then this value indeed specified a timeout which, if exceeded, can lead to a status error. mode (optional string) can be used to give specific calling instructions, such as 'SYNC' (use a synchronous call, i.e. no listener) or 'CONNECT' (use a TCP connection instead of the default UDP).
- Returns
- the acquired data as a python dictionary object with keywords
- 'status' giving the error/status code (which can be intepreted with strerror),
- 'timestring' giving the UTC timestamp of the returned data as a string
- 'timestamp' giving the UTC timestamp of the returned data as double (representing the number of seconds since January 1, 1970 with fractional seconds).
- 'sysstamp' giving the system stamp assigned to the data (obtained from the CYCLER for the context accessed).
- 'usrstamp' giving the user stamp assigned to the data (if any).
- 'data' giving the returned data for the targeted property.
Notice in the above example that the dictionary will not print the returned object in any systematic order according to the keywords. However this is not an issue, as one simply uses a keyword to focus in on the value(s) in question. For example the print dump of d['data'] in the above example.
As noted above, in the case of structures, one can specify the 'known' structure type in the call to tine_read as shown:
Note also in the above example that the 'data' field of the returned object is also represented as a dictionary whose keywords are the stucture fields. Should the structure be 'nested' then the 'data' field will likewise contain nested dictionaries.
If the structure type is unknown, it may be safely omitted, in which case it will be discovered. In the above example if we omit all optional parameters the call returns the 'registered' data size and type, in this case an array of 10 such structures:
As a final note: the format string given in the format parameter is case 'insensitive' with respect to the TINE format type. That it, 'struct' is identical to 'STRUCT', 'float' is identical to 'FLOAT'. However (and this is important) if a structure tag is appended to the format string 'struct' it is case 'sensitive'! That is 'SineInfo' is NOT the same as 'SINEINFO', etc. as far as structure tags are concerned. Also note further that the property being accessed is called 'SineInfo' as is the structure tag name. This is an unfortunate coincidence.
PyTine.stop_get
As noted, a call to PyTine.get is liable to start an asynchronous listener in order to locally reflect the targeted values from some server. Additional synchronous calls to PyTine.get with the same address parameters will object data from the local buffer. An asynchronous listener will stop listening following a dead-time of roughly five minutes without any additional calls to PyTine.get with the associated address parameters.
Under some circumstances this can result in an unwanted burden on network traffic and CPU load if the client application knows that it is no longer interested in the targeted values. For instance an combo box swithes to another device accessing a large waveform. In order to avoid waiting out the 5-minute deadtime, an application can proactively call PyTine.stop_get, with the same calling parameters as used in the original PyTine.get call. This will close the link to the underlying listener and the unnecessary extra network traffic and CPU load.
Simply typing 'PyTine.stop_get' at the python command prompt will generate a syntax exception with the following helper text:
PyTine.set
With 'PyTine.set' you can set the current target value of any targeted endpoint which allows WRITE access. Simply typing 'PyTine.set' at the python command prompt will generate a syntax exception with the following helper text:
Or within a python GUI environment such as IDLE you will see helper text when you type the method:
One sees that there are once again two primary required arguments, namely the target address and target property.
The parameter description is given in more detail below:
- Parameters
-
address is the initial parameter and must be a string of the form /<context>/<server>/<device>. This essentially follows the TINE naming hierarchy. If NO other input parameters are given, the default 'read' data type and data size (for the target property as established by the targeted server) will be acquired. See below. property is a string giving the desired property to be obtained from the target address. If the property is not 'static' then an asynchronous listener will be established updating the value every 1000 msec. No 'callbacks' events will be issued. It is assumed that the application will continue to issue the same read requests for its life cycle. If this is not the case, then after an idle period of 5 minutes without any subsequent 'read' requests on the same parameter will cause the listener to be canceled, thereby notifying the corresonding server that this client is no longer interested in the parameter. input (python object) is optional. If omitted the the 'set' call is a simple command which calls the target property with WRITE access. Some propertys such as 'INIT', 'RESET', etc. may be simple commands which do not take or require input data. Otherwise the python object passed can be a single text, number, or dictionary (structure) value or an array of such. format (string) is optional. If used it can specify the desired data input format. If this is omitted, then the call will try to ascertain the default data input format. Make use of this parameter to override the default data type. size (optional integer) is the input data size, namely the number of elements to send to the target. Use this to override the size of the input array passed as the input argument. timeout (optional integer) is the requested timeout (in milliseconds) which, if exceeded, can lead to a status error. Default = 1000 msec. mode (optional string) can be used to give specific calling instructions, such as 'CONNECT' (use a TCP connection instead of the default UDP). callback (optional callable python function) if passed to the set call this will effectively instruct PyTine.set to send the command asynchronously and return immediately. The results of the set operation are then posted in the callback function given.
- Returns
- void. Throws an exception if not successful.
Consider the simple task of setting some attribute, for instance the amplitude of a sine curve. Below we do this and read it back:
Note: If a structure is to be sent, then the structure fields (at least as far as the data types and sizes are concerned) MUST be known a priori. Theoretically a call to PyTine.get() can be made to discover the structure data type (as long as it is known that the designated property supports the delivered structure data type also as an 'input' data type!). Or the appropriate list query call can be made to likewise determine and register the structure in the local application.
When one knows the structure fields, one can construct the dictionary object to send as input.
In the example below, we use the 'SineInfo' structure as input to set several attributes of a sine curve atomically:
PyTine.call
With 'PyTine.call' you can atomically set and readback the current target value of any targeted endpoint which allows WRITE access.
You can also issue any READ call which requires input data.
Simply typing 'PyTine.call' at the python command prompt will generate a syntax exception the following helper text:
Or within a python GUI environment such as IDLE you will see helper text when you type the method:
One sees that there are once again two primary required arguments, namely the target address and target property. If these are the only two arguments supplied then PyTine.call() effectively is equivalent to PyTine.get().
The parameter description is given in more detail below:
- Parameters
-
address is the initial parameter and must be a string of the form /<context>/<server>/<device>. This essentially follows the TINE naming hierarchy. If NO other input parameters are given, the default 'read' data type and data size (for the target property as established by the targeted server) will be acquired. See below. property is a string giving the desired property to be obtained from the target address. If the property is not 'static' then an asynchronous listener will be established updating the value every 1000 msec. No 'callbacks' events will be issued. It is assumed that the application will continue to issue the same read requests for its life cycle. If this is not the case, then after an idle period of 5 minutes without any subsequent 'read' requests on the same parameter will cause the listener to be canceled, thereby notifying the corresonding server that this client is no longer interested in the parameter. input (python object) is optional. If omitted the the 'set' call is a simple command which calls the target property with WRITE access. Some propertys such as 'INIT', 'RESET', etc. may be simple commands which do not take or require input data. Otherwise the python object passed can be a single text, number, or dictionary (structure) value or an array of such. format (string) is optional. If used it can specify the desired data output format. If this is omitted, then the call will try to ascertain the default data output format. Make use of this parameter to override the default data type. size (optional integer) is the output data size, namely the number of elements to receive from the target. inputformat (string) is optional. If used it can specify the desired data input format. If this is omitted and format has been supplied, then the input data type is taken from the output format. If neither has been supplied then the call will try to ascertain the default data input format. inputsize (optional integer) is the intput data size, namely the number of elements to send to the target. Use this to override the size of the input array passed as the input argument. The default value is 1 if an input object has been provided. timeout (optional integer) is the requested timeout (in milliseconds) which, if exceeded, can lead to a status error. Default = 1000 msec. mode (optional string) can be used to give specific calling instructions, such as 'CONNECT' (use a TCP connection instead of the default UDP) and in particular the data access mode, i.e. 'WRITE' for WRITE access. Simply OR all desired mode instructions (e.g. 'WRITE|CONNECT').
- Returns
- the acquired data as a python dictionary object with keywords
- 'status' giving the error/status code (which can be intepreted with strerror),
- 'timestring' giving the UTC timestamp of the returned data as a string
- 'timestamp' giving the UTC timestamp of the returned data as double (representing the number of seconds since January 1, 1970 with fractional seconds).
- 'sysstamp' giving the system stamp assigned to the data (obtained from the CYCLER for the context accessed).
- 'usrstamp' giving the user stamp assigned to the data (if any).
- 'data' giving the returned data for the targeted property.
And an example, here we issue an atomic 'WRITE/READ' where we set the 'Noise' of '/TEST/SineServer/SineGen3' to 31.
We specify the size as '1' so that the returned data only delivers the single value (as we know in advance that property 'Noise' is a multi-channel array property and by default will deliver all values):
PyTine.attach
Besides making use of the underlying 'listeners' to monitor and reflect the data of targeted properties, you an also explicitly issue asynchronous data acquision by making use of PyTine.attach and providing a callback function. This has the advantage of responding immediately to a data update as opposed to synchronously polling within a python application. The monitor so established can also be instructed to notify on 'datachange' or even on 'event' (where the targeted server is explicity scheduling property data in order to avoid readback latency).
Simply typing 'PyTine.call' at the python command prompt will generate a syntax exception the following helper text:
Or within a python GUI environment such as IDLE you will see helper text when you type the method:
One sees that there are here three primary required arguments, namely the target address and target property and a 'callable' python function, which should take (int,int,object) as arguments.
The parameter description is given in more detail below:
- Parameters
-
address is the initial parameter and must be a string of the form /<context>/<server>/<device>. This essentially follows the TINE naming hierarchy. If NO other input parameters are given, the default 'read' data type and data size (for the target property as established by the targeted server) will be acquired. See below. property is a string giving the desired property to be obtained from the target address. If the property is not 'static' then an asynchronous listener will be established updating the value every 1000 msec. No 'callbacks' events will be issued. It is assumed that the application will continue to issue the same read requests for its life cycle. If this is not the case, then after an idle period of 5 minutes without any subsequent 'read' requests on the same parameter will cause the listener to be canceled, thereby notifying the corresonding server that this client is no longer interested in the parameter. callback is a python 'callable' function which takes arguments (int id, int cc, Object data). input (python object) is optional. If omitted the the 'set' call is a simple command which calls the target property with WRITE access. Some propertys such as 'INIT', 'RESET', etc. may be simple commands which do not take or require input data. Otherwise the python object passed can be a single text, number, or dictionary (structure) value or an array of such. format (string) is optional. If used it can specify the desired data output format. If this is omitted, then the call will try to ascertain the default data output format. Make use of this parameter to override the default data type. size (optional integer) is the output data size, namely the number of elements to receive from the target. inputformat (string) is optional. If used it can specify the desired data input format. If this is omitted and format has been supplied, then the input data type is taken from the output format. If neither has been supplied then the call will try to ascertain the default data input format. inputsize (optional integer) is the intput data size, namely the number of elements to send to the target. Use this to override the size of the input array passed as the input argument. The default value is 1 if an input object has been provided. interval (optional integer) is the requested update interval (in milliseconds). Even in a DATACHANGE mode, this interval plays a role, as it instructs the targeted server 'how often it should look'. mode (optional string) can be used to give specific calling instructions, such as 'CONNECT' (use a TCP connection instead of the default UDP) or 'NETWORK' (send as UDP multicast). id (optional int) can be used to specify a desired callback 'id' (the first int argument in the provided callback routine). If this is not given, then id will always contain '0'. access (optional string) can be used to specify the access of the contract (i.e. READ and/or WRITE. The standard default access is READ. If you apply the WRITE access as well the call to PyTine.attach reverts to a SINGLE transfer (as opposed to TIMER or DATACHANGE). The results of the operation are then posted in the given callback function.
- Returns
- the link id which can later be used to 'detach()' (i.e. stop monitoring).
When the callback routine is fired, the 'data' (third) argument passed will be a Python object which parallels the object returned from a PyTine.get() call. That is, the object will be a python dictionary containing:
- 'status' giving the error/status code (which can be intepreted with strerror),
- 'timestring' giving the UTC timestamp of the returned data as a string
- 'timestamp' giving the UTC timestamp of the returned data as double (representing the number of seconds since January 1, 1970 with fractional seconds).
- 'sysstamp' giving the system stamp assigned to the data (obtained from the CYCLER for the context accessed).
- 'usrstamp' giving the user stamp assigned to the data (if any).
- 'data' giving the returned data for the targeted property.
Consider the following example, which establishes a data link to get the beam current in PETRA:
Example:
First a callback routine is declared (defined), which in this simple example just prints out the data timestamp as a string and the data when the callback is fired.
The monitor link is started and the returned link ID is kept in a global variable called 'lid'. The callback is then called regularly at 1 second intervals (because the default interval 1000 and the default mode TIMER have been used).
The monitor can be stopped by calling PyTine.detach() (here: 'pt.detach(lid)').
PyTine.detach
As noted above, a monitor link can be halted at any time by noting the link id returned from the initial monitor call and using it as argument to PyTine.detach().
The parameter description is given in more detail below:
- Parameters
-
linkid is the link id returned from the PyTine.attach() call used to start the monitor.
PyTine.list PyTine.hist PyTine.strerror PyTine.version PyTine.debug
Browsing Utilities
Browing the control system for elements can generally be achieved by making use of PyTine.list().
PyTine.list
PyTine.list() can be called without arguments. That is all arguments are optional. The parameter description for PyTine.list is given below:
- Parameters
-
context is a string which identifies the targeted context. server is a string which identifies the targeted server. If server is provided as an argument then context must also be provided, otherwise a query to get the contexts will ensue. device is a string which identifies the targeted device name. It might be necessary to provide this parameter for 'device oriented' servers, where different devices might have different associated properties. property is a string which identifies the targeted property. It might be necessary to provide this parameter for 'property oriented' servers, where different properties might have different associated device names. structure is a string which identifies the targeted structure tag for which the field names are desired. In general the context and server must likely be provided for a call to get the structure fields.
The top tier of the TINE naming hierarchy is the 'context'. To ascertain the available contexts within the control system, simply call 'PyTine.list()' without arguments.
A call to 'PyTine.list()' without arguments will return a list of all available contexts as a dictionary with the single keyword 'contexts'.
The next tier of the TINE naming hierarchy is the device server (or device group). Note: a device 'group' can appear as a logical server in a list of device servers, when in fact it refers to a 'group' of physically distinct servers of a the same variety.
A call to 'PyTine.list()' with the context parameter only will return a list of available servers in the given context as a dictionary with the single keyword 'servers'.
The next tier of the TINE naming hierarchy is the device name. Most servers are device servers with a flat hierarchy at this stage. By this we mean that they will provide a set of registered devices and a set of registered properties, and each property is supported by each device as well as each device supports all registered properties.
Thus a call to 'PyTine.list()' with both the context and a target server specified will return a list of the registered properties and devices of targeted server. Here the returned dictionary has a list of names for keyword 'devices' and a list of name for keyword 'properties':
It is possible to register a server as a 'device-oriented' server, whereby it cannot be a-priori assumed that each device managed by the server supports the same list of properties. Likewise it is also possible to register a server as a 'property-oriented' server whereby each individual registered property might support its own independent set of 'keywords' (which then assume the role of 'device names'). This is typical of 'service-oriented' servers (e.g. Central Archive Server, or Central Alarm Server) and is definitely true of CDI servers.
If a call to 'PyTine.list()' with context and specified lands on such a server, then the returned dictionary will only contain the single keyword 'devices' if the server is device oriented or it will contain the single keyword 'properties'if the server is property oriented. To obtain the properties for a device, the 'PyTine.list()' call needs to be issued with a specific device entered. For instance, below a video server ('device oriented') is queried:
To obtain the device list for a property from a property-oriented server, then 'PyTine.list()' call needs to be issued with a specific property. For instance, below a CDI server is queried:
Archive Utilities
Many of the control system parameters will be archived and ready for retrievel and examination when called for.
Archived data can be stored 'centrally', where a range of filtering parameters might be in play (so as to reduce the amount of unnecessary data commited to disk). 'centrally' stored data are always availible and never expired.
Archive data can also be stored 'locally', where simpler filtering based on tolerances might be in play. 'locally' stored data are available only for a (configurable) duration, typically 1 to 3 months.
Archive data might be stored 'centrally' based on an 'event trigger'. This usually refers to 'post-mortem' events, such as an RF trip or unexpected beam loss, etc. Such data are managed differently than the regular trend archives descibed above. Event data generally have an associated event 'comment' (the reason why the event was triggered), which can be edited by 'experts' at any time. Event data are associated with a specific point in time and a specific trigger. Consequently retrieving archived event data is a bit more 'involved' than simple history trends of stored machine variables (see Event Archive Utilities below).
The primary python method for retrieving and analysizing archive data over time is PyTine.history().
PyTine.history
Simply typing 'PyTine.history()' at the command prompt will generate the 'usage' message shown below:
Or within a python GUI environment such as IDLE you will see helper text when you type the method:
One sees that there are once again two primary required arguments, namely the target address and target property.
The parameter description is given in more detail below:
- Parameters
-
address is the initial parameter and must be a string of the form /<context>/<server>/<device>. This essentially follows the TINE naming hierarchy. If NO other input parameters are given, the default 'read' data type and data size (for the target property as established by the targeted server) will be acquired. If data from the central archiver are to be obtained, then the 'server' in the address string should be 'HISTORY'. property is a string giving the desired property to be obtained from the target address. stop (optional string) gives the stop time to use in the data range of the archive call (default = 'Now'). The 'stop time' should be given in a string data format ('dd.mm.yyyy hh:mm:ss') or the string 'now' to refer to the current time.
depth (optional string) should begin with a number and be followed by a representative unit of time ('days','hours','minutes', etc.). (default = '1day'). The 'depth' can also be used to specify the acquisition of a data 'snapshot' (e.g. of a waveform or multi-channel array) at a particular time. Then the 'stop time' gives the desired time and 'depth' should contain the string 'snapshot'. flags (optional string) is a string which can be used to supply archive acquisition options. For instance to retrieve the archived data system stamps along with the data and timestamps, then 'flags' = 'SYSTEMSTAMP' should be specified. timeout (optional integer) is the requested timeout (in milliseconds) which, if exceeded, can lead to a status error. Default = 1000 msec. sample (optinal integer) is the requested sampling raster. If '0' (default) then the target server will determine the best sampling raster to use in order to return representative data over the time range (stop time and depth) for the number of points requested (default = 1000). Every effort will be made to ensure that points of interest (e.g. spikes and dips) will be returned in the data. However, to be on the safe side you may want to specify the sampling raster (e.g. '1'), if all stored archive data are required. Note that the returned data will likely not cover the requested range, in which case the call should be repeated using the same stop time and a depth given by the \stop time minus the time of the last returned data point. numberPoints (optional integer) is the requested number of returned data points (default = 1000). The returned number of archived data points will not exceed this number. You should decide what the goal of the archive history call is in deciding on the optimal number of points. If a simply plot of stored data over a range is desired, then the default settings for sample and numberPoints are most likely fine. If all stored data are required for a more extensive analysis, then perhaps a large numberPoints and a sample raster of '1' are optimal.
The example below shows a simple call to get the local history from a targeted server, specifying a depth of 8 hours.
As there is no long term storage, the call only returns a few points over this interval. The returned data are given in 'value-timestamp' pairs, where the timestamp is UTC seconds since 1970 (including fractional seconds). Making the same call again, but passing flags='SYSTEMSTAMP' will return an array of data 'triplets' containing 'value-timestamp-systemstamp' tuples.
A call to the central archiver might look like:
As an example of a 'snapshot', below shows the acquistion of the entire multi-channel array of beam loss monitor rates at PETRA for a specific time:
Note that the returned data will be the closest time (equal to or greater than) the specified target time.
Event Archive Utilities
You can also use python to easily interface with the TINE Post Mortem/Event Archive System. The following utilities are available in PyTine :
PyTine.triggerEvent
Use this call if you need to trigger an event from python.
Simply typing 'PyTine.triggerEvent()' at the command prompt will generate the 'usage' exception message shown below:
The parameter description is given in more detail below:
- Parameters
-
context is the TINE context to which the event server receiving the trigger belongs. event is the event trigger name. The event trigger name defines the event. A call to triggerEvent signals the the event server to run through the data acquistion instructions related to the event identified by this trigger name. Ergo, this must be a known event, or this call will result in an invalid_index return code. comment is an optional comment to be assigned to the event at the time of the trigger. This comment will be designated as 'static' and under most circumstances will not disappear if a user further annotates the event comment for this particular event. triggerLevel is an optional trigger level (default = 1), which indicates which step in the event data acquistion should be taken as the initial step. A value of '-1' indicates that the event server should obtain a global event number for this particular event from the SITE event server. triggerTime can be used to optionally specify the UTC event id to be assigned to this event. Generally this will be the UTC value for now at the time of trigger, or a global value from the SITE event server. Under some circumstances a server might wish to e.g. collect data from hardware and post-assign a UTC time id to the event after the data have been taken. rangeStart gives the input as a system stamp specification. A negative value or '0' signals the system to apply treat the rangeStart value as an offset to the provided 'triggerTime' as to use the input as a time stamp specification. rangeStop provides the end of a system-stamp (or time-stamp) range to use when obtaining data froma a server's local history. If rangeStop is less that rangeStart, then the value given is used as an increment to apply to the given rangeStart (with a maximum cutoff at 1000). In other words, if rangeStop < rangeStart then rangeStop = rangeStart + rangeStop. rangeMax provides a maximum number of sequence entries to obtain over the range provided. A negative value will negate the range specifcations entirely. A value of '0' will signal the system to use a default maximum (typically = 100). options provides additional 'flags' to define trigger criteria. Currently, the only available option is EVNT_TRIGGER_USE_USERSTAMP which signals the event server to focus on the 'user' data stamp (and not the system stamp) in the range specifications.
As an example:
PyTine.getEventList
Use this call to obtain a list of stored events for the trigger specified.
Simply typing 'PyTine.getEventList()' at the command prompt will generate the 'usage' exception message shown below:
The parameter description is given in more detail below:
- Parameters
-
context is the TINE context to which the event server receiving the trigger belongs. event is the event trigger name for which the event list is desired. startTime optionally provides the beginning of the time range for which the event list is desired. If omitted, now minus one month will be used. stopTime optionally provides the end of the time range for which the event list is desired. If omitted, now will be used. limit optionally provides the maximum number of events to retrieve. The returned list will be in descending order. If omitted, the limit will be '1' (i.e. the most recent stored event).
As an example:
PyTine.getArchivedEventData
Use this call to actually retrieve data stored with the event.
Simply typing 'PyTine.getArchivedEventData()' at the command prompt will generate the 'usage' exception message shown below:
The parameter description is given in more detail below:
- Parameters
-
context is the TINE context to which the event server receiving the trigger belongs. event is the event trigger name for which the event data is desired. eventId is the UTC event id specifying the particular event whose data are desired. This should provide the unique UTC event Id assigned to the event when it was triggered and can be passed as a UTC integer value or a human readable string representation which corresponds to the UTC event Id. channel optionally provides a full stored address entry string in the form /<context>/<server>/<device>[<property>]. if this parameter is not provided then the eventServer, eventDevice, and eventProperty parameters must be provided. The point being: the stored address of the item whose data are desired must be provided. eventServer optionally provides the stored server name whose data are desired (if channel is not used). eventDevice optionally provides the stored device name whose data are desired (if channel is not used). eventProperty optionally provides the stored property name whose data are desired (if channel is not used). eventContext optionally provides the stored context name whose data are desired (if channel is not used). If eventContext (and channel) are not provided then the value of context will be assumed. format optionally provides the desired format specification for the returned data. size optionally provides the desired (maximum) array size for the returned data.
As an example:
In the above, the channel parameter was used to specify the desired stored address and the event ID was passed directely as a UTC integer ID.
PyTine.getEventArchiveComment
Each stored event can (and usually does) provide a comment (an annotation) describing the particular event. In most cases the initial comment is provided with the event trigger at the time of the trigger (the static comment). Experts who later examine the contents of the stored event can then further annotate the event in question (the user comment), as well as specifiy that the event should not expired (be removed from the system after some length of time), i.e. the status).
Simply typing 'PyTine.getEventArchiveComment()' at the command prompt will generate the 'usage' exception message shown below:
The parameter description is given in more detail below:
- Parameters
-
context is the TINE context to which the event server receiving the trigger belongs. event is the event trigger name for which the event annotation is desired. eventId is the UTC event id specifying the particular event whose data are desired. This should provide the unique UTC event Id assigned to the event when it was triggered and can be passed as a UTC integer value or a human readable string representation which corresponds to the UTC event Id.
As an example:
We see that the returned comment is actually a dictionary with keys status (the current event status - primary either 'SAVE', 'NONE' or 'DELETE'), static (the static event trigger comment), and user (the expert analysis annotation).
PyTine.setEventArchiveComment
You can assume the role of an expert and supply specific event annotations with this method.
Simply typing 'PyTine.setEventArchiveComment()' at the command prompt will generate the 'usage' exception message shown below:
The parameter description is given in more detail below:
- Parameters
-
context is the TINE context to which the event server receiving the trigger belongs. event is the event trigger name for which the event annotation is desired. eventId is the UTC event id specifying the particular event whose data are desired. This should provide the unique UTC event Id assigned to the event when it was triggered and can be passed as a UTC integer value or a human readable string representation which corresponds to the UTC event Id. comment gives the annotation string to apply to this specific event. This can either be a simple comment string with the associated STATUS, STATIC, and USER sections or not (in which case the comment string is treated as a USER annotation. Or the comment passed can be a dictionary object with the keys status, static, and user provided).
As an example:
Server API
Python is in many cases a very good language in which to write middle layer logic, where data is acquired from one or more front-end servers, manipulated, and then some resulting data should be made available to the control system 'at large' for purposes of display or archiving, etc.
You can write a TINE server completely in Python by making use of the following PyTine functions described below. Once again, these routines follow in the most part the paradigm of the Buffered Server.
A Python server can simply attach to an existing server configuration database (either a .csv file set or a single .xml file specifying the property and device information along with the server's name, etc. See Attaching a Server to a Database) or it can make use of registration calls such as register_server, register_property, register_device, etc. to do the same, essentially on the fly (See a Simple On-the-fly Server Registration).
List of API Calls (details below)
- PyTine.attach_server attaches to an existing server configuration database (either .csv or .xml based).
- PyTine.attach_handler attaches a python handler function to a specified property so as to handle WRITE events.
- PyTine.pushdata pushes a python data set to a specified property.
- PyTine.register_fec assigns a FEC name and other parameters to the Python server (in lieu of attach_server).
- PyTine.register_server assigns a server name (and context) to the Python server (in lieu of attach_server).
- PyTine.register_device registers a device with the Python server.
- PyTine.register_property registers a property with the Python server.
- PyTine.register_type registers a structure data type.
- PyTine.register_error_code registers a user-defined error code (beyond the systematically known error codes).
- PyTine.register_death_handler registers a Python function to handle any server termination event that might occur during initialization.
- PyTine.setalarm sets an alarm for the given device.
- PyTine.clearalarm clears an alarm for the given device or all devices (depending on input).
- PyTine.allowed_users retrieves, adds, or removes user names to/from the list of users with WRITE permission
- PyTine.allowed_addresses retrieves, adds, or removes network addresses to/from the list of addresses with WRITE permission
- PyTine.errorlist retrieves the list of error code enumerations
- PyTine.log appends log file entries to the desired log file
Attaching a Server to a Database
PyTine.attach_server
If the server's properties and devices are available via a TINE database (produced, for instance, by using the TINE server wizard), then a simple call to 'PyTine.attach_server()' will cause the configuration database to be read and make the configured properties and devices avialable. The server will automatically 'plug' itself into the control system and be visable to prospective clients. At this stage there will likely be NO intersting data to be read from any of the properties, as the underlying buffers will have been initialized to contain '0'. A call to 'PyTine.attach_server()' without any arguments at all will look only for a 'fec.xml' file, where it will expect to find all information necessary to register the fec process along with any servers and their properties, devices, and associated information.
- Parameters
-
eqm (string) is the so-called 'local name' of the equipment module. This is a 6-character name used for administration purposes within the running process and is thus required only to be unique within the process. In Python, you will likely have only a single registered server per Python process, so this minimal restriction scarely presents a problem. Although a meaningless character string such as "1" will suffice, it is typical to provide a 3-letter acronym followed by "EQM" (for equipment module), for instance "MLBEQM". server (string) is the equipment module's exported name. This is the server name which all control system clients will 'see'. This can be up to 32-characters in length. This name must be unique within the registered context (as given in the fecid.csv file or fec.xml file). capacity (int) is the maximum number of device instances that this server will manage.
- Returns
- 0 upon success, otherwise a TINE error code
Alternatively you can completely forgo any configuration database and register all necessary information via the registration API calls 'PyTine.register_fec', 'PyTine.register_server', 'PyTine.register_device', and 'PyTine.register_property' (see below).
PyTine.pushdata
In order to supply the registered properties with data, the Python 'server' should call 'PyTine.pushdata' when it has determined that new data are available for the property in question. Using just 'PyTine.attach_server' and 'PyTine.pushdata' in this manner are theoretically the only Python calls necessary to provide a 'READ-ONLY' server.
- Parameters
-
property (string) is the property for which the supplied data are to be used. device (string) is the specific device instance for which the supplied data are to be used. This must be a string corresponding to a registered device or a string of the form "#1", etc. which then indicates the device instance 'numerically'. devicenumber (int) is the specific device instance according to its numerical form only. This is frequently a better option for a server, which may not know (or need to know) which device 'names' have been configured. If both device and devicenumber are provided, devicenumber will take precedence. data (object) is the data (array) which is to be 'pushed' into the underlying property buffer. size (int) is the length of the data array to push into the property buffer. If omitted, the entire contents of the data array will be used. scheduled (int) is an integer flag which if non-zero instructs the subsystem to immediately notify all listening clients of a change in the property's data. timestamp (double) is an explicit (utc) timestamp with which to 'tag' the data. Normally, the time of the call to 'PyTine.pushdata' is used as the data timestamp. The double value represents seconds since Jan. 1, 1970 and can contain fractions of a second. systemstamp (int) is an explicit system cycle/event number stamp with which to 'tag' the data. If not provided, then the system-wide cycle/event number will be used (if known). userstamp (int) is an option user-defined stamp with which to 'tag' the data.
- Returns
- 0 upon success, otherwise a TINE error code
If the server is to respond to WRITE commands, it should provide a property dispatch handler by making use of 'PyTine.attach_handler'.
Note that if the data to be pushed is a structure, this must correspond to a registered structure AND the property in question must be registered to support this structure. See the discussion below concerning registering a structure and registering a property.
PyTine.attach_handler
If a property is to accept WRITE requests, that is requests which attempt to change a setting, then the Python server should provide a dispatch handler for the corresponding property. This is done by make a call to 'PyTine.attach_handler' and providing the appropriate Python function to act as the dispatcher.
- Parameters
-
property is the property to which the handler is to be associated. handler is a Python callable function to be called when a WRITE transaction for the property is being requested by some client.
The handler routine passed should accept a single Python Object will be be Python dictionary and return an integer (used as a TINE return code). The dictionary object passed to the handler will contain the fields property (indicating the property which is triggering the handler), device (indicating the device which is triggering the handler), devicenumber (indicating the device as the associated device number which is triggering the handler), caller (indicating the caller who is triggering the handler), and data (the input data being passed to the handler - Py_None if no data have been sent).
- Returns
- 0 upon success, otherwise a TINE error code
It is up to the dispatch routine to either accept the call (return '0') or to reject the setting on some other grounds (return non-zero : see the section on TINE error codes).
An atomic 'write/read' call will expect to read back the value it just sent (if the return code indicates success), so a call to PyTine.pushdata should be included in the handler if all goes well. This detail however is entirely up to the developer.
An example of server attaching to a 'csv-style' server database with equipment module 'SINEQM' is shown below. A Python script makes calls to 'PyTine.attach_server', which attaches itself to a pre-configured data base. It then pushes a startup value for the (known) property 'Amplitude' and defines and attaches a property handler for property 'Amplitude' by calling 'PyTine.attach_handler'.
In the above case, the property handler always returns '0' (success). Under certain circumstances it might be desireable to rerurn an error code. In such cases, simply return a valid tine error code or a user-defined (see register_error_code) error code. For instance,
The call to 'tine_attach_server' as noted above attaches itself to a configuration database.
In this case, it consists of a set of .csv files.
The file 'fecid.csv' is located in the FEC_HOME directory:
The file 'exports.csv' is located in a subdirectory of the FEC_HOME directory called 'SINEQM' (the subdirectory name MUST be the same as given the call to 'tine_attach_server').
This file essentially gives the names of the exported properties as well as all relevant information about the exported properties. This information is in fact used to determine the sizes and behaviors of the underlying property buffers. The file 'exports.csv' also provides the exported server name, in this case "MLSineServer". This exported server name is used as a cross-reference within the fecid.csv file to latch onto the appropriate FEC, in case of any ambiguity (note: a fecid.csv can contain multiple entries).
The file 'devices.csv' is also located in the 'SINEQM' subdirectory and provides the device names for the individual devices.
Note that the number of devices in total is given in the 'exports.csv' file as '10' (the NUM_DEVICES column). Thus, at most 10 entries will be read from the 'devices.csv' file.
An alternative server configuration database involves the single file 'fec.xml' which contains all of the configuration details. Going this route would have the 'all-eggs-in-one-basket' advantage (a set of .csv Files can be large and confusing), but have the disadvange of not being able to easily focus on targeted configuration changes. If the call to PyTine.attach_server is made without options then the server initialization only looks for a single fec.xml file.
The advantage of 'attaching' to a server database is that all of the configuration details are kept in a separate configuration file or set of files and not hard-coded.
The disadvantage is that the Python server must know a-priori what the contents of the configuration database are. E.g. 'know' that there is a property 'Amplitude' in the above example, 'know' how many devices are supprted, etc. etc.
It is then often more advantageous to register all configuration information directly in Python. As the python server uses a 'one-FEC, one-server' policy, the information necessary to launch a fully functioning server on-the-fly is minimal (e.g. an 'acceptible' - in most cases - FEC Name can be generated from the input server name and context, the local equipment module name is simply taken to be 'PYEQM').
The set of available server configuration routines consist of the following:
PyTine.register_fec
You can assign a FEC name to your Python server via the API call 'PyTine.register_fec'.
If you want to register a specific FEC name or provide other specific FEC information you can do so with this call.
Simply typing 'PyTine.register_fec()' at the Python prompt will produce the following output:
The one required argument is the 'name', which provices the system-wide unique FEC Name (see the Overview documentation: 'What's in a Name?'). However if all other arguments are omitted, then the default port offset will be determined by scanning the local FEC manifest in order to avoid a conflict with other servers which are possibly running on the same host. Likewise it is often useful to provide information as the location, responsibility, 'context' (default = "TEST") and 'subsystem' (default = "TEST"). So making use of all parameters is encouraged.
- Parameters
-
name (string) is the system wide unique name of the FEC process (up to 16 characters in length) subsystem (optional string) is the control subsystem to which the servers should be associated. (e.g. "VAC", "DIAG", "MAG", etc.). This is not a part of the name hierarchy but can be used in browsing. context (optional string) is the control system context in which the servers should be registered. description (optional string) is a description (up to 64 characters) of the functionality of the FEC. location i(optional string) s a string (32 characters) containing the phyisical location of the FEC host computer. hardware (optional string) is a string description of attached hardware. For most Python middle layers, this will simply be "none". responsible (optional string) is the person (or persons) to contact in case of problems. It should also contain the 'user name' if possible of such persons, as administrative actions (such as 'removing' the FEC from the ENS database) will require a 'match' on the user name of the person attempting such actions versus those 'responsible' for the FEC in question. port (optional int) is the port 'offset' to be applied to all of the server's listening service ports. This should be a simple integer between 0 and 55500, but preferably small. The default is '0'.
If multiple FECs run on a single computer, then each must have its own unique port offset. Hence the default value of '0' will work only once per host. Once again, this is not the listening 'port address' but is an 'offset' to be applied to a set of listening ports (UDP, TCP, STREAM, Debug, and even possibly IPX).
- Returns
- '0' upon success or a TINE error code.
PyTine.register_server
You can assign the server's exported name and local equipment module name to your Python server via the API call 'PyTine.register_server'.
Simply typing 'PyTine.register_server()' at the Python prompt will produce the following output:
- Parameters
-
name (string) is the desired exported server name. This is the server name which all control system clients will 'see'. This can be up to 32-characters in length. This name must be unique within the registered context. context (optional string) is the desired context for the server (default = 'TEST'). Note that the combination of server name and context must be system-wide unique (or the server will not register itself in the system and an 'address in use' message will be returned from the equipment name server). eqm (optional string) is the so-called 'local name' of the equipment module. This is a 6-character name used for administration purposes within the running process and is thus required only to be unique within the process. (default = 'PYEQM'). capacity (optional int) is the maximum number of device instances that this server will manage. (default = 1000). fec (optional string) is the desired FEC name. You can completely forgo the call to PyTine.register_fec if the value of the additional FEC information is not relevant and provide a FEC name here via this parameter. If the FEC name has already been determined then the value of this parameter is irrelevant.
- Returns
- '0' upon success or a TINE error code.
- Note
- If no call to PyTine.register_fec has been made and no 'fec' parameter has been supplied in the call to PyTine.register_server then a viable FEC name will be determined, based on the context and server names known at the time of registration. As the FEC name must also be system-wide unique but only consists of 16 characters, there could possibly be a name collision if this is left to 'chance'.
Thus a look in the fec.log if things should go wrong is advisable.
- if no port offset is specified an attempt to find a viable port is made be scaning the local fec manifest.
PyTine.register_device
You can assign the server's device instance names within your Python server via the API call 'PyTine.register_device'
Simply typing 'PyTine.register_device()' at the Python prompt will produce the following output:
- Parameters
-
name (string) is the name of the device instance to be registered. number (int) is the associated device number. This must be greater than or equal to 0 and smaller than the device 'capacity' entered in 'PyTine.register_server' in order to succeed. description (optional string) can be used to supply a device description. location (optional string) can be used to supply a device location information. zpostion (optional float) can be used to supply a device z-position information. redirection (optional string) must be a string of the form '/<context>/<server>/<device>[<property>]' if the device instance in question does reside on the local server but should be redirected to a remote server. propertylist (optional string list) can be used to associate a list of properties to the given device. This will effectively establish a device-oriented server.
- Returns
- '0' upon success or a TINE error code.
PyTine.register_property
You can assign the server's property names and information within your Python server via the API call 'PyTine.register_property'.
Simply typing 'PyTine.register_property()' at the Python prompt will produce the following output:
Here a detailed description of the parameters:
- Parameters
-
name (string) is the property name to be registered size (int) gives the array size of properties output format (string) gives the data type of the property. This should by a string such as 'float', 'int32' (synonym: 'int'), etc. Strings entries are best dealt with by using a 'fixed-capacity' string type such as 'NAME16' or 'NAME64', etc. Additional array 'type' information is supplied by attaching e.g. '.CHANNEL' (for channel array) or '.SPECTRUM' for (a spectrum array). mode (optional string) gives the access mode of the property.
('READ', 'WRITE', 'READ|WRITE', etc.) If 'WRITE' is among the mode instructions, then the input size will be taken as '1' and input format as the same as the output format (i.e. attribute like conditions). If the output data size is 0 then the input data size is also 0 and the access mode must be specified as 'WRITE'. Such a case would signal a 'command-style' property.min (optional float) gives the minimum range of the property values max (optional float) gives the maximum range of the property values units (optional string) gives the engineering units of the property (a string not to exceed 16 characters) description (optional string) gives a description of the data supplied by, or the action initiated by calling the property.
- Returns
- A positive 'id' for the registered property upon success or the negative of a TINE error code if there is an error.
Simple On-the-fly Server Registration
It is actually quite easy to make use of the above registration calls to produce a Python server on-the-fly at the command line. Consider the following example:
Here the server name is the only argument passed to PyTine.register_server. Thus the context is by default 'TEST'. A Fec Name is generated based on this information, a port is deduced from the local manifest and the server is registered and available to the control system:
This particular server does not do very much other than accept commands to change the values stored for the three devices registered.
One can make use of Python threads and timers to otherwise update the data represented by the property 'Value'.
Similarly, an update thread or timer might also set and clear alarms.
PyTine.setalarm
Alarms are in general associated with a particular device and defined by a specific alarm code (see the section on the Alarm System). The static information associated with an alarm code is found in the alarms definition file alarms.csv. If conditions warrant you can set an alarm within an update routine via this API call. Simply typing PyTine.setalarm() at the command prompt will produce the following usage text:
- Parameters
-
code (integer) is the alarm code which designates which alarm is being applied to the device given. device (string) is the device name (optional) indicating which device is setting the alarm. devicenumber (integer) is the device number (optional) indicating which device is setting the alarm. Either the device or the devicenumber parameter should be supplied (whichever is the more convenient coding paradigm). If both are omitted, then the alarm is applied to device 0. data (type given in the alarms.csv definition) is the optional data associated with the alarm. options (string) is an optional alarm descriptor which can specify the type of alarm. Here only "TRANSIENT" is supported (signalling the that alarm has no duration and is both new and terminated at the same time).
PyTine.clearalarm
An alarm once set will remain in the local alarm tables until its clear counter has passed the removal threshold (typically 8).
Simply typing PyTine.clearalarm() is a valid call as it stands. To see the usage text, one can type e.g. PyTine.clearalarm(help) at the command prompt and see the following usage text:
- Parameters
-
code (integer) is the alarm code specifying which alarm should be cleared. If omitted, then the clear counter of all active alarms for the given device is increased by 1.
Otherwise, the designated alarm is marked for immediate termination.device (string) is the device name (optional) indicating which device is to be cleared. If omitted, then all alarms will be cleared. Note: if code is specified then either device or devicenumber must be specified as well. Otherwise, the call will return an error (invalid_parameter). devicenumber (integer) is the device number (optional) indicating which device is setting the alarm (if device has not been passed.
PyTine.register_type
A Python server can handle structures as input or output like any other TINE server. You will need to register the structure(s) you wish to use during initialization. This is best accomplished by making use of a call to 'PyTine.register_type'. Simply typing PyTine.register_type() at the command prompt will produce the following usage text:
- Parameters
-
tag (string) is a string identifier to associate with the structure being registered. This should not be longer than 16 characters, as the underlying tine kernel will truncate the structure tag to 16 characters if need be. struct (obj) is a python dictionary of key-value pairs giving the overall makeup of the structure.
The initial values in the key-value pair list are irrelevant other than their values do in fact determine the format of the associated structure field. Thus integer values will be taken as 32-bit integers (unless otherwise decorated) and float values will be taken as 32-bit float values (unless otherwises decorated). String values will be assumed to be fix-length string fields with the length of the field being given by the length of the string used in initialization. Hint: make use of e.g. .ljust(64) or .rjust(64) to specify a 64-character string field.
As an example consider the C structure:
To realize this in Python so as to pass it along to PyTine.register_type() you would do something like :
A server making use of this new data type for property Header might register itself along these lines:
Then a client-side call for this property Header will yield the desired structure:
PyTine.register_error_code
Use this call to register a error code which can be used as a return code from a property handler (in addition to the system error codes).
- Parameters
-
code (integer) is the user defined error code to be inserted into the error registry. Must be >= 512. text is a short (up to 32 characters) text description to be associated with the error code. longtext is a longer (up to 128 characters) text description to be associated with the error code.
PyTine.register_death_handler
A tine server will under some circumstances make a hard exit if it cannot be successfully initialized. For instance, the server socket cannot be opened, or the desired server or FEC name cannot be assigned because it is already being used, etc. In such cases, it is usually better to halt execution (with appropriate log file entries and console messages) and force the problem to be dealt with rather than give the impression that the server is somehow running.
When this happens, the process can optionally be informed that such a signal has occurred and revoke the automatic process termination and take steps to gracerfully return resources to the system, etc. If this is desired, the Python server should register a death handler via this API call.
- Parameters
-
handler is a callable python function which will be called in the event of a termination signal from the tine kernel.
PyTine.allowed_users
In general, those users to be allowed WRITE permission to those settable properties which may have been registered can most easily be supplied via a users.csv file (see the section on Security). One can also supply a list of users directly from Python via this API call.
- Parameters
-
add (string or list of strings) will add those user names in the list to the current users access control list. remove (string or list of strings) will remove those user names in the list from the current users access control list.
- Returns
- the current users access control list.
If no parameters are supplied, the call simply returns the current list.
PyTine.allowed_addresses
In general, those network addresses to be allowed WRITE permission to those settable properties which may have been registered can most easily be supplied via a ipnets.csv file (see the section on Security). One can also supply a list of addresses directly from Python via this API call.
- Parameters
-
add (string or list of strings) will add those network addresses in the list to the current users access control list. remove (string or list of strings) will remove those network addresses in the list from the current users access control list.
- Returns
- the current network address access control list.
If no parameters are supplied, the call simply returns the current list.
PyTine.errorlist
The tine system error codes are available in Python as enumerated constants. One can obtain the entire list by simply calling this method without arguments. Otherwise the desired text or code can be obtained by passing one or the other parameter.
- Parameters
-
code is the error code for which the text message is desired. text is the text message for which the error code is desired.
PyTine.log
You can append server log file entries to the log file of choice via this method.
- Parameters
-
message is the log file entry to be appended to the log file file (optional) is the log file name. If ommitted, then 'fec.log' is assumed. The extenstion '.log' will be applied to any file name given. severity (optional) is a log severity from 0 (INFO) to 3(FATAL) which will be inserted into the log message. If omitted, INFO (informational) is assumed. tag (optional) is a tag string which will be inserted into the log message (files other than fec.log). If omitted then the severity will be used.
