Dim Introduction

DIM is a light weight communication protocoll based on publish/subscribe mechanism. Servers publish named services (commands or parameters) to a DIM name server. Clients can subscribe such services by name. They then get the values of the services subscribed from the server providing it. Whenever a server updates a service, all subscribed clients get the new value. Clients can also execute commands on the server side.

DIM provides the possibility to specify parameters and command arguments as primitives (I or L,X,C,F,D) or structures. The structures are described in a format string which can be retrieved by the clients (for parameters and commands) and servers (for commands):

   T:s;T:s;T:s ...

Thus a client can generically access parameter structures, but without semantical interpretation.
In addition to the data and format string one longword called quality is sent.

Generic GUI

When the number and kind of services of DIM servers often change it would be very convenient if a generic GUI would show all available services without further programming. It would be also very nice if standard graphical elements would be used to display certain parameters like rate meters. If we have many services it would be convenient to have a naming convention which allows to build tree structures on the GUI.

Naming conventions for generic GUI:

   /servernamespace/nodename[:nodeID]/[[applicationnamespace::]applicationname:]applicationID/[TYPE.module.]name
   /DABC/lx05/Control/RunState

We recommend to forbid spaces in any name fields. Dots should not be used except in names (last field). The generic GUI can handle only services from one servernamespace. For DABC and MBS this servernamespace is set to DABC.

For generic GUIs we need something similar to the EPICS records. This means to define structures which can be identified. How shall they be indentified? One possibility would be to prefix a type to the parameter name, i.e. rate:DataRate. Another to use the quality longword. This longword can be set by the server. One could mask the bytes of this longword for different information:

   mode (MSB)| visibility | type | status (LSB)
   mode: not used
   visibility: Bit wise (can be ORed)
     HIDDEN    = all zero
     VISIBLE   = 1  appears in parameter table
     MONITOR   = 2  in table, graphics shown automatically if type is STATUS, RATE or HISTOGRAM
     CHANGABLE = 4  in table, can be modified
     IMPORTANT = 8  in table also if GUI has a "minimal" view.
   type: (exclusive)
     PLAIN     = 0
     GENERIC   = 1
     STATE     = 2
     RATE      = 3
     HISTOGRAM = 4
     MODULE    = 5
     PORT      = 6
     DEVICE    = 7
     QUEUE     = 8
     COMMANDDESC= 9
     INFO      = 10
   status: (exclusive) 
     NOTSPEC     = 0
     SUCCESS     = 1
     INFORMATION = 2
     WARNING     = 3
     ERROR       = 4
     FATAL       = 5

Then we could provide at the client side objects for handling and visualization of such records.

Record ID=0: Plain

Scalar data item of atomic type

Record ID=1: Generic self describing

For these one would need one structure per number of arguments. Therefore the generic type would be rather realized by a more flexible text format, like XML. This means the DIM service has a string as argument which must be parsed to get the values.

XML schema similar to command descriptor.
Format: C

Record ID=2: State

   int severity (0=Success, 1=warning, 2=error, 3=fatal)
   char color (Red, Green, Blue, Cyan, Magenta, Yellow)
   char status name
Format: L:1;C:16;C:16

Record ID=3: Rate

   float value
   int displaymode (arc, bar, statistics, trend)
   float lower limit
   float upper limit
   float lower alarm
   float upper alarm
   char color (Red, Green, Blue, Cyan, Magenta, Yellow)
   char alarm color
   char units
Format: F:1;L:1;F:1;F:1;F:1;F:1;C:16;C:16;C

Record ID=4: Histogram

Structure must be allocated including the data field witch may be integer or double.

   int channels
   float lower limit
   float upper limit
   char axis lettering
   char content lettering
   char color (White, Red, Green, Blue, Cyan, Magenta, Yellow)
   int first data channel
Format: L:1;F:1;F:1;C:32;C:32;C:16;I(or D)

Record ID=10: Info

   int verbose (0=Plain text, 1=Node:text)
   char color (Red, Green, Blue, Cyan, Magenta, Yellow)
   char textline text
Format: L:1;C:16;C:128

Record ID=9: Command descriptor

This is an invisible parameter describing a command argument list. The service name must be correlated with the command name, e.g. by trailing underscore.

   char string describing arguments
Format: C

The descriptor string could be XML specifying the argument name, type, required and description. Question if default value should be given here for optional arguments. Example:

<?xml version="1.0" encoding="utf-8"?>
<command name="com1" scope="public" content="default">
<argument name="arg1" type="F" value="1.0" required="req"/>
<argument name="arg2" type="I" value="2" required="opt"/>
<argument name="arg3" type="C" value="def3" required="req"/>
<argument name="arg4" type="boolean" value="" required="opt"/>
</command>

The command definition can be used by the GUI to build input panels for commands. The scope can be used to classify commands, content should be set to default if argument values are default, values if argument values have been changed.

Commands

Commands have one string argument only. This leaves the arguments to semantic definitions in string format. To implement a minimal security, the first 14 characters of the argument string should be an encrypted password (13 characters by crypt plus space). The arguments are passed as string. A command structure could look like:

   char password[14]
   char argument string
Format: C

The argument string has the same XML as the command description. Thus, the same parser can be used to encode/decode the description (parameter) and the command. An alternate format is the MBS style format argument = value where boolean arguments are given by -argument if argument is true.

Setting parameters

If a parameter should be changable from the GUI, there must be a command for that. A fixed command SetParameter must be defined on the server for that. Argument is a string of form name=value. In the parameter table of the GUI one field can be provided to enter a new value and the command SetParameter is used to set the new value.

Generic Java GUI

A generic GUI has been implemented in Java. It processes all services found on the DIM name server. According the description above it does the following:

• Get list of commands and parameters and create objects for each
• Put parameters in a table
• Put commands in a command tree
• Create panels for rate meters, states, histograms, and infos

Application interfaces

Besides the generic part of the GUI it might be useful to have specific user panels as well, integrated in the generic GUI. This is provided by interface classes. A user may implement these interfaces in his own menues. He can connect his own call back functions to parameters, and a command function to be called when a command shall be executed. He may create his own panels for display using the graphical primitives like rate meters.

Application servers

Any application which can implement DIM services can be controlled by the generic GUI if it follows the protocol describesd above. The first application was DABC, the second one MBS.

-- HansEssel - 27 Feb 2008