Condition Values and Texts - Requirements and Ideas

Note: In the meantime, based on the ideas of this article, a first prototype has been developed (see Service.Intern.ConditionCompiler)

Purpose

Provide control system-wide condition values and texts.

Software functions or methods usually return a so called error code when an error has occured. The term error code is a bit misleading, since a function may also return a success code if it has performed well (without error). So we use the more general term condition.

Conditions should be system-wide unique to allow their context-free handling.

Software deals best with condition values. Parsing text would be awful. Coding directly with numbers would be just as well. Values defined as constants must be supplied instead

Humans need condition texts which describe the condition. An "Error 404" on the operator's display explains nothing.

This text describes how system-wide unique condition values and their corresponding texts can be created and handled.

Simple Example

In principle, we need two types of key/value associations, one for dealing with condition values, one to display the corresponding text.

1. To code on the values, key is a constant designator, value is its (integer) value:

  - MX_POWEROFF  08154712
  - APP_OK       37421235
  - ...

2. To display the corresponding text, key is the (integer) value and value is the (english and german) text:

  - 08154712  "Power of magnet is off", "Magnet ist ausgeschaltet"
  - 37421235  "Normal successful completion", "Auftrag erfolgreich ausgeführt"
  - ...

Given this, a service, e.g. a FESA property, may generate an exception like

  throw(FesaException(MX_POWEROFF));

and an application could handle such an exception

  catch(FesaException e) {
    int condVal = e.value();
    if (condVal == MX_POWEROFF) {
      // ignore this specific error here
    }
    else {
      string condTxt = condLib.getTxt(condVal, LANG_EN);
      // or 'string condTxt = condLib.getTxt(condVal);' using the Locale
      display.writeTo(condTxt);
      ...

thereby dealing with condition value and text.

Creation of Conditions

• To handle condition texts, key/value pairs are necessary that associates condition numbers with (english and german) texts.

• Condition values must be unique within the whole control system.

• Software must not deal directly with condition value numbers but with condition value symbols (constant designators) instead.

• A source key/value pair must be used to generate as destination two key/value pairs. One pair associates constants with numbers. The other associates numbers with texts.

  Example key/value pairs:

         Source ident/text pair:
           Key:   "POWEROFF"
           Value: { EN: "Power of magnet is off",
                    DE: "Magnet ist ausgeschaltet" }
  
         Destination symbol/value pair:
           Key:   MX_POWEROFF
           Value: 08154712
  
         Destination value/text pair:
           Key:   08154712
           Value: { EN: "Power of magnet is off",
                    DE: "Magnet ist ausgeschaltet" }

• A source may be a file that contains several ident/text pairs (see e.g. Appendix A) or an application with a GUI that allows interactive definition of ident/text pairs.

• A re-generation using a source ident/text pair where the ident is already existing must assure that the newly generated associated number (e.g. 08154712) is exactly the same as with the previous generation. The texts may change.

• For ident/text pairs with a new ident that hasn't existed yet, a new associated number must be generated that lies within the facility's valid range. See Appendix B.

• To be suitable for all intended programming languages, generated symbols of symbol/value pairs must be case-insensitive and therefore converted to uppercase.

• Condition texts may contain placeholders which will be replaced by parameters supplied by the software module that generates the condition.

  E.g.:

         Source:
           Ident: "CURR_INVALID"
           Text:  { "Current set value %fA for magnet %s invalid",
                    "Strom-Sollwert %fA für Magnet %s ungültig" }
  
         Actual condition text:
           MX-E-CURR_INVALID, Current set value 47.11A for magnet TK1MU1 invalid

• Condition numbers must be of 32bit integer type. Condition symbols and condition texts must be UTF8-encoded strings.

• Formats of the symbol/value pair destinations.
  • Java:
    • public static int MX_POWEROFF = 08154712;
    • java source file (*.java)
  • C/C++:
    • static const int32_t MX_POWEROFF = 08154712;
    • header file (*.h)
  • Python:
    • MX_POWEROFF = 08154712
    • python file (*.py)
  • Fortran 77:
    • parameter (MX_POWEROFF = 08154712)
      or while used together with "implicit none"
      implicit none
integer MX_POWEROFF
parameter (MX_POWEROFF = 08154712)
    • fortran77 file (*.f)
  • Fortran 90:
    • integer, parameter :: MX_POWEROFF = 08154712
    • fortran90 file (*.f90)

• To assign a set of conditions to a certain software module, conditions must be grouped into facilities. A facility must be identifiable by a name and by a number.

  Using the example above:

         Source:
           Facility name:   "MX"
           Facility number: 1069

  Facility names should be an abbreviation of the software module's name or an acronym, e.g. 'MX' for pulsed magnets FEC software. They should be not longer than five characters.

  Facility names and numbers will be centrally managed by CSCO to assure their system-wide uniqueness.

• 2000 different facilities must be possible. Per facility 4000 conditions must be possible.

• A symbol of a symbol/value pair should be composed out of the ident of the source ident/text pair prefixed with the facility name seperated by an underscore.

  Using the example above:

         Source ident:
           Key: "POWEROFF"
  
         Destination symbol:
           Key: "MX_POWEROFF"

  Alternative prefixes that include the seperator may be specified for backward compatibility but are strongly discouraged for new facilities. See the <altPrefix> tag in the XML proposal in Appendix A.

• A special symbol/value pair must be generated for the facility number. It must be

         Key:   "<facility-name>_FACILITY_NUMBER"
         Value: <facility-number>

  e.g. for C++

         static const int32_t MX_FACILITY_NUMBER = 1069;

  No value/text pair will be generated for this entry.

• A condition must be associated with a severity level. Levels may be

        S = Success
        I = Information
        W = Warning
        E = Error
        F = Fatal

• Condition numbers of Success or Information severity level must be odd, the other three must be even.

• An enum representation for the five severity levels must be defined.

        S = Success     = 1
        I = Information = 3
        W = Warning     = 0
        E = Error       = 2
        F = Fatal       = 4

• The full format of a condition text retrieved from a value/text pair must have the following format:

         <FACILITY-NAME>-<L>-<IDENT>, <Text>

  (where <L> is the severity level). An API should provide methodes to retrieve a single text element or a user-defined subset of the text elements.

• An API should provide methods to return
  • the facility number and
  • the severity level (as integer value) directly from a given condition number.

Backward Compatibility and Third Party Systems

• Compatibility to the 'Condition Messages' of the existing GSI control system:
  • New (Java) client applications will have to deal with (at least) accesses to devices still controlled by the old GSI Device Access system. Those devices return completion codes and exceptions containing old-style condition messages.
  • Probably, there will also be the other way round: Existing GSI (operating) applications will have to deal with FESA-based devices. Those devices will return new-style condition numbers.
  • In principle, the compatibility problem arises every time when a GSI software component (of the existing control system) must communicate with a software component of the future FAIR control system.
  • So for old input sources (*.msg files), the new condition generation system must calculate the same condition numbers as the existing system when the inputs (facility, severity, ident) to both systems are the same.

• How to deal with existing condition codes of third party systems?
  • Linux/OS, e.g. I/O Error: Error values are defined and fix.
    Solution:
    • Create a condition OS_ERROR which accepts an integer parameter
    • When a Linux error occurs, return the OS_ERROR condition with the Linux errno as parameter.
    • Use strerror(errno) on the client side to get the describing text. (Caution: needs Linux on client side!)
    • Alternatively, the OS_ERROR parameter may be a string. Then the text can be generated on the server side and sent to the client.
  • Oracle user errors: Errors are user-defined but must lie within a predefined range.
    Solution (???):
    • Create in parallel Oracle errors and corresponding FAIR conditions.
    • Map Oracle errors to FAIR conditions.

Usage of Conditions

• It must be possible to integrate the exchange of such information within the control system. The information must contain:
  • key
  • parameter values (for replacing the placeholders)
  • eventually a default text
  • eventually further information (underlying messages, in case of exceptions e.g. root cause or a list of this information?)

• Condition symbols or values may be used
  • within exceptions
  • as return value
  • eventually as (last) parameter of method signatures
  • in the Messaging System
    • ??? specially defined message structure for the exchange of texts

Appendix A: Proposal for an XML Source File

  <conditions
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www-acc.gsi.de/XMLSchema/xsd/v03/conditions.xsd">

    <version>1.0.0</version>               <!-- ???: Oder in conditions.xsd? -->

    <title>MX Conditions</title>
    <facilityName>MX</facilityName>        <!-- system-wide unique -->
    <facilityNumber>3742</facilityNumber>  <!-- system-wide unique -->
    <altPrefix>MX$_</altPrefix>            <!-- optional, not recommended, unique -->

    <severities>
      <severity>
        <level>SUCCESS</level>
        <condition>
          <ident>OK</ident>
          <text_de>Auftrag erfolgreich ausgeführt</text_de>
          <text_en>Normal successful completion</text_en>
          <description_de>...</description_de>  <!-- optional -->
          <description_en>...</description_en>  <!-- optional -->
        </condition>
        <condition>
          <ident>ABC</ident>
          <text_de>Foo bar</text_de>
          <text_en>Fuh-Stab</text_en>
        </condition>
      </severity>
      <severity>
        <level>INFORMATION</level>
        <condition>
          ...
        </condition>
      </severity>
      ...
      <severity>
        <level>FATAL</level>
        ...
      </severity>
    </severities>
  </conditions>

Die description Tags hatten wir mal erfunden mit der Idee, dass es hilfreich sein kann, dem Operateur weitergehende Informationen zu einer Fehlermeldung zu liefern. Also: Es wird ein Fehler angezeigt, der Operateur klickt drauf und bekommt die ausführliche Beschreibung. Beispiel:

  <level>WARNING</level>
  <condition>
    <ident>CurrS_Power</ident>
    <text_de>Gerät ist nicht eingeschaltet</text_de>
    <text_en>Power of device is off</text_en>
    <description_de>
      Der gewünschte Sollwert wurde im Dualport-RAM abgelegt,
      konnte aber am Gerät nicht eingestellt werden, da
      dieses ausgeschaltet ist oder gerade einschaltet.
      Der interne Zustand der Software ist 'power off' oder
      'power sequence'. Der Sollwert wird eingestellt, sobald
      das Gerät eingeschaltet ist.
    </description_de>
    <description_en>
      ...dito...
    </description_en>
  </condition>

Appendix B: Format of a Condition Number

  Bits     Meaning
  ------------------------
  31..28   reserved (= 0)
  27       = 1
  26..16   facility number (0..2047)
  15       = 1
  14...3   condition number (0..4095)
   2...0   severity (0..7)

open issues

  - parameter placeholders syntax
    - %s -> string
    - %i -> integer
    - %f -> float
    - %x -> hex(integer)
    - ...
    oder anders?
  - one repository for all conditions (DB):
    - Inhalt: Tabelle mit (mind.) 4 Spalten: 1 - "MX_POWEROFF",
      2 - 08154712, 3 - "Power of magnet is off",
      4 - "Magnet ist ausgeschaltet";
      plus Facility name and facility number (an alternate prefix)
    - extrakt einer XML-Datei, die alle Conditions einer Facility
      enthält; editieren; re-insert. XML format see appendix A.
    - Input:
      - aus XML-File
      - via GUI
      - einmalig: aus msg-File
    - Output:
      - Header-Datei pro Facility (mx-conditions.h, .java, ...)
      - Library; _eine_ dicke oder auch pro Facility?                   ???
        - conditions.so, .jar, ...
        - mx-conditions.so, dgx-conditions.so, ...

  - retrieving texts
    - not from DB
    - but from ...conditions.so, ...conditions.jar, ...

  - Generierung mit Maven                                               ???
    - Eine laufende DB erforderlich? Geht so nicht!
    - Was macht Cosylab, das auch Conditions generieren
      möchte?
      - für FESA: dann wird nur die Header-Datei benötigt,
      - und für Anwendungen: dann auch die Bibliothek!
      Statt DB entspr. Dateien?

  - Übergangslösung: 'msgc' und *.msg benutzen.