Script-Elemente und Syntax

Die Elemente und die Syntax der Automation Engine scripting language sind konsistent mit anderen Scriptsprachen, die Sie kennen. Schreiben Sie Anweisungen mit Befehlen, Funktionen und Variablen und fügen Sie Kommentare hinzu. Sie können die Automation Engine scripting language mit Befehlen Ihrer Zielbetriebssysteme und Anwendungen kombinieren. Siehe Mit dem Script-Editor arbeiten für Informationen zur Syntaxhervorhebung und -vervollständigung.

Script-Anweisungen

Anweisungen sind das wesentliche Element in Scripts und enthalten in der Regel ein Kommando. Befolgen Sie diese Regeln, wenn Sie Script-Anweisungen schreiben:

• Alle Anweisungen beginnen mit einem Doppelpunkt.
• Die maximale Länge der Anweisung beträgt 1024 Zeichen, einschließlich Leerzeichen.

Richtig formatierte Anweisungen werden im Script-Editor blau dargestellt.

Beispiel

Die folgende Script-Anweisung zeigt den Text "Automation Engine" im Aktivierungsreport an, wenn das Objekt verarbeitet wird:

:PRINT "Automation Engine"

Wenn Sie eine Anweisung in der nächsten Zeile fortsetzen müssen, schreiben Sie einen Unterstrich am Ende der Zeile und beginnen Sie die nächste Zeile mit einem Doppelpunkt.

Beispiel

Die folgende Anweisung wird als einzelne Script-Anweisung interpretiert:

:SCRIPT LINE SCRIPT LINE SCRIPT LINE SCRIPT LINE SCRIPT LINE_

:CONTINUED SCRIPT LINE

Script-Funktionen

Funktionen ermöglichen es Ihnen, Daten im System zu manipulieren. Script-Funktionen liefern Rückgabewerte, was sie von Script-Anweisungen unterscheidet.

Befolgen Sie diese Regeln, wenn Sie Script-Funktionen verwenden:

• Beginnen Sie die Zeile mit einer Script- Anweisung. Beginnen Sie eine Zeile nicht mit einer Script-Funktion.
• Fügen Sie nur eine Funktion pro Zeile hinzu.

Richtig formatierte Funktionen werden im Script-Editor rot dargestellt.

Syntax

Die folgende Anweisung definiert den Wert einer Variablen als die Summe zweier Zahlen.

:SET &SUM# = ADD(2,2)

Parameter

• :SET
  Anweisung, die die Variable definiert
• &SUM#
  Variable
• ADD
  Funktion, die die Werte addiert, die sich innerhalb der Klammern befinden

Viele Script-Funktionen können alleine verwendet werden, aber es gibt auch Funktionen, die nur in Kombination mit anderen Script-Elementen funktionieren bzw. Sinn ergeben.

Beispiel

Die Script-Funktion PREP_PROCESS_FILE erzeugt eine Datensequenz aus dem Inhalt einer Textdatei. Der Rückgabewert ist ein Handle. Die Funktion GET_PROCESS_LINE liest die einzelnen Zeilen der Textdatei, benötigt jedoch den mit PREP_PROCESS_FILE abgerufenen Handle.

Rückgabewerte von Funktionen

Rückgabewerte können einzelne Zeichen, Strings oder Zahlen sein. Die Zahlen werden immer mit 16 Ziffern und führenden Nullen geliefert. Die Nullen haben keinen Einfluss auf die weitere Verarbeitung der Zahl (z. B. in arithmetische Operationen).

Syntax

Die folgenden Script-Zeilen setzen eine Script-Variable auf eine Summe von zwei Werten und zeigen die resultierende Zahl an.

:SET &SUM# = ADD(2,2)

:PRINT &SUM#

Parameter

• :SET
  Anweisung, die die Variable definiert
• &SUM#
  Variable
• ADD
  Funktion, die die Werte in Klammern addiert
