System-Skriptsprache: Allgemeine Funktionen, Sonstige Funktionen (Miscellaneous functions)

Die sonstigen Funktionen befassen sich vor allem mit Elementen der System-Skriptsprache und der Ausführung von Skripten. Zu den sonstigen Funktionen gehören:

call
cast
echo
hashMap
import
if
load
sendMail
new

Grundlegende Informationen zu den allgemeinen Funktionen der System-Skriptsprache erhalten Sie im Dokument System-Skriptsprache: Allgemeine Funktionen.

call

Name	call
Beschreibung	call ruft eine Aktivitätsdefinition vom Typ Funktionsaufruf auf.
Signaturen	`HashMap call(String activityDefinition, HashMap parameters)`
Parameter	activityDefinition ist der Name einer Aktivitätsdefinition vom Typ Funktionsaufruf. parameters ist eine Hash-Tabelle mit einem Eintrag für jeden Parameter der Aktivitätsdefinition. Die Parameter werden alphabetisch sortiert.
Ergebnis	Eine HashMap mit einem Eintrag für jeden Rückgabeparameter der aufgerufenen Aktivitätsdefinition.
Fehlerquellen	Bei dem Aufruf muss jedem Parameter der aufgerufenen Aktivitätsdefinition ein Wert zugeordnet werden.
Beispiele	`cast(String, call("help.encrypt", hashMap(PLAIN_TEXT:="Hello world", KEY:="")).VALUE)`verschlüsselt den Text Hello world mithilfe des Standard-Schlüssels. `cast(Number, call("convertToFahrenheit", hashMap(CELSIUS:=100)).FAHRENHEIT)` ruft die Aktivitätsdefinition mit dem Parameterwert 100 auf und wandelt das Ergebnis vom Datentyp Unknown in eine Zahl um. `@convertToFahrenheit(CELSIUS:=100).FAHRENHEIT` ist eine alternative Syntax für den Aufruf im vorherigen Beispiel. `call("getTopTenItems", hashMap(CUSTOMER:=loadPartner("10010"):number))` gibt eine HashMap mit den Artikelnummern der zehn meistgekauften Artikel von dem Kunden 10010 zurück.
Kontext	`ALL`
Hinweise	Die maximale Rekursionstiefe ist beschränkt. Weitere Informationen finden Sie im Kapitel Komplexität von Ausdrücken beschränken des Hilfedokuments Einführung: System-Skriptsprache.
Siehe auch	Weitere Informationen zur alternativen Syntax mit @ finden Sie im Kapitel Aktivitätsdefinitionen aufrufen des Hilfedokuments Einführung: System-Skriptsprache.

Folgendes Beispiel aus der Aktivitätsdefinition help.call ruft die Aktivitätsdefinition help.encrypt auf, um einen Text zu verschlüsseln. Anschließend wird die Aktivitätsdefinition help.decrypt aufgerufen, um den verschlüsselten Text wieder zu entschlüsseln.

function create()
{
var p_plainText := parameters.PLAIN_TEXT;
var key := cast(String, newGuid());

var params as HashMap;
params["PLAIN_TEXT"] := p_plainText;
params["KEY"] := key;
var encryptedText := cast(String, call("help.encrypt", params).VALUE);

params := new(HashMap);
params["ENCRYPTED_TEXT"] := cast(String, encryptedText);
params["KEY"] := key;
var decryptedText := cast(String, call("help.decrypt", params).VALUE);

result.DECRYPTED_TEXT := decryptedText;
}

cast

