Zum Hauptinhalt springen

Ressourcen

Konfiguration von Ressourcen "resources"​

Es gibt bestimmte Funktionen, die über ihre dynamischen Funktionsparameter hinausgehend eine ergänzende statische Konfiguration benötigen. Dies sind z.B. Lookup-Tabellen oder auch Funktionen der Steuerungstechnik mit Registerbreiten oder Zählbereichen. Diese statische Konfiguration wird dem Funktionsaufruf als letzter Parameter in Form eines JSON-Objekts übergeben.

Die Konfiguration direkt am Funktionsaufruf ist für wenige einzelne Parameter noch sinnvoll, bei umfangreichen Konfigurationen, z.B. einer Klassierung oder eines Filters, können diese Ressourcen zur besseren Lesbarkeit des Formelsatzes in einen eigenen Bereich im math-Modul ausgelagert werden. Durch die Auslagerung kann die gleiche Konfiguration außerdem an verschiedenen Stellen im Formelsatz wiederverwendet werden.

Im Rahmen sogenannter Ressourcen ist es möglich,

  • Text für Konfiguration oder weitere Verarbeitung zu hinterlegen,
  • komplexe JSON-Objekte aus dem Formelsatz in einen hierfür vorgesehenen Bereich der Konfiguration auszulagern und
  • unter der Verwendung sogenannter Decoder einen Verarbeitungsprozess von beliebigen Daten (Text oder Binär) zu ermöglichen.

Diese Ressourcen werden EINMALIG bei Start des Messbetriebs initialisiert und können wie folgt konfiguriert werden

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {

    ...

    "resources": {
      "someTextResource": [

          < LINES OF TEXT >

      ],
      "someObjectResource": {

          < JSON STYLE Configuration >

      },
      "someDecodableResource": {
        "decoder": [

          < DECODERS >

        ],
        "value": "someInitialResourceValueString"
      }
      ...
    }
  }
}

Wir unterscheiden hierbei zwischen

  • Reine Text-Ressourcen, die den Text ähnlich dem math-Parameter als ein einziger String oder eine Liste von Strings (in Form eines JSON Arrays) spezifizieren. Die einzelnen Strings der Liste werden vor der Verwendung mittels '\n' verbunden. (im o.g. Beispiel someTextResource)

  • Objekt-Ressourcen, die darstellbare JSON Objekte zur Konfiguration von Funktionen im Formeltext bereitstellen (im o.g. Beispiel someObjectResource)

  • und dekodierbaren Ressourcen, die eine Folge von Verarbeitungsprozessen (Decodern) nacheinander auf einen initiales Datenpaket anwenden und das Ergebnis ebenfalls als Datenpaket bereitstellen (im o.g. Beispiel someDecodableResource). Dieses Datenpaket kann ein lesbarer Text aber auch ein binäres Datenpaket sein.

Zugriff auf und Umwandlung von Ressourcen​

Der Zugriff auf Ressourcen kann ausschließlich an der Stelle des letzten Parameters einer Funktion, die ein JSON-Objekt als Parameter akzeptiert, erfolgen

someJsonObjectAcceptingFunction( ... , {$ref:'someResource'} )

und liefert typischer Weise ein JSON-Objekt zurück. Ausnahme ist z.B. die Funktion lookup(), die aus der Ressource einen Textblock mit einem proprietären Datenkopf und einer Folge von Datenwerten zum Füllen der Tabelle erwartet.

Für den Fall, dass hingegen eine Stringrepräsentation erwartet wird, kann der Inhalt der Ressource wie folgt konvertiert werden

someStringAcceptingFunction( ... , sResource({$ref:'someResource'}), ... )

In jedem Fall ist es die Verantwortung des Anwenders, Daten so bereitzustellen, dass die verwendete Funktion oder der Formelsatz die Daten auch interpretieren und verarbeiten kann.

Beispiel: Bereitstellung einer Text basierten Konfiguation aus einer Text-Ressource:​

Im folgenden Beispiel wird die Konfiguration einer Lookup-Tabelle in Form eines proprietären Text-Formats erwartet. Die einzelnen Datenpunkte folgen den Kopfzeilen.

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someTextAcceptingFunction( ... , {$ref:'someText'} );",
    "resources": {
      "someText": [
          "IN kPa 0.0 0.167751 161"
        , "OUT l"
        , ""
        , "0"
        , "42.942"
        , "87.924"
        , "134.946"
        , "184.008"
        , "235.11"
        , "288.252"
        , "343.434"
        , "400.656"
        , "459.918"
        , "521.22"
        , "584.562"
        , "..."
      ],
      ...
    }
  }
}

Weitere Anwendungsbeispiele könnten sein:

  • Ein vorgegebener e-Mail Text zur Benachrichtigung, in dem im Formelsatz Textmarker durch konkrete Werte ersetzt werden.

  • Eine XML-Struktur für ein Subsystem, das damit für eine Messaufgabe konfiguriert werden muss.

Beispiel: Bereitstellung eines erwarteten JSON Objekts aus einer Objekt-Ressource​

In folgendem Beispiel wird eine statische Funktionskonfiguration in Form eines JSON-Objekts erwartet

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction( ... , { someParam: value } );"
  }
}

Dieses kann wie folgt durch eine Objektressource bereitgestellt werden

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction( ... , {$ref:'someObject'} );",
    "resources": {
      "someObject": {
        someParam: value
      },
      ...
    }
  }
}

Beispiel: Bereitstellung einer verarbeiteten Zeichenkette aus Ressourcen​

In folgendem Beispiel wird von der Funktion "someObjectAcceptingFunction" eine verarbeitete Zeichenkette (wie z.B. der Inhalt einer Datei oder eine dekodierte bzw. entpackte Repräsentation der Zeichenkette, siehe Abschnitt "decoder" für weitere Details) erwartet.

Dies kann durch eine dekodierbare Ressource wie folgt realisiert werden

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction({$ref:'someDecodableResource'});",
    "resources": {
      "someDecodableResource": {
        "decoder": [
          "someFirstDecoderStage someFirstFirstDecoderArgument ... someLastFirstDecoderArgument",
          ...,
          "someLastDecoderStage someFirstLastDecoderArgument ... someLastLastDecoderArgument"
        ],
        "value": "someInitialStringValue"
      }
    }
  }
}

Hierbei überführt zunächst die erste Decoderstufe "someDecoderStageFIRST" den initialen Stringwert der Ressource "someInitialValueString" in ein Zwischenergebnis und sämtliche folgenden Decoderstufen berechnen aus dem vorherigen Zwischenergebnis das folgende Zwischenergebnis, wobei die letzte Decoderstufe ihr Zwischenergebnis als Endergebnis in Form eines JSON Wertes vom Typ String zurückliefert.

Anmerkung: Soll dieses Ergebnis dort verwendet werden, wo ein String erwartet wird, muss - wie weiter oben beschrieben - dieses beim Zugriff mittels "sResource" konvertiert werden.

Decodierung von Ressourcen "decoder"​

Aufgabe eines Decoders ist es, einen Quellstring in einen Zielstring zu konvertieren.

Es stehen im Moment folgende Decoder zur Verfügung

  • file für das Einlesen einer Datei
  • base64 zur Decodierung eines base64-formatierten Strings
  • unzip zum Entpacken des Inhalts einer gzip-gepackten Datei

Darüberhinaus ein sehr flexibel einsetzbarer Decoder

  • system für den Aufruf von Systemprozessen

Decoder "file"​

Der "file" Decoder dient dem Einlesen einer Datei "/sdi/config/some/file/name", wie folgt

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file"
        ],
        "value": "some/file/name"
      }
    }
  }
}

Wird als "value" des Decoders ein relativer Pfad spezifiziert, adressiert dieser relativ zum smartCORE Konfigurationsverzeichnis /sdi/config/. Es kann jedoch auch ein absoluter Pfad spezifiziert werden.

Decoder "unzip"​

Zum Entpacken gzip-gepackter Dateien kann der "unzip" Decoder verwendet werden, z.B. wie folgt

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file",
          "unzip"
        ],
        "value": "some/compressed/file/name.gz"
      }
    }
  }
}

Decoder "base64"​

Zum Decodieren base64-codierter Dateien kann der "base64" Decoder verwendet werden, z.B. wie folgt

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file",
          "base64"
        ],
        "value": "some/base64/encoded/file.b64"
      }
    }
  }
}

Decoder "system"​

Für die Initialisierung von Ressourcen unter Verwendung beliebiger Systemaufrufe kann der Decoder "system" benutzt werden. Dieser unterstützt Aufrufparameter. Beispiel:

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someEditedResource'});",
    "resources": {
      "someEditedResource": {
        "decoder": [
          "file",
          "system sed -e 's/hello/world/g'"
        ],
        "value": "some/source/file"
      }
    }
  }
}