• :PRINT
  Gibt den Wert im Aktivierungsreport aus

Dies ist das Ergebnis, das angezeigt wird:

0000000000000004

Tipp: Sie können eine Script-Funktion verwenden, um führende Nullen in der Ausgabe zu entfernen. Weitere Informationen finden Sie unter FORMAT.

Rückgabewerte können auch eine Fehlernummer enthalten. Weitere Informationen zu Rückgabewerten finden Sie in der Beschreibung des jeweiligen Script-Elements unter Automation Engine Script-Verweis und Fehlerbehandlung in Scripts.

Script-Variablen

Mit Script-Variablen können Sie Werte in Scripts definieren und übergeben. Script-Variablen können Zahlen, Strings, Datumsreferenzen oder Uhrzeiten enthalten. Der Wert der Variablen gilt bis das Script verarbeitet wurde. Richtig formatierte Variablen werden im Script-Editor violett dargestellt.

Definieren und Setzen von Variablen in Scripts

Verwenden Sie die folgenden Script-Anweisungen, um Variablen in Ihren Scripts zu deklarieren und ihnen Werte zuzuweisen:

• :DEFINE
  Definiert eine Variable und deklariert den Datentyp
  Weitere Informationen finden Sie unter Datentypen von Script-Variablen.
• :SET
  Weist den Wert einer Variablen zu

Hinweis: Der Wert, den Sie einer Script-Variablen zuweisen, ist nicht begrenzt. Einige Script-Elemente, wie z. B. :ADD_COMMENT, kürzen den Wert, weil das Zielfeld ein Limit hat.

Weitere Informationen: Script-Elemente für Variablen und VARA-Objekte.

Beispiele

Die folgende Anweisung deklariert eine Variable als String.

: DEFINE   &FILE#, string

Die folgenden Script-Zeilen deklarieren die Variable als String und definieren den Text in diesem String.

: DEFINE   &FILE#, string
: SET   &FILE# = "temp.txt"

: DEFINE &STRING#, string

:DEFINE &SIGNED#, signed

:DEFINE &UNSIGNED#, unsigned

:DEFINE &FLOAT#, float

: SET &STRING#= "1234abc"
:SET &SIGNED#= -5
:SET &UNSIGNED#= 24
:SET &FLOAT#= -0.50

Script-Variablennamen

Befolgen Sie die Regeln für die Benennung von Variablen, wenn Sie Script-Variablen definieren. Weitere Informationen finden Sie unter Variablennamen.

Variablennamen sind kontextspezifisch, sodass Sie mehrere Variablen in verschiedenen Objekten mit gleichem Namen definieren können. Die Voraussetzung dafür ist, dass sie in separaten Kontexten verwendet werden. Variablen können nicht die gleichen Anfangsbuchstaben innerhalb desselben Kontextes verwenden.