Name	cast
Beschreibung	cast wandelt einen Ausdruck in einen anderen Datentyp um.
Signaturen	`String cast(<datatype>, Unknown p)` `String[] cast(<datatype>, Unknown p)` `Number cast(<datatype>, Unknown p)` etc.
Parameter	p ist der Ausdruck, der in einem anderen Datentyp umgewandelt werden soll.
Ergebnis	Der Ausdruck wird in den Datentypen <datatype> umgewandelt.
Fehlerquellen	Nicht alle Datentypen können ineinander umgewandelt werden. Ist dies der Fall, entsteht ein syntaktischer Fehler. Grundsätzlich können alle Datentypen in den Datentypen Unknown umgewandelt werden. Auch der umgekehrte Weg von Unknown in einen beliebigen Datentyp ist möglich. Folgende Datentypen können in eine Zeichenkette (String) umgewandelt werden: Boolean, Bytes, CisDate, Guid, Number, Timestamp. Darüber hinaus kann eine Zeichenkette (String) in eine Guid umgewandelt werden. Auch ein CisObject kann in eine CisObjectReference umgewandelt werden und umgekehrt. Folgende Umwandlungen sind nicht möglich: Timestamp zu Number, Boolean zu und von Number, CisDate zu Timestamp.
Beispiele	`cast(String, ZERO_GUID)` gibt eine Zeichenkette mit 32 Nullen zurück. `cast(Guid, cast(String, ZERO_GUID))` ergibt wieder eine ZERO_GUID.
Kontext	`ALL`
Hinweise	Verwenden Sie die Funktion „cast“ beispielsweise in den folgenden Fällen: Wenn ein ein Ausdruck oder eine Funktion den Datentyp Unknown zurückgibt, wie z. B. bei den Funktionen first oder if. Um durch das programmierte Ereignis com.cisag.pgm.workflow.GenericOLTPEvent übergebene Parameter auszuwerten. Beim Aufruf einer Aktivitätsdefinition vom Typ Funktionsaufruf, die einen Wert von einem Datentyp außer String, Number oder Timestamp zurückgibt. Um in einem Serviceknoten die Ergebnisse des Verarbeitungsauftrags auszuwerten. Für die Umwandlung von CisDate zu Timestamp steht die Funktion toTimestamp zur Verfügung. Die Umwandlung von Listen wird nicht syntaktisch geprüft.
Siehe auch	guidToString, toCharList, toTimestamp

Folgendes Beispiel aus der Aktivitätsdefinition help.cast wandelt ein CisDate und einen Zeitpunkt in Zeichenketten um:

function create()
{
var p_today := today();
var p_timestamp := now();
var r_cisDateToString := cast(String, p_today);
var r_timestampToString := cast(String, p_timestamp);

result.VALUE_CISDATE := r_cisDateToString;
result.VALUE_TIMESTAMP := r_timestampToString;
}

echo

Name	echo
Beschreibung	echo gibt seinen Parameter auf der Konsole der Toolshell aus und gibt den Wert true zurück.
Signaturen	`Boolean echo(Unknown expression)`
Parameter	expression ist ein Term oder Ausdruck.
Ergebnis	Die Funktion echo gibt den Wert von expression auf der Konsole der Toolshell aus. Mit dieser Funktion lassen sich beispielsweise Bedingungen in Aktivitätsdefinitionen überwachen. Der Rückgabewert ist immer `true`, auch dann, wenn der Parameter `null`ist.
Fehlerquellen
Beispiele	`echo("A")` gibt ECHO: A auf der Konsole aus. `echo(list("A", "B", "C", 1, 2, 3))` gibt ECHO: [[S=A], [S=B], [S=C], [N=1], [N=2], [N=3]] auf der Konsole aus. `echo(hashMap(A:=1, B:=null, C:=day(today()), D:=new(Unknown[3])))` gibt ECHO: {A=[N=1], B=[103=null], C=[N=13], D=[L=[[103=null], [103=null], [103=null]]]} auf der Konsole aus. Der Schlüsselwert 103 steht für den Datentyp Unknown. `echo(loadPartner("10010"))` gibt ECHO: Partner[10010] auf der Konsole aus. `echo(definition:name)` gibt den Namen der Aktivitätsdefinition auf der Konsole aus. `echo(activity:code)` gibt die Identifikation (Nummer) der Aktivität auf der Konsole aus. `echo(activity->Process:code)` und `echo(process.Code)`geben beide die Identifikation (Nummer) des Prozesses auf der Konsole aus. `echo("parameters.object:status=" + parameters.object:status)` gibt den Wert des Attributs status des vom parameters.object referenzierten Business Objects auf der Konsole aus. In einer Bedingung hat dieser Ausdruck den Wahrheitswert true. `echo("Activity definition " + definition:code + " evaluated event " + valueSetName(EventType, event.type) + " with subtype " + valueSetName(ObjectChangeType, event.subtype) + " for " + objectName(event.guid) + " " + parameters.object:number + " triggered by user " + userName (parameters.userGuid) + " in database " + databaseName(event.database)) + "."` in der Übergangsbedingung einer Aktivitätsdefinition mit einer Ereignisdefinition vom Typ Business Entity gibt `ECHO: Activity definition exampleEcho\|Start evaluated event TRANSACTION with subtype UPDATE for com.cisag.app.general.obj.Partner 10010 triggered by user JOB in database ADV60010.`auf der Konsole aus.
Kontext	`ALL`
Hinweise	Die Ausgabe wird auch in das Protokoll des Application-Servers geschrieben, auf dem die Funktion echo ausgeführt wird. Eine Ausgabe in einer Übergangsbedingung steht im Protokoll des Application Servers, der das Ereignis bearbeitet. Eine Ausgabe in einer Vorbedingung steht im Protokoll des Application-Servers, auf dem die Workflow-Engine bzw. der Scheduler läuft. In der Regel ist dies der Message-Server.
Siehe auch

Folgendes Beispiel aus der Aktivitätsdefinition help.echo gibt einen Text auf der Konsole der Toolshell aus:

function create()
{
echo(parameters.TEXT);
}

hashMap

Name	hashMap
Beschreibung	hashMap erzeugt eine HashTabelle und gibt sie zurück.
Signaturen	`hashMap(key1:=value1, key2:=value2,…,keyN:=valueN)`
Parameter	value1, value2,…,valueN sind Terme für die Werte zu den Schlüsseln key1, key2,…,keyN der zu erzeugende Hash-Tabelle. Alle Parameter sind optional.
Ergebnis	Eine Hash-Tabelle mit den angegeben Schlüssel-Wert-Paaren.
Fehlerquellen	Keine.
Beispiele	`hashMap()` gibt eine leere Hash-Tabelle zurück. `hashMap(one:=1, two:=2, three:=3)` gibt die Hash-Tabelle {one=[N=1], two=[N=2], three=[N=3]} zurück.
Kontext	`ALL`
Hinweise
Siehe auch	new

Folgendes Beispiel aus der Aktivitätsdefinition help.hashMap gibt die Hash-Tabelle {one=[N=1], two=[N=2], three=[N=3]} auf der Konsole der Toolshell aus:

function create()
{
var r_hashMap := hashMap(one:=1, two:=2, three:=3);

echo(r_hashMap);
}

import

Name	import
Beschreibung	import importiert ein Skriptobjekt oder eine Bibliothek in eine in der System-Skriptsprache erfasste Deklaration.
Signaturen	`import systemScript`
Parameter	systemScript ist der technische Name eines Entwicklungsobjekts vom Typ Skript oder der Name einer in der OLTP-Datenbank erfassten Bibliothek.
Ergebnis	Ist das angegebene Skriptobjekt bzw. die Bibliothek vorhanden, dann wird es bzw. sie in die Deklaration eingebunden. Die im Skriptobjekt bzw. in der Bibliothek enthaltenen Variablen, Konstanten, Klassen und Funktionen stehen in den Deklarationen zur Verfügung.
Fehlerquellen	Der Befehl import muss an erster Stelle in den Deklarationen stehen. Das eingebundene Skriptobjekt bzw. die Bibliothek und die Deklarationen müssen beide in der gleichen Skriptsprache erfasst sein. Da das Skriptobjekt bzw. die Bibliothek in die Deklaration textuell eingebunden wird, darf das Skriptobjekt bzw. die Bibliothek nicht im Widerspruch zur Deklaration stehen. Dies könnte z. B. dann der Fall sein, wenn sowohl das Skriptobjekt als auch die Deklaration eine Funktion mit dem gleichen Namen enthält.
Beispiele	`import com.pt.app.HelloWorld` importiert das in einem Produktiv-Testsystem in der System-Skriptsprache erfasste Skriptobjekt mit dem gleichen Namen. `import help.stringUtilityFunctions` importiert die Bibliothek mit dem gleichen Namen.
Kontext	`ALL`
Hinweise	Die Funktion import steht nur in der System-Skriptsprache zur Verfügung. Skriptobjekte erfassen Sie in der Anwendung Entwicklungsobjekte. Bibliotheken erfassen Sie in der gleichnamigen Anwendung Bibliotheken. Gibt es sowohl ein Skriptobjekt als auch eine Bibliothek mit dem angegebenen Namen, dann wird die Bibliothek bevorzugt importiert. Sowohl ein Skriptobjekt als auch eine Bibliothek stehen in allen Datenbanken eines Systems zur Verfügung. Als sogenanntes. Produktivsystem-Entwicklungsobjekt kann ein Skriptobjekt von einem Produktiv-Testsystem in ein Produktivsystem mithilfe der Anwendung Cockpit: Produktivsystem-Entwicklungsobjekte transportiert werden. Unter anderem aus diesem Grund wird die Verwendung von Skriptobjekten empfohlen.
Siehe auch	load

Folgendes Beispiel aus der Aktivitätsdefinition help.import importiert die Deklarationen aus der Bibliothek help.stringUtilityFunctions.

import help.stringUtilityFunctions;

function create()
{
var p_text := parameters.TEXT;
var p_separator := parameters.SEPARATOR;
var r_wordList := splitString(p_text, p_separator);

result.SPLIT_TEXT := r_wordList;
result.JOINED_TEXT := joinString(r_wordList, p_separator);
}

Die beiden Funktionen split und join müssen in der Bibliothek help.stringUtilityFunctions in der System-Skriptsprache deklariert sein, beispielsweise wie folgt:

function split(p_text as String, p_separator as String) as String[]
{
if (p_separator = "")
p_separator := " ";
var increment := length(p_separator);
var sep as String;
var word as String;
var r_wordList as String[];
var i := 0;
var startPos := 0;

while (i + increment - 1 < length(p_text)) {
sep := substring(p_text, i, i + increment);
if (sep = p_separator) {
word := trim(substring(p_text, startPos, i));
i := i + increment;
startPos := i;
if (word <> "" and word <> p_separator)
add(r_wordList, word);
} else {
i := i + 1;
}
}

word := substring(p_text, startPos);
if (word <> "" and word <> p_separator)
add(r_wordList, word);

return r_wordList;
}

function join(p_textList as String[], p_separator as String) as String
{
var r_text as String;

for (word as String : p_textList)
r_text := r_text + p_separator + word;
if (r_text <> "")
r_text := substring(r_text, length(p_separator));

return r_text;
}

if

Name	if
Beschreibung	if wertet einen von zwei Ausdrucken bedingt aus.
Signaturen	`Unknown if(Boolean condition, Unknown a, Unknown b)`
Parameter	condition ist eine Bedingung vom Datentyp Boolean. a ist der Ausdruck, dessen Wert zurückgegeben wird, wenn die Bedingung condition wahr ist. b ist der Ausdruck, dessen Wert zurückgegeben wird, wenn die Bedingung condition falsch ist.
Ergebnis	Ist condition wahr, dann wird der Ausdruck a ausgewertet und dessen Wert zurückgegeben. Ist condition falsch, dann wird der Ausdruck b ausgewertet und dessen Wert zurückgegeben.
Fehlerquellen	Keine
Beispiele	`if(a > b, a, b))`gibt die größere von den Zahlen a und b als Unknown zurück. `cast(Number, if(a > b, a, b))` gibt die größere von den Zahlen a und b als Zahl zurück. `if(null, 1, 2)` gibt null zurück. `if(true, i, i / 0)` gibt immer i als Unknown zurück. Da true immer wahr ist, wird i / 0 nie ausgewertet und der Ausdruck verursacht keinen Laufzeitfehler.
Kontext	`ALL`
Hinweise	Sie können Sie die Funktion if verwenden, um in einem Ausdrucksfeld (wie z. B. in der Übergangsbedingung oder im Ausdruck für die Bearbeiter einer Aktivitätsdefinition) eine Bedingung abzubilden. Da das Ergebnis der Funktion if vom Datentyp Unknown ist, müssen Sie es in der Regel mithilfe der Funktion cast zuerst in einen anderen Datentyp umwandeln, bevor Sie es verwenden können.
Siehe auch	Weitere Informationen zu den bedingten Befehlen finden Sie in den Kapiteln Bedingter Befehl (if) und Bedingter Befehl mit Alternative (if … else) des Hilfedokuments Einführung: System-Skriptsprache.

Folgendes Beispiel entstammt der Aktivitätsdefinition help.if.

function create()
{
var p_number1 := parameters.NUMBER1;
var p_number2 := parameters.NUMBER2;

var r_comparator := cast(String,
if(p_number1 > p_number2,">",
if(p_number1 < p_number2, "<", "=")));

result.VALUE :=
cast(String, p_number1) + r_comparator + cast(String, p_number2);
}

load

Name	load
Beschreibung	load bindet ein Skriptobjekt in eine in JavaScript erfasste Deklaration ein.
Signaturen	`load (scriptObject)`
Parameter	scriptObject ist der technische Name eines Entwicklungsobjekts vom Typ Skript.
Ergebnis	Ist das angegebene Skriptobjekt vorhanden, dann wird es in die Deklaration eingebunden. Die im Skriptobjekt enthaltenen Variablen, Konstanten, Klassen und Funktionen stehen in den Deklarationen zur Verfügung.
Fehlerquellen	Das eingebundene Skriptobjekt und die Deklarationen müssen beide in der gleichen Skriptsprache erfasst sein. Da das Skriptobjekt in die Deklaration textuell eingebunden wird, darf das Skriptobjekt nicht im Widerspruch zur Deklaration stehen. Dies könnte z. B. dann der Fall sein, wenn sowohl das Skriptobjekt als auch die Deklaration eine Funktion mit dem gleichen Namen enthält.
Beispiele	`load (com.pt.app.HelloWorld)` importiert das in einem Produktiv-Testsystem in JavaScript erfasste Skriptobjekt mit dem gleichen Namen.
Kontext	`ALL`
Hinweise	Die Funktion load steht nur in JavaScript zur Verfügung, daher muss ein mit load eingebundenes Skriptobjekt auch in JavaScript erfasst sein. Skriptobjekte erfassen Sie in der Anwendung Entwicklungsobjekte. Ein Skriptobjekt steht in allen Datenbanken eines Systems zur Verfügung. Als sogenanntes Produktivsystem-Entwicklungsobjekt kann ein Skriptobjekt von einem Produktiv-Testsystem in ein Produktivsystem mithilfe der Anwendung Cockpit: Produktivsystem-Entwicklungsobjekte transportiert werden. Unter anderem aus diesem Grund wird die Verwendung von Skriptobjekten empfohlen.
Siehe auch	import

Folgendes Beispiel aus der in JavaScript erfassten Aktivitätsdefinition help.load öffnet das in JavaScript erfasste Skriptobjekt com.pt.app.HelloWorld.

load(com.pt.app.HelloWorld);

function create()
{
var r_hello = hello();
result.VALUE = r_hello;
}

Die Funktion hello muss in einem Skriptobjekt mit dem Namen com.pt.app.HelloWorld in JavaScript deklariert sein, beispielsweise wie folgt:

function hello()
{
return "Hello world!";
}

sendMail

Name	sendMail
Beschreibung	sendMail sendet eine E-Mail-Nachricht an einen oder mehrere Empfänger.
Signaturen	`Boolean sendMail(String recipientTo, String subject, String descriptionHtml)` `Boolean sendMail(Guid recipientToUserGuid, String subject, String descriptionHtml)` `Boolean sendMail(Guid[] recipientToUserGuids, String subject, String descriptionHtml)`
Parameter	recipientTo ist die E-Mail-Adresse des Empfängers. Hat die E-Mail-Nachricht mehrere Empfänger, dann trennen Sie jede E-Mail-Adresse durch ein Komma. subject ist der Betreff der E-Mail-Nachricht. descriptionHtml ist die Beschreibung der E-Mail-Nachricht als HTML-String kodiert. recipientToUserGuid ist die Benutzer-Guid des Empfängers. recipientToUserGuids ist eine Liste mit Benutzer-Guids der Empfänger.
Ergebnis	Sendet die E-Mail-Nachricht an den oder die Empfänger. Als Absender wird der in der Customizing-Funktion Benutzereinstellungen für das System hinterlegte Absender verwendet.
Fehlerquellen	Fehler können u. a. durch unzulässige E-Mail-Adressen oder eine unvollständige oder fehlerhafte Konfiguration der E-Mail-Funktion entstehen.
Beispiele	`sendMail(parameters.userGuid, "Test", "<em>Hello World!</em>")` versendet eine E-Mail-Nachricht an den Benutzer, der das Ereignis ausgelöst hat.
Kontext	`ALL`
Hinweise	Wegen der besseren Dokumentation und Nachvollziehbarkeit wird empfohlen, E-Mail-Nachrichten mithilfe von E-Mail-Knoten zu versenden.
Siehe auch	Siehe auch die Funktionen für E-Mail-Knoten im Hilfe-Dokument System-Skriptsprache: Workflow-Funktionen.

Folgendes Beispiel aus der Aktivitätsdefinition help.sendMail versendet eine E-Mail-Nachricht an einen Benutzer im System.

function create()
{
var p_user := parameters.USER;
var p_subject := parameters.SUBJECT;
var p_description := parameters.DESCRIPTION;
var r_sendMail := sendMail(userMailAddress(userGuid(p_user)), p_subject, toHtml(p_description));

result.SEND_MAIL := r_sendMail;
}

new

Name	new
Beschreibung	new erzeugt eine neue Instanz eines Datentyps.
Signaturen	`new(Unknown type)` `new(Unknown listType, Number size)`
Parameter	type ist der Datentyp der neuen Instanz. size ist die Größe der Liste.
Ergebnis	Eine neue Instanz mit dem angegebenen Datentyp wird erzeugt. Falls der Datentyp eine Liste ist, so besitzt new eine erweiterte Funktionalität. Bei Listen unbestimmter Länge kann bei new eine Länge n angegeben werden. Wenn der Listentyp die Länge n hat bzw. eine Länge n mitgegeben wird, so wird eine Liste mit n leeren Elementen erzeugt. Falls der Datentyp eine Klasse ist, wird eine neue Instanz dieser Klasse erzeugt. Alle Attribute der neuen Instanz werden mit Standardwerten gefüllt.
Fehlerquellen	Keine
Beispiele	`new(HashMap)` gibt eine neue Instanz vom Datentyp HashMap zurück. `new(Number[])` gibt eine neue leere Liste vom Datentyp Number[] zurück. `new(Number[10])` gibt eine neue Liste vom Datentyp Number[] mit 10 Elementen vom Elementdatentyp Number mit dem Standardwert 0 zurück. `new(Number[], index)` gibt eine neue Liste vom Datentyp Number[] mit den in index angegeben Elementen vom Elementdatentyp Number zurück. `new(Number[index])` ergibt einen syntaktischen Fehler.
Kontext	`ALL`
Hinweise
Siehe auch	hashMap, newGuid

Folgendes Beispiel entstammt der Aktivitätsdefinition help.new.

function create()
{
var p_size := parameters.SIZE;
var r_stringArray := new(String[], max(min(p_size, 10), 0));
/* alternative notation: new(String[10]) */

result.VALUE := r_stringArray;
result.VALUE := new(Number[]);
}

Comarch ERP Enterprise 6.4