Funktionen

Eine Funktion ist ein wiederverwendbarer Codeblock, der eine bestimmte Aufgabe ausführt. Wenn Sie diese Aufgabe benötigen, können Sie einfach die entsprechende Funktion in Ihrem Skript verwenden. So sparen Sie Zeit und Arbeit, da Sie Ihrem Skript den Code für diese Aufgabe nicht jedes Mal hinzufügen müssen, wenn Sie die Aufgabe benötigen. Und da Sie weniger Code benötigen, sind Ihre Skripte einfacher und übersichtlicher.

Funktionen bieten die folgenden Möglichkeiten:

• Sie können Daten aus dem Skript extrahieren, auf die gewünschte Weise bearbeiten und die Ergebnisse dann wieder an das Skript zurückgeben.
• Sie können eine oder mehrere Aktionen ausführen und die resultierenden Daten an das Skript zurückgeben.

Einige Funktionen sind in Studio integriert und können in Ihren Skripten verwendet werden. Zur Verwendung einer integrierten Funktion müssen Sie Ihrem Skript keinen weiteren Code hinzufügen. Wenn Sie eine solche Funktion verwenden möchten, können Sie sie einfach aufrufen.

Sie können auch benutzerdefinierte Funktionen erstellen und in Skripten verwenden. Dies ist praktisch, wenn Sie bestimmten Code häufig in Ihrem Skript verwenden. Sie müssen dem Skript den Code nicht jedes Mal hinzufügen, wenn Sie ihn benötigen, sondern können stattdessen einfach eine Funktion erstellen, die den Code enthält. Wenn Sie den Code anschließend benötigen, rufen Sie die Funktion auf.

Syntax

Am Ende eines Funktionsnamens befindet sich ein Klammernpaar: Funktionsname().

Beim Text innerhalb der Klammern handelt es sich um Parameter, die Daten definieren, die zwischen der Funktion und dem Skript übergeben werden: Funktionsname(Param1,Param2).

Verwenden Sie zum Erstellen einer benutzerdefinierten Funktion diese Syntax:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

In dieser Syntax:

• FUNCTION ist das erforderliche Schlüsselwort, mit dem alle Anweisungen für benutzerdefinierte Funktionen beginnen.
• <name> ist der Name der Funktion.
• ([<parameter>] [...]) definiert die erforderlichen Parameter für die Funktion.
• { ... } enthält den Code der Funktion.
• [RETURN <data>] ist die Anweisung, mit der Daten von der Funktion an das Hauptskript übergeben werden.

Sie können Ihren benutzerdefinierten Funktionen einen beliebigen Namen geben, müssen dabei jedoch die folgenden Richtlinien beachten:

• Verwenden Sie alphanumerische Zeichen (a-z, A-Z, 0-9).

• Das erste Zeichen des Namens muss ein Buchstabe sein.
• Verwenden Sie den Unterstrich ( _ ) und das Dollarzeichen ( $ ) an einer beliebigen Stelle im Namen.
• Verwenden Sie weder reservierte Wörter noch die Namen von integrierten Funktionen.

Die Syntax für eine RETURN-Anweisung lautet:

RETURNoderRETURN <var>

Verwenden Sie beim Aufrufen einer Funktion eine der beiden folgenden Syntaxen:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Parameter und Argument

Zahlreiche Funktionen müssen Daten aus dem Skript verwenden. Dazu können Sie Parameter und Argumente verwenden.

Parameter werden beim Erstellen einer Funktion definiert. Ein Parameter ist ein Variablenname, der innerhalb der Klammern steht, die auf den Namen der Funktion folgen. Eine Funktion kann mehr als einen Parameter enthalten. Die einzelnen Parameter werden durch ein Komma voneinander getrennt. Wahlweise können Sie ein Leerzeichen einfügen. Beispielsweise hat die Funktion logn(value, base) zwei Parameter: value und base.

Die Daten, die das Skript über die Parameter an die Funktion übergibt, werden als Argumente bezeichnet. Das folgende Beispiel zeigt die Verwendung der integrierten Funktion abs(value) in einem Skript. In diesem Beispiel ist  -42 das Argument, das an den Parameter value übergeben wird.