Tipp: Beenden Sie Variablennamen mit einem Hash-Zeichen (#), um den Namen zu begrenzen und Probleme mit ähnlichen Variablennamen zu vermeiden. Beispielsweise können die Variablen &VALUE# und &VALUES# im gleichen Kontext verwendet werden. Dies ist mit &VALUE und &VALUES nicht möglich.

Arrays

Verwenden Sie Arrays, um mehrere verschiedene Werte in einer Variablen zu speichern. Deklarieren Sie eine Variable als Array, indem Sie Array-Parameter in die :DEFINE-Anweisung aufnehmen. Auf die einzelnen Werte im Array kann über einen Index zugegriffen werden.

• Schreiben Sie Arrays als Variablennamen, gefolgt von eckigen Klammern [].
• Geben Sie den Index an, indem Sie eine Zahl in die Klammern schreiben.
• Array-Namen können bis zu 24 alphanumerische Zeichen lang sein.
• Ein Array kann bis zu 99999 Elemente enthalten.

Verwenden Sie die Script-Anweisung ON_ERROR, um die Fehlerbehandlung in das Script einzubinden, wenn das Array einen ungültigen Index verwendet. Wenn das Script einen ungültigen Index enthält, wird standardmäßig eine Fehlermeldung sowohl in das Log als auch in den ACT-Report geschrieben, aber die Verarbeitung wird nicht angehalten. Weitere Informationen finden Sie unter:ON_ERROR.

Beispiel

Das folgende Script deklariert eine Variable als Array mit 10 Werten und gibt den Wert des Index 5 an:

:DEFINE&ARR#, unsigned, 10

:SET&ARR#[5] = 20

Hinweis: Noch nicht initialisierte Array-Felder zeigen den Standardwert "" an, wenn der Datentyp String ist, oder 0 für numerische Datentypen.

Tipps:

• Speicher wird für alle Elemente in einem Array reserviert. Um Performance-Probleme zu vermeiden, erstellen Sie Arrays mit genau der Anzahl der Elemente, die Sie tatsächlich benötigen.
• Sie können eine Script-Anweisung verwenden, um Werte direkt in einem Array zu speichern, mit oder ohne Angabe eines Index. Weitere Informationen finden Sie unter :FILL.

Variablen in Scripts verwenden

Neben Script-Variablen können Sie in Scripts verschiedene Arten von Variablen aufrufen, die in der Automation Engine verwendet werden, um in den Variablen gespeicherte Werte abzurufen und zu speichern. Mit verschiedenen Script-Elementen können Sie verschiedene Variablentypen abrufen und ändern. Weitere Informationen finden Sie unter Script-Elemente für Variablen und VARA-Objekte.

VARA-Objekte

Mit mehreren Script-Elementen können Sie speziell mit VARA-Objekten arbeiten. Geben Sie den Namen des VARA-Objekts in den Parametern des Script-Elements an.

Wichtig! Der Script-Editor unterstützt die Bearbeitung von VARA-Objekten nicht, die beliebige Binärwerte enthalten (z.B. 0x00-0x08, 0x0b, 0x0c, 0x0e-0x19). Wenn Sie versuchen, einen dieser Werte zu speichern, wird das Zeichen ? (0x3f) stattdessen immer gespeichert.

Tipp: Im Abschnitt Script Access (Script-Zugriff) der VARA-Objektdefinition definieren Sie, was geschehen soll, wenn der Schlüssel, auf den sich Ihr Script bezieht, im angegebenen VARA-Objekt nicht verfügbar ist. Weitere Informationen finden Sie unter Script-Zugriff.

Weitere Informationen: Variablen und VARA-Objekte

Script-Parameter

Schreiben Sie die Parameter für Script-Elemente in Klammern. Verwenden Sie Kommas, um Parameter zu trennen. Script-Elemente werden in der Reihenfolge ausgewertet, in der sie aufgelistet sind.

Beispiel

In der folgenden Script-Zeile sind die Parameter für die Funktion in Klammern eingeschlossen.

:SET &SUM# = ADD(2,2)

Hinweise:

• Schreiben Sie die erforderlichen Parameter in die Klammern, ohne weitere umschließende Klammern.
• Schreiben Sie optionale Parameter in eckige Klammern.

Beispiel

Die folgende Funktion erzeugt ein Objekt und hat verwendet zwei erforderliche Parameter (Objekttyp und Objektname) sowie zwei optionale Parameter (Ordner und Titel).

CREATE_OBJECT (Objekttyp, Objektname, [Ordner], [Titel] )

Wenn Sie keinen Wert für einen optionalen Parameter angeben möchten, schreiben Sie nichts oder ein Leerzeichen zwischen die Kommas.

Beispiel

Die folgende Anweisung gibt keinen Ordner an, da zwischen dem zweiten und dritten Komma kein Zeichen vorhanden ist.

:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2018",,"Unternehmenskalender für 2018")

Wenn Sie Werte für alle erforderlichen Parameter angeben, aber keine Werte für die restlichen optionalen Parameter aufnehmen möchten, müssen Sie für die restlichen optionalen Parameter keine Kommas einfügen.

Beispiel

Die folgende Anweisung erstellt ein Objekt ohne Angabe eines Ordners oder Titels, und Sie können die Klammern nach dem letzten erforderlichen Parameter einfach schließen.

:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2018")

Schlüsselwortparameter

Sie müssen Schlüsselwortparameter genau wie angegeben schreiben. In unserer Dokumentation sind die Schlüsselwortparameter fett ausgezeichnet. Wie bei den Parametern werden optionale Schlüsselwörter in eckige Klammern gesetzt.

Beispiel

In der folgenden Funktion ist VERSION ein Schlüsselwort.

SYS_INFO (Komponente,VERSION, [ Typ ], [Komponentenname])

Optionale Schlüsselwörter werden in eckige Klammern gesetzt.

Beispiel

In der folgenden Script-Funktion ist FORCED ein optionales Schlüsselwort.

MODIFY_TASK (RunID, Status [, FORCED])

Einige Schlüsselwortparameter können in Lang- oder Kurzform geschrieben werden. In diesem Fall wird der Schlüsselwortparameter mit dem optionalen Text für seinen langen Namen in [ ] Klammern dokumentiert.

Beispiel

Der Schlüsselwortparameter STR_SUBSTITUTE_VAR ist als STR_SUB[STITUTE]_VAR dokumentiert. Sie können STR_SUBSTITUTE_VAR oder STR_SUB_VAR schreiben.

Script-Literale

String-Literale sind Strings, die in einfachen (') oder doppelten (") Anführungszeichen geschrieben sind. Sie können jeden beliebigen String als Literal schreiben, z.B. um einen bestimmten Text zu drucken.

Ein Script-Literal kann auch Script-Variablen enthalten, die durch ihre Werte ersetzt werden, wenn die Script-Zeile, die das Script-Literal enthält, verarbeitet wird. Die folgenden Scripts rufen die Systemzeit ab und geben den String Zeit, gefolgt von der Systemzeit aus:

: SET   &TIME# = SYS_TIME ( "HH:MM:SS" )

: PRINT   "Time &TIME#"

Ausgabe:

Zeit 10:30:05

## <Nummer> ist eine reservierte Kombination. Wenn Sie diesen String in einem Script-Literal verwenden, wird der Text in der Meldung , deren Nummer unter <Nummer> festgelegt ist, gespeichert.

Die folgende Anweisung zeigt eine Meldung an:

:PRINT "##1800" oder :PRINT ##1800

Dies ist die angezeigte Meldung:

2011-06-15 13:01:51 - U0020408 ENDED_NOT_OK  - aborted.|

Wichtig! Der String <![[ ]]> ergibt einen Fehler, wenn Sie diese in Script-Literalen verwenden und Sie können das Objekt nicht speichern. Wenn Sie diesen String verwenden müssen, befolgen Sie die nachstehenden Schritte zur Vermeidung dieses Fehlers:

• Schreiben Sie einen Kommentar, der diese Zeichen enthält, und verwenden Sie den Kommentar, wenn Sie diese Zeichen benötigen.
  !<![[ ]]>

  :PRINT '<![[ ]]>'

• Der Fehler tritt nur auf, wenn diese Zeichen nacheinander verwendet werden. Sie können einen String zusammenstellen, indem Sie stattdessen Elemente kombinieren.
  • Verwenden Sie eine Script-Variable in einem Script-Literal, um den gewünschten String zu erstellen:
    : SET &VAR# = "]]"
    : PRINT'<![[ &VAR#>'
  • Verwenden Sie das Script-Element STR_CAT, um zwei Strings zu verbinden und den gewünschten String zu erstellen:
    : SET &VAR# = STR_CAT ("<![[ ]]",">")
    : PRINT &VAR#

Objektnamen

AE-Namen müssen nicht unter einfache oder doppelte Anführungszeichen gesetzt werden, es sei denn, sie beginnen mit einer Zahl. Schreiben Sie die folgenden AE-Namen ohne Anführungszeichen, wenn sie nicht mit einer Zahl beginnen:

• Objektnamen
  Wichtig! Halten Sie die Namensregeln für Objekte ein. Weitere Informationen finden Sie unter Objekte hinzufügen.
  Hinweis: Der Objektname wird in der Script-Referenz als der AE-Name angegeben, um eine Unterscheidung gegenüber Namen von Objekttypen darzustellen.
• Attribute von Objekten
  Weitere Informationen finden Sie unter Seite "Attribute".
• Kurzformen der Objekttypen
  Weitere Informationen finden Sie unter Objekttypen.

Hinweise: Verwenden Sie Anführungszeichen, wenn der AE-Name mit einer Zahl beginnt.

Strings per Script bearbeiten

Die Automation Engine-Scriptsprache stellt verschiedene Script-Elemente zur Verfügung, mit denen Sie Strings bearbeiten können. Sie können Strings verketten, Teile von Strings abrufen oder entfernen und alle oder Teile von Strings ersetzen. Weitere Informationen finden Sie unter Script-Elemente zur Bearbeitung von Strings.

Kommentare

Jede Zeile, die mit einem Ausrufezeichen beginnt, wird als Kommentar interpretiert und hat keinen Einfluss auf die Verarbeitung. Verwenden Sie Kommentare, um andere Benutzer darüber zu informieren, was verschiedene Teile Ihres Scripts bewirken, und erleichtern Sie die spätere Wartung.

Beispiel

!Ich kann hier irgendetwas schreiben

Richtig formatierte Kommentare werden im Script-Editor grün dargestellt.

Datenzeilen und Job Control Language

(Nur Jobobjekte) Zeilen, die weder mit einem Ausrufezeichen (!) noch mit einem Doppelpunkt (:) beginnen, werden als Datenzeilen interpretiert. Datenzeilen enthalten Kommandos in der Job Control Language (JCL) des Zielsystems. Wenn Sie JCL einschließen, vergewissern Sie sich, die Kommandos und die Syntax der JCL des Zielsystems zu verwenden, da diese dort interpretiert werden. Wenn ein Script mit JCL verarbeitet wird, wird die JCL an den Agenten gesendet und dort ausgeführt.

Sie können auch eine Script-Anweisung verwenden, um eine Script-Zeile explizit als Datenzeile zu deklarieren. Weitere Informationen finden Sie unter :DATA.

Jobs für Enterprise Business Solutions (PeopleSoft und SAP), beinhalten einige spezielle Funktionen. Daher bietet das Automation Engine scripting language spezifische JCL-Elemente für diese Systeme. Weitere Informationen finden Sie unter Job Control Language – Script-Referenz.

Beispiel

Die folgende Datenzeile verwendet einen Windows-Befehl, um eine Datei in ein Verzeichnis zu kopieren.

copy test.txt c:\temp

Wenn eine Datenzeile mit einem Doppelpunkt (:) beginnt, müssen Sie sie explizit mit der Script-Anweisung :DATA als Datenzeile deklarieren.

Beispiel

Die folgende Datenzeile verwendet den gleichen Windows-Befehl wie im obigen Beispiel, ist aber explizit deklariert.

:DATA copy test.text c:\temp

Hinweis: Wenn Sie eine Variable einbinden und Ihre Datenzeile ein kaufmännisches Und-Zeichen vor der Variablen benötigt, stellen Sie sicher, dass Sie beide kaufmännischen Und-Zeichen schreiben. Wenn das Script verarbeitet wird, wird die Script-Variable zusammen mit dem Und-Zeichen in ihrem Namen durch den Wert ersetzt, der der Variablen zugewiesen ist. Wenn Sie ein Und-Zeichen verwenden, ohne einen gültigen Variablennamen danach anzuführen, bleibt die Datenzeile unverändert.

Siehe auch: