Modul XML

Das Modul XML stellt ein paar Routinen zum Umgang mit XML bereit.

#xml_clearall

#xml_clearall löscht die Liste der geparsten XMLs

Parameter

keine

Beispiel

#xml_clearall

#xml_parse

#xml_parse parst ein XML, das ist die Voraussetzung für den Einsatz der weiteren Routinen.

Es handelt sich dabei um eine nummerierte Prozedur. #xml_parse parst in die ersten XML-Daten, #xml_parse2 in die zweiten und so weiter.

Parameter

• cnd ("condition") - wenn Y, dann wird die Prozedur ausgeführt; default Y, Funktionen werden ersetzt
• xml - der Text, der geparst werden soll; Funktionen werden ersetzt

Beispiel

#http_request   y=post    cy="application/xml"   request=$TEXT(1)   response=resp   se=Y   acc=application/xml     $CODE$
#cout   c=$VAR(resp)
#xml_parse   xml=$VAR(resp)
#xml_loop   n=xml   er=c_test2_line   pfx=customer   path=soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse

#xml_loop

#xml_loop durchläuft die verschiedenen Items im Array eines geparsten XML und führt dabei jeweils die in er genannte Subroutine aus. Auf die einzelnen Daten des XML kann mit $XML_DATA zugegriffen werden.

Es handelt sich dabei um eine nummerierte Prozedur. #xml_loop loopt durch die ersten XML-Daten, #xml_loop2 durch die zweiten und so weiter.

Parameter

• cnd - ("condition") Die Prozedur wird nur dann ausgeführt, wenn das Statement in cnd Y ergibt. Default ist Y, Funktionen werden ersetzt
• db - ("database") Name der Datenbank, in der eine Transaktion gestartet wird, wenn ert = Y ist.
• er - ("each row") Das Kommando, das für jede Zeile der Datenmenge aufgerufen wird. Funktionen werden ersetzt.
• ern - ("each row no") Das Kommando, das für jede Zeile der Datenmenge aufgerufen wird. Funktionen werden nicht ersetzt. Wenn ern einen Wert hat, bleibt er unberücksichtigt. Üblicherweise wird er verwendet.
• ert - ("each row transaction") Wenn Y, wird für jede Zeile der Datenmenge eine eigene Transaktion gestartet und nach der Abarbeitung des Kommandos wieder geschlossen.
• m - ("maximum") Es wird maximal für die Anzahl der angegebenen Zeilen das in er angegebene Kommando ausgeführt. Dieser Parameter wird häufig dazu verwendet, während der Entwicklung mit einer geringen Zahl von Datensätzen zu arbeiten.
• nex ("no exception") - Wenn Y, wird bei Exceptions in er nicht abgebrochen, sondern mit dem nächsten Datensatz fortgesetzt. Default N, Funktionen werden ersetzt.
• n - Name der Datenmenge, wird benötigt, um mit $XML_DATA() auf die einzelnen Felder zugreifen zu können.
• path - Pfad im XML, der zu dem Array führt, durch das geloopt werden soll; Funktionen werden ersetzt
• pfx ("prefix") - Name der einzelnen Array-Elemente; Funktionen werden ersetzt
• sep ("separator") - Das Trennzeichen, mit dem die Elemente im Parameter path getrennt sind; Funktionen werden ersetzt, default ist der Punkt

Beispiel

siehe #xml_parse

#xml_gav

#xml_gav ("GetArrayValues") durchläuft die verschiedenen Items im Array eines geparsten XML und ermittelt dabei die Daten, die im Format name/value vorliegen.

Es handelt sich dabei um eine nummerierte Prozedur. #xml_loop loopt durch die ersten XML-Daten, #xml_loop2 durch die zweiten und so weiter.

Parameter

• cnd - ("condition") Die Prozedur wird nur dann ausgeführt, wenn das Statement in cnd Y ergibt. Default ist Y, Funktionen werden ersetzt
• f_xxx - Name der Variable oder Nummer des Values, in die das jeweilige Ergebnis geschrieben werden soll; xxx ist das Namen-Feld im XML, Funktionen werden ersetzt
• name - Bezeichnung des Namen-Feldes; default ist name, Funktionen werden ersetzt
• path - Pfad im XML, der zu dem Array führt, durch das geloopt werden soll; Funktionen werden ersetzt
• pfx ("prefix") - Name der einzelnen Array-Elemente; Funktionen werden ersetzt
• sep ("separator") - Das Trennzeichen, mit dem die Elemente im Parameter path getrennt sind; Funktionen werden ersetzt, default ist der Punkt
• value - Bezeichnung des Value-Feldes; default ist value, Funktionen werden ersetzt

Beispiel

Es sollen die Adressdaten aus folgendem XML geholt werden:

<contact>
  <email>test@gmail.com</email>
  <created>2022-07-18 07:57:51.0</created>
  <updated>2023-04-05 11:39:57.0</updated>
  <id>12345</id>
  <standard_fields>
    <field>
      <name>ADDRESS</name>
      <value>Bismarckstraße 17</value>
    </field>
    <field>
      <name>CITY</name>
      <value>Berlin</value>
    </field>
    <field>
      <name>FIRSTNAME</name>
      <value>Michael</value>
    </field>
    <field>
      <name>LASTNAME</name>
      <value>Mustermann</value>
    </field>
    <field>
      <name>SALUTATION</name>
      <value>Herr</value>
    </field>
    <field>
      <name>ZIP</name>
      <value>12345</value>
    </field>
  </standard_fields>
  <custom_fields>
    <field>
      <name>easter_calendar_prize_3</name>
      <value>20</value>
    </field>
  </custom_fields>
</contact>

Die Werte werden in die Variablen adresse, ort, plz, vorname und nachname geschrieben; die Parameter name und value müssen hier nicht geschrieben werden, da sie im XML nach den Standard-Werten benannt sind.

#xml_gav   path=contact.standard_fields   pfx=field   f_address=adresse   f_city=ort   f_zip=plz   f_firstname=vorname   f_lastname=nachname
#coutl $VAR(vorname) $VAR(nachname)

#xml_chg

Ändert einen Wert in einem geparsten XML.

Es handelt sich dabei um eine nummerierte Prozedur. #xml_chg ändert in den ersten XML-Daten, #xml_chg2 in den zweiten und so weiter.

Parameter

• cnd ("condition") - wenn Y, dann wird die Prozedur ausgeführt; default Y, Funktionen werden ersetzt
• path - Pfad im XML, der zu dem XML-Feld führt
• sep ("separator") - Das Trennzeichen, mit dem die Elemente im Parameter path getrennt sind; Funktionen werden ersetzt, default ist der Punkt
• z - Wert, der in das XML-Feld geschrieben wird; Funktionen werden ersetzt

Beispiel

#xml_parse   xml=$VAR(resp)
#var_set   n=cp   z=soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse.customer
#xml_chg   path=$VAR(cp).firstName   z=$PVAL(grid,firstName,looprow)
#xml_chg   path=$VAR(cp).lastName   z=$PVAL(grid,lastName,looprow)
#xml_chg   path=$VAR(cp).contactData.phone   z=$PVAL(grid,contactData.phone,looprow)

Das Beispiel zeigt einen Ausschnitt aus einem Save-Kommando: Zunächst werden die Daten über einen REST-Server geholt (das ist noch nicht im Beispiel-Code), geparst, dann werden einzelne Felder durch die Daten im Grid ersetzt, danach (auch wieder nicht im Beispiel-Code) werden die Daten zum REST-Server zurück geschrieben. Um die #xml_chg-Prozeduren übersichtlicher zu halten, wird der wesentliche Teil des Pfades in der Variablen cp gespeichert.

$XML_TEXT

Die Funktion $XML_TEXT erzeugt aus einem geparsten XML wieder einen Text.

Parameter

1. Nummer des geparsten XML
2. Typ
   1. flat - einfach nur der Text ohne Zeilenumbruch
   2. frm - formatiert
3. optional: Pfad des Teils des geparsten XML, das in einen Text gewandelt werden soll; ohne diesen Parameter wird das gesamte geparste XML in einen Text gewandelt.
4. optional: Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt

Beispiele

#text               $XML_TEXT(1,frm,soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse.customer)

$XML_VALUE

$XML_VALUE gibt einen konkreten Wert aus einem geparsten XML zurück

Parameter

1. Nummer des geparsten XML
2. Pfad zum gewünschten Wert
3. optional: Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt

Beispiel

#cout   c=$XML_VALUE(1,soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse.customer.firstName)

$XML_DATA

$XML_DATA greift auf die einzelnen Felder eines Elementes eines XML-Arrays zu, durch das mit #xml_loop geloopt wird.

Parameter

1. Name der XML-Loop (parameter n in #xml_loop)
2. Pfad; bei Felder, die direkt unter der Loop-Ebene liegen, nur der Feldname, ansonsten ein entsprechender Pfad, siehe zweites Beispiel.
3. optional: Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt

Beispiele

#cout   c="$XML_DATA(xml,firstName) $XML_DATA(xml,lastName)"
#cout   c="$XML_DATA(xml,contactData.phone)"

$XML_DATATEXT

$XML_DATATEXT ermittelt das XML innerhalb einer #xml_loop-Schleife. Das kann dazu verwendet werden, dies seinerseits zu parsen. (Zum Beispiel, weil dann wieder geloopt werden muss.)

Parameter

1. Name der XML-Loop (parameter n in #xml_loop)
2. Typ (flat oder frm)
3. Pfad; bei Felder, die direkt unter der Loop-Ebene liegen, nur der Feldname, ansonsten ein entsprechender Pfad, siehe zweites Beispiel.
4. optional: Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt

Beispiel

#xml_parse2   xml=$XML_DATATEXT(xml,frm)
#xml_loop2   n=sf   er=c_osterkampagne_standardfields   pfx=field   path=contact.standard_fields

$XML_LFR

$XML_LFR den ersten Wert innerhalb einer Loop, der einem Regex-Ausdruck entspricht. Dies wird primär für den Fall verwendet, dass in einer Loop nur ein Wert erwartet wird, der dem Regex-Kriterium entspricht. Nach dem ersten gefundenen Wert wird die interne Schleife abgebrochen und der gefundene Wert als Funktionsergebnis zurückgegeben.

Parameter

1. Nummer des geparsten XML
2. Pfad zum gewünschten Wert
3. Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt
4. Prefix
5. Feldname
6. optional: Regex-Statement

Beispiel

#cout   c=$XML_LFR(1,$VAL(1)price,.,discountAmounts,code,[A-Z]{3}\d{4})

$XML_VALEX

Die Funktion $XML_VALEX ermittelt, ob ein bestimmter Wert existiert ("value exists").

Parameter

1. Nummer des geparsten XML
2. Pfad zum gewünschten Wert
3. Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt
4. Prefix
5. Feldname
6. Wert, alternativ das Regex-Statement
7. Typ
   1. ic - ignore case (Groß- und Kleinschreibung wird beim Vergleich ignoriert)
   2. regex - Der Wert-Parameter wird als Regex-Statement verwendet
   3. alles andere - Stringvergleich unter der Berücksichtigung der Groß- und Kleinschreibung
8. Rückgabewert Yes, default Y
9. Rückgabewert No, default N

Beispiel

#text <soap:Envelope xmlns:soap="
...
#text <customer>
...
#text <toDelete>false</toDelete>
#text <characteristics>
#text <characteristics>
#text Rollator
#text </characteristics>
#text <characteristics>
#text Gluten
#text </characteristics>
#text <characteristics>
#text Ernährung
#text </characteristics>
#text </customer>
...

#xml_parse   xml=$TEXT(1)
#val_set   n=1   z=soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse.customer
#cout   c="Gluten: $XML_VALEX(1,$VAL(1),.,characteristics,code,gluten,ic)"
#cout   c="Gluten nic: $XML_VALEX(1,$VAL(1),.,characteristics,code,gluten)"
#cout   c="Rollator: $XML_VALEX(1,$VAL(1),.,characteristics,code,Rollator,ic)"
#cout   c="Unsinn: $XML_VALEX(1,$VAL(1),.,characteristics,code,unsinn,ic)"

$XML

$XML ermittelt einen Teil eines XMLs, das im Gegensatz zu den anderen Funktionen im Modul XML nicht geparst sein muss. Statt der Nummer eines geparsten XML wird der Name einer Variable angegeben, in der sich das XML befindet.

Parameter

1. Name der Variable, in der sich das XML befindet
2. Pfad; bei Felder, die direkt unter der Loop-Ebene liegen, nur der Feldname, ansonsten ein entsprechender Pfad, siehe zweites Beispiel.
3. optional: Wenn Y, wird die Groß- und Kleinschreibung bei der Suche im XML ignoriert.
4. optional: Trennzeichen, mit dem die Elemente im Pfad getrennt werden; default ist der Punkt

Beispiel

#http_request   y=post    cy="application/xml"   request=$TEXT(1)   response=resp   se=Y   acc=application/xml     $CODE$
#val_set   n=1   z=soap:Envelope.soap:Body.ns2:searchCustomerResponse.searchCustomerResponse.customer.
#cout   c="$XML(resp,$VAL(1)firstName)"