ASSIGN abVal = abs(-42)

In Studio sind alle Parameter erforderlich. Wenn eine Funktion mit einem Parameter definiert ist, müssen Sie beim Aufrufen der Funktion einen Wert übergeben. Die Anzahl der an die Funktion übergebenen Argumente muss mit der Anzahl der definierten Parameter übereinstimmen.

Das Skript überprüft nicht, ob die Argumente den richtigen Typ und das richtige Format aufweisen. Doch wenn der Typ oder das Format des Arguments nicht den Erwartungen der Funktion entspricht, wird die Funktion möglicherweise nicht ordnungsgemäß ausgeführt oder die Ergebnisse können fehlerhaft sein.

Wenn zu wenige oder zu viele Argumente an die Funktion übergeben werden, tritt beim Ausführen des Skripts ein Kompilierungsfehler auf. Dies kann bei integrierten Funktionen und bei benutzerdefinierten Funktionen geschehen.

Formatierung der Argumente

Beim Aufrufen einer Funktion, die Parameter erfordert, müssen Sie die zu übergebenden Argumente in die Funktion einschließen. Formatieren Sie die Argumente anhand der folgenden Richtlinien:

• Wenn es sich beim Argument um einen numerischen Wert oder um eine Variable handelt, muss es nicht in einfache oder doppelte Anführungszeichen eingeschlossen werden.
• Wenn das Argument eine Variable ist, muss es nicht in geschweifte Klammern eingeschlossen werden.
• Wenn das Argument alphanumerisch, aber keine Variable ist, schließen Sie es in einfache oder doppelte Anführungszeichen ein.

Beispielsweise erfordert die dateadd()Funktion drei Parameter: unit, date und value.

Unit definiert den Teil des Datums, der durch die Funktion geändert werden soll, wie Jahr oder Monat. Date ist das ursprüngliche Datum, das geändert werden soll. value gibt an, um welchen Wert die Funktion die angegebene Einheit des ursprünglichen Datums erhöhen soll. Das folgende Beispiel zeigt, wie die einzelnen Teile formatiert werden:

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

unit ist ein alphanumerischer String und wird daher mit einfachen Anführungszeichen formatiert. date ist in diesem Beispiel eine Variable und steht daher ohne Anführungszeichen. Wenn Sie ein Datum als String übergeben würden, wären Anführungszeichen erforderlich. value ist numerisch und wird daher nicht formatiert.

RETURN-Anweisungen

Eine RETURN-Anweisung beendet eine Funktion und gibt die Kontrolle an das Skript zurück. Sie kann auch Daten an das Skript zurückgeben.

RETURN-Anweisungen können Daten nur in Form eines Variablenwertes oder eines Arrays an das Skript zurückgeben. Sie können nicht mehrere Werte zurückgeben, es sei denn, diese Werte gehören zu einem Array oder einem Objekt. Sie können keine Objekte zurückgeben, es sei denn, die Objekte werden zuerst in das JSON-Format konvertiert. Bei Bedarf können Sie es im Skript wieder in ein Objekt konvertieren.

Die Syntax für eine RETURN-Anweisung lautet:

RETURNoderRETURN <var>

Alle integrierten Funktionen, die einen Wert an das Skript zurückgeben, enthalten eine RETURN-Anweisung. In benutzerdefinierten Funktionen, die Sie erstellen, sind RETURN-Anweisungen optional. Wenn keine RETURN-Anweisung vorhanden ist, kann die Funktion keine Werte an das Skript zurückgeben. Sie können eine Funktion ohne RETURN-Anweisung nur verwenden, indem Sie sie wie eine Anweisung aufrufen.

Wenn Sie eine RETURN-Anweisung in eine Funktion einschließen, muss sie sich in der letzten Zeile der Funktion befinden.

Sichtbarkeit der Variablen

Standardmäßig sind alle Werte in der Funktion nur innerhalb der Funktion verfügbar und verwendbar. Wenn die Funktion beendet wird, gehen alle enthaltenen Werte verloren. Wenn die Funktion eine RETURN-Anweisung enthält, die einen Variablenwert an das Skript zurückgibt, sind nur die Werte, die über die RETURN-Anweisung übergeben werden, außerhalb der Funktion verfügbar.

Wenn Sie in eine benutzerdefinierte Funktion Variablen aufnehmen, die im Hauptskript vorhanden sind, haben diese Variablen einen globalen Umfang. Das heißt, dass diese Werte auch ohne RETURN-Anweisung außerhalb der Funktion verfügbar sind. Auch wenn Sie eine Variable innerhalb der Funktion als global deklarieren, ist ihr Wert im Hauptskript verfügbar. Dies ähnelt dem Verhalten in Subskripten.

Wenn Sie eine Funktion in einem Ausdruck oder als Wert einer Variablen verwenden, gilt das Standardverhalten. Doch wenn Sie eine Funktion als Anweisung aufrufen, haben alle Werte in der Funktion einen globalen Umfang und können außerhalb der Funktion verwendet werden. Funktionen ohne RETURN-Anweisung können nur auf diese Weise verwendet werden.

Erstellen von benutzerdefinierten Funktionen

Wenn bestimmter Code an mehreren Stellen in Ihrem Skript verwendet werden soll, können Sie benutzerdefinierte Funktionen erstellen. Eine benutzerdefinierte Funktion steht nur in dem Skript zur Verfügung, in dem Sie sie erstellt haben. Wenn Sie eine benutzerdefinierte Funktion in einem anderen Skript verwenden möchten, müssen Sie den Code der Funktionsdefinition in das jeweilige Skript kopieren.

Sie können eine Funktion in einer Snippet-Aktion in Ihrem Skript erstellen und dann in anderen Snippet-Aktionen im selben Skript aufrufen. Wenn Sie das Snippet debuggen, das die Funktionsdefinition enthält, wird diese beim Debuggen berücksichtigt. Beim Debuggen der anderen Snippets wird die Funktion jedoch nicht eingeschlossen.

Die Syntax zum Deklarieren einer benutzerdefinierten Funktion lautet folgendermaßen:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION ist ein Schlüsselwort, das dem Skript mitteilt, dass eine benutzerdefinierte Funktion folgt. Für Funktionsnamen gelten dieselben Namenskonventionen wie für andere Elemente in Skripten:

• Verwenden Sie alphanumerische Zeichen (a-z, A-Z, 0-9).

• Das erste Zeichen des Namens muss ein Buchstabe sein.
• Verwenden Sie den Unterstrich ( _ ) und das Dollarzeichen ( $ ) an einer beliebigen Stelle im Namen.
• Verwenden Sie weder reservierte Wörter noch die Namen von integrierten Funktionen.

Wenn die Funktion Parameter erfordert, fügen Sie diese in die Klammern am Ende des Funktionsnamens ein. Wenn keine Parameter vorhanden sind, können die Klammern leer bleiben. Trennen Sie mehrere Parameter durch Kommas.

Der Code, aus dem die Funktion besteht, steht zwischen den geschweiften Klammern. Die Platzierung der geschweiften Klammern ist flexibel. Sie können sich in derselben Zeile wie das FUNCTION-Schlüsselwort und der Name oder in separaten Zeilen befinden. Beide der folgenden Beispiele sind gültige Funktionsdefinitionen:

FUNCTION myFunction() { ASSIGN var = "value" } 

FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

Wenn die Funktion eine RETURN-Anweisung enthält, muss es sich um die letzte Anweisung in der Funktion vor der schließenden geschweiften Klammer handeln.

Die Funktion enthält keinen String und keine Anführungszeichen. Wenn keine Anführungszeichen vorhanden sind und es sich nicht um eine Zahl oder einen booleschen Wert handelt, wird davon ausgegangen, dass es sich um eine Variable handelt.

Weitere Informationen zum Erstellen von Funktionen finden Sie auf der Seite "Deklarierungsanweisungen".

Hilfe zur automatischen Vervollständigung für benutzerdefinierte Funktionen

Sie können Hilfe zur automatischen Vervollständigung für Ihre benutzerdefinierten Funktionen hinzufügen. Dabei handelt es sich um Tooltipp-Text, der eingeblendet wird, wenn Sie im Snippet editor-Fenster mit der Eingabe des Funktionsnamens beginnen. Diese Hilfe wird nur eingeblendet, wenn Sie die Funktion mit der Punkt-Schreibweise aufrufen.

Bild anzeigen

Mit diesen Tooltipps können Sie hilfreiche Informationen über die Funktion zur Verfügung stellen. Beispielsweise können Sie damit die Parameter der Funktion definieren.

Um Hilfe zur automatischen Vervollständigung hinzuzufügen, fügen Sie einen Kommentar auf der Zeile hinzu, auf der sich die Funktionsdeklaration befindet. Wenn Sie beispielsweise den im Bild oben gezeigten Tooltipp erstellen möchten, sieht Ihre Funktionsdeklaration folgendermaßen aus:

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}	

Wenn Sie einer Funktion Hilfe zur automatischen Vervollständigung hinzufügen, müssen die geschweiften Klammern, die den Funktionscode enthalten, auf einer anderen Zeile stehen als die Funktionsdefinition. Das Skript interpretiert den gesamten Text, der nach den beiden Schrägstrichen steht, als Teil des Kommentars. Wenn sich die geschweiften Klammern auf derselben Zeile befinden, nimmt das Skript sie in den Kommentar auf.

Aufrufen von Funktionen in einem Skript

Wenn Sie eine Funktion in Ihrem Skript verwenden möchten, müssen Sie sie aufrufen. Sie können eine Funktion mit drei verschiedenen Methoden aufrufen. Nicht jede Methode ist für alle Funktionen geeignet. Die Methoden, die für eine bestimmte Funktion verfügbar sind, richten sich danach, ob die Funktion einen Wert zurückgibt. Sie können eine Funktion folgendermaßen aufrufen:

• Alleine, wie eine Anweisung. Diese Methode ist für alle Funktionen geeignet.
• An einer Stelle, an der Sie eine Variable oder einen Ausdruck verwenden würden. Diese Methode eignet sich nur für Funktionen, die einen Wert zurückgeben.
• Mit einer Variable mithilfe der Punkt-Schreibweise. Diese Methode eignet sich nur für Funktionen, die einen Wert zurückgeben.

Aufrufen einer Funktion als Anweisung

Eine Anweisung ist eine Codezeile, die ein Befehlsschlüsselwort enthält, das dem Skript mitteilt, welche Aktionen es ausführen soll. Sie können eine Funktion wie eine Anweisung verwenden. In diesem Fall benötigen Sie im Gegensatz zu anderen Anweisungen in einem Snippet kein besonderes Befehlsschlüsselwort. Der Code in der Funktion teilt dem Skript mit, welche Aktionen es ausführen soll.

Sie können jede Funktion wie eine Anweisung aufrufen. Eine Funktion ohne RETURN-Anweisung kann nur mit dieser Methode aufgerufen werden. Grund hierfür ist, dass eine RETURN-Anweisung Daten von der Funktion an das Skript zurückgibt. Wenn keine RETURN-Anweisung vorhanden ist, kann das Skript nur auf die Daten in der Funktion zugreifen, wenn sie als Anweisung aufgerufen wird.

Für das Aufrufen einer Funktion als Anweisung gilt die folgende Syntax:

<functionName><([parameter], [parameter], [...])>

Das folgende Beispiel zeigt, wie die Funktion append() als Anweisung aufgerufen wird:

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Verwenden einer Funktion anstelle einer Variablen

Eine Funktion, die einen Wert zurückgibt, kann überall dort verwendet werden, wo eine Variable oder ein Ausdruck verwendet werden könnte. Das Skript kann den von der Funktion zurückgegebenen Wert genau wie den Wert der Variablen oder das Ergebnis des Ausdrucks verwenden.

Für die Verwendung einer Funktion anstelle einer Variablen gilt die folgende Syntax:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}