XProc-Steps

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

p:exec

<p:declare-step type="p:exec">
   <p:input port="source" primary="true" sequence="true"/>
   <p:output port="result" primary="true"/>
   <p:output port="errors"/>
   <p:output port="exit-status"/>
   <p:option name="command" required="true"/> <!-- string -->
   <p:option name="args" select="''"/> <!-- string -->
   <p:option name="cwd"/> <!-- string -->
   <p:option name="source-is-xml" select="'true'"/> <!-- boolean -->
   <p:option name="result-is-xml" select="'true'"/> <!-- boolean -->
   <p:option name="wrap-result-lines" select="'false'"/> <!-- boolean -->
   <p:option name="errors-is-xml" select="'false'"/> <!-- boolean -->
   <p:option name="wrap-error-lines" select="'false'"/> <!-- boolean -->
   <p:option name="path-separator"/> <!-- string -->
   <p:option name="failure-threshold"/> <!-- integer -->
   <p:option name="arg-separator" select="' '"/> <!-- string -->
   <p:option name="byte-order-mark"/> <!-- boolean -->
   <p:option name="cdata-section-elements" select="''"/> <!-- ListOfQNames -->
   <p:option name="doctype-public"/> <!-- string -->
   <p:option name="doctype-system"/> <!-- anyURI -->
   <p:option name="encoding"/> <!-- string -->
   <p:option name="escape-uri-attributes" select="'false'"/> <!-- boolean -->
   <p:option name="include-content-type" select="'true'"/> <!-- boolean -->
   <p:option name="indent" select="'false'"/> <!-- boolean -->
   <p:option name="media-type"/> <!-- string -->
   <p:option name="method" select="'xml'"/> <!-- QName -->
   <p:option name="normalization-form" select="'none'"/> <!-- NormalizationForm -->
   <p:option name="omit-xml-declaration" select="'true'"/> <!-- boolean -->
   <p:option name="standalone" select="'omit'"/> <!-- "true" | "false" | "omit" -->
   <p:option name="undeclare-prefixes"/> <!-- boolean -->
   <p:option name="version" select="'1.0'"/> <!-- string -->
</p:declare-step>

Der <p:exec>-Step ermöglicht das Ausführen von externen Befehlen/Programmen auf der Kommandozeile des jeweiligen Betriebssystems. Die Inhalte am Input-Port (“source“) werden dem jeweiligen Aufruf übergeben. Das Programm, welches ausgeführt werden soll, wird durch die Option “command“ definiert. Die Option erwartet einen String, der den jeweiligen Befehlsaufruf enthält.

Unter der Option “args“ können Parameter angegeben werden, die das Verhalten des aufzurufenden Programms beeinflussen können. Ein klassischer Parameter ist zum Beispiel “-h“, was üblicherweise die Hilfe ausgibt. Mehrere Parameter werden durch ein Leerzeichen angegeben. Dieses Trennzeichen kann aber auch frei unter “arg-separator“ definiert werden. Durch die Option “cwd“ (Current Working Directory) kann der Benutzer den Pfad im Dateisystem angeben, wo sich das aufzurufende Programm befindet. Falls das Programm nicht gefunden werden kann, wird ein dynamischer Fehler ausgegeben. Wird diese Option nicht bedient, ist der Wert standardmäßig der Ort im Dateisystem, wo sich das auszuführende Programm befindet.

Die boolschen Optionen “source-is-xml“ und “result-is-xml“ teilen dem Prozessor mit, ob entweder die Eingabeinformationen oder Ausgabeinformationen XML-basiert sind oder nicht. Sind die Optionen “wrap-result-lines“ oder/und “wrap-error-lines“ auf “true“ gesetzt, so werden sämtliche Zeilen der Ausgabeinformationen mit einem <c:line>-Element umschlossen. Falls die Option “output-is-xml“ ebenfalls auf “true“ steht, wird ein dynamischer Fehler ausgegeben.

Die Option “path-separator“ gibt an, wie das Zeichen für eine Trennung von Pfaden im Dateisystem auszusehen hat. Kommt dieses Zeichen bei den Angaben von “command“, “args“ oder “cwd“ vor, so wird es durch das jeweilige Betriebssystem anhängige Pfadtrennungszeichen ersetzt.

Es stehen noch weitere Optionen zur Verfügung, welche genauere Angaben über die Beschaffenheit der einzulesenden Daten (z.B. welcher Art sie sind unter der Option “media-type“) und deren Verarbeitungsvorgaben (z.B. ob die Ausgabedaten eingerückt werden sollen unter “indent“) ermöglichen.

Da diese Optionen stark fallbasiert und für die primäre Bedeutung des Steps unerheblich sind, wird auf diese nicht weiter eingegangen.

Der Step verfügt weiterhin über drei Output-Ports. Der primäre Output-Port “result“ gibt das Ergebnis des ausgeführten Programmes aus. Im Output-Port “errors“ sind eventuell aufgetretene Fehler aufgelistet, also die Ausgaben, die auf der Kommandozeile auf die Standard-Fehlerausgabe geschrieben werden. Der Port “exit-status“ gibt immer einen Integer-Wert aus, der Rückschluss über das erfolgreiche Ausführen des Befehls gibt. So ist bei einem Erfolg der Wert <c:result>0</result> zu lesen und bei aufgetretenen Fehlern <c:result>1</c:result>.

Beispiel

Im folgenden Beispiel soll der Unix-Befehl “cat“ ausgeführt werden. Er soll das Dokument “filmsammlung.xml“ ausgeben.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step" version="1.0" name="testpipe">
   <p:input port="source">
      <p:document href="filmsammlung.xml"/>
   </p:input>
   <p:output port="result" sequence="true">
      <p:empty/>
   </p:output>
   <p:exec command="cat" result-is-xml="true" name="exec"/>
   <p:identity>
      <p:input port="source">
         <p:pipe port="errors" step="exec"/>
      </p:input>
    </p:identity>
    <p:store href="fehler.xml"/>
    <p:identity>
       <p:input port="source">
          <p:pipe port="exit-status" step="exec"/>
       </p:input>
    </p:identity>
    <p:store href="exit_status.xml"/>
    <p:identity>
       <p:input port="source">
          <p:pipe port="result" step="exec"/>
       </p:input>
    </p:identity>
    <p:store href="resultat.xml"/>
</p:declare-step>

Die drei Output Ports werden jeweils von einem <p:identity>-Step abgefangen und via <p:store> in eine Datei gespeichert. Das Resultat sieht folgendermaßen aus (Auszug):

<c:result>
 <FilmSammlung>
    <Film>
       <Titel>Star Wars: Episode IV - A New Hope</Titel>
       <Jahr>1978</Jahr>
       <Genre>SciFi</Genre>
[...]

Da der Prozess erfolgreich durchgeführt wurde, erfolgt keine Ausgabe am Port “errors“. Die erstellte Datei “fehler.xml“ hat also keinen Inhalt. Im Port “exit-status“ wird dementsprechend <c:result>0</c:result> ausgegeben (was dem Inhalt von “exit-status.xml“ entspricht).

Tipp der data2type-Redaktion:
Zum Thema XProc bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an: