Gerätemodelle mit dem neuen XML-Code-Generator erstellen

Die Änderungen im Gerätemodell auf einen Blick

• Einführung zusätzlicher XML-Elemente (<header>, <properties>, <additional>) um das Dokument zu strukturieren.
• Das XML-Element <eqmodversion> im Header ist neu.
• Die Default-Properties werden nun als Attribut angegeben. Inzwischen gibt es auch XML-Beschreibungen der Properties, die über die genannten URLs verwendet werden können auf der Applikationsseite.
• Alternativ ist es nun möglich, die einzelnen Teile der XML-Gerätebeschreibung auf mehrere Dateien zu verteilen. Diese werden vom neuen Code-Generator in ein komplettes XML-Dokument das alle einzelnen Teile enthält, überführt.
• Die Angabe des sourcename-Attributes im Namen des Gerätemodells ermöglicht es intern einen anderen Namen für die Verwendung in den Quellen anzugeben. Extern kann ein anderer Name für die jeweilige Variante des Gerätemodells verwendet werden, z.B. FG01 statt FG.

Hier ein einfaches Beispiel für die neue Struktur in einem Dokument, die Aenderungen sind rot markiert:

<?xml version="1.0" encoding="UTF-8"?>
<eqmod xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xi="http://www.w3.org/2001/XInclude" 
    xsi:noNamespaceSchemaLocation="http://www-acc.gsi.de/XMLSchema/xsd/eqmod.xsd">

<header>
    <name sourcename="EQMod">EQMod</name>
    <creator>Your Name</creator>
    <version>09.00</version>
    <eqmodversion>EQMOD_18</eqmodversion>
    <description>
        <short>EQMod device model</short>
        <long>EQMod device model</long>
    </description>
</header>

<properties>
    <property category="master">
        <name>INVERTER</name>
        <description>
            <short>Read/Write inverter switch.</short>
            <long>Read/Write inverter switch.</long>
        </description>
        <action access="device" medlock="none" type="write"/>
        <action access="free" medlock="none" type="read"/>
        <data>
            <value name="inverter" type="Float32"/>
        </data>
    </property>
    <complextype name="TLevels">
   <array name="start" length="16" type="Float32"/>
   <array name="end" length="16" type="Float32"/>
    </complextype>
</properties>

<additional>
    <defaultproperty>
        <extend impl="default-usrs-x86.cc" url2xml="https://www-acc.gsi.de/XML_Property_Descriptions/default-usrs.xml"/>
        <extend impl="therapy-usrs.cc" url2xml="https://www-acc.gsi.de/XML_Property_Descriptions/therapy-usrs.xml"/>
        <extend impl="therapy-master-usrs.cc" url2xml="https://www-acc.gsi.de/XML_Property_Descriptions/therapy-master-usrs.xml"/>
        <extend impl="therapy-slave-usrs.cc" url2xml="https://www-acc.gsi.de/XML_Property_Descriptions/therapy-slave-usrs.xml"/>
    </defaultproperty>

    <addinclude location="header" src="local">eqmod-helper.hh</addinclude>
    <addinclude location="usr" src="local">eqmod-helper.cc</addinclude>
</additional>
</eqmod>

Inklusion

Der neue XML-Code-Generator erlaubt das Inkludieren von XML-Fragmenten. Diese Fragmente enthalten jeweils Teile der bisherigen Gerätemodelldefinition. Ein übergeordnetes XML-Dokument, das den Namen des Gerätemodells trägt, inkludiert die zu verwendenden Teile. So ist es auf eine einfache Art möglich, z.B. die Property-Definitionen für verschiedene Varianten eines Gerätemodells auszutauschen.

Editieren und Validieren

Die XML-Dokumente für die Inklusion können mit dem XML-Editor Oxygen validiert werden.Der Editor wird im Blade-Center (in der asl7x-Umgebung) aufgerufen mit

> oxygen-xml&

Es stehen drei Floating-Licences zur Verfügung, d.h. der Editor kann zu einer Zeit von max. drei Benutzern verwendet werden.

Der bisher verwendete Exchanger XML Lite Editor unterstützt die Validierung von inkludierten XML-Fragmenten leider nicht.

Die Validierung der XML-Dokumente mit dem neuen Schema wird ausdrücklich empfohlen, um späteren Fehlern bei der Code-Generierung vorzubeugen. Validierbar sind alle XML-Dokumente außer den XML-Fragmenten, die lediglich wohlgeformt sein müssen. Es ist nicht möglich, diese einzeln zu validieren, da kein Schema angegeben werden kann. Es ist lediglich möglich, die Fragmente über das inkludierende XML-Dokument zu validieren mit dem richtigen Editor.

Umstellung der XML-Dokumente

Es gibt ein Beispiel, an dem man sich die neue Struktur der XML-Dokumente ansehen kann.

Das Beispiel für die neue Struktur ohne die Inklusion von XML-Fragmenten befindet sich hier:

/home/bel/matthies/lnx/tmp/xml_beispiel_2copy

Das Beispiel für die neue Struktur mit der Inklusion von XML-Fragmenten befindet sich hier:

/home/bel/matthies/lnx/tmp/xml_beispiel_2copy_include

C++-Code erstellen

Aufruf des C++-Code-Generators:

eqpact # zum Setzen der Umgebungsvariablen
usrgen Gerätemodellname # wenn XML-Inklusion nicht verwendet wird

Dabei wird neben den Adaptern und den Implementierungen der Properties auch eine Datei namens Gerätemodellname_complete.xml erzeugt. Diese enthält alle verwendeten XML-Fragmente.

Danach geht es weiter wie gewohnt...

Python Code-Generierung

Für die Python-Code-Generierung ist es ausreichend, dass ein komplettes XML-Dokument vorliegt das die neue Struktur einhält.Es gibt nun ein Skript, das anhand der Schema-URL erkennt welcher Python-Code-Generator aufgerufen werden muss.

Beispiel-Aufruf des Python-Code-Generators:

eqpact # zum Setzen der Umgebungsvariablen
pygen Gerätemodellname_complete.xml  # falls XML-Fragmente inkludiert wurden

oder
pygen Gerätemodellname.xml  # falls keine XML-Fragmente inkludiert wurden

Dabei wird wie vorher auch eine von devscr zu verwendende Datei namens GerätemodellnameEQMod.py erzeugt.

PythonCodeGenerator

Therapy-Properties fuer den PropHelper generieren

• Die Generierung der Python-Dateien aus therapy-usrs.xml, therapy-master-usrs.xml, therapy-slave-usrs.xml ist nur nach Aenderungen an den Therapy-Properties notwendig.
• Die erzeugten Therapy-Property-Python-Dateien muessen noch umbenannt werden in TherapyUsrs.py, TherapyMasterUsrs.py, TherapySlaveUsrs.py.
• Abzulegen sind die erzeugten und bearbeiteten Python-Dateien unter

webdavs://www-acc.gsi.de/dav/XML_Property_Descriptions/python

Der aktuellste Python-Code-Generator loest die unter //eqmod/additional/defaultproperty@url2xml angegebenen Erweiterungen auf und waehlt die entsprechenden Python-Dateien aus. Der Inhalt wird am Ende der gerade generierten Python-Datei angehaengt.

Nützliche URLs

Default-/Therapy-Documents

http://www-acc.gsi.de/XML_Property_Descriptions/default-usrs.xml

http://www-acc.gsi.de/XML_Property_Descriptions/therapy-usrs.xml

http://www-acc.gsi.de/XML_Property_Descriptions/therapy-master-usrs.xml

http://www-acc.gsi.de/XML_Property_Descriptions/therapy-slave-usrs.xml

Schema

Zur Validierung der Gerätemodelle

http://www-acc.gsi.de/XMLSchema/xsd/eqmod.xsd

Zur Validierung der Default-Property-Bescheibung

http://www-acc.gsi.de/XMLSchema/xsd/eqmod_default.xsd

Dokumente

• UmgebauterXMLCodeGenerator.pdf: Beschreibung des neuen XML-CodeGenerators