Schlüsselwortreferenz

Func...Return...EndFunc

Definiert eine Benutzerfunktion, die Null oder mehr Argumente aufnimmt und optional ein Ergebnis zurückgibt.

Func functioname ( [Const] [ByRef] $param1, ..., [Const] [ByRef] $paramN, $optionalpar1 = value, ...)
    ...
    [Return [value]]
EndFunc

 

Parameter

Die Parameter werden vom Benutzer selbst gewählt. Später werden sie genau wie die eingebauten Funktionen aufgerufen.

 

Bemerkungen

Das Schlüsselwort Const ist optional und zeigt an, dass sich der Wert des Parameters während der Ausführung der Funktion nicht ändert. Eine als Const deklarierte Variable kann eine Funktion nur durchlaufen, wenn der Const Parameter verwendet wird.

Das Schlüsselwort ByRef zeigt an, dass der Parameter als Referenz zu dem Originalobjekt behandelt werden soll. Standardmäßig wird der Parameter in eine neue Variable kopiert. Jedoch verknüpft ByRef die neue Varaible auf den Originalparameter. ByRef ist zu bevorzugen wenn eine Funktion große Mengen an Daten beinhaltet wie zum Beispiel ein großen Array. Wird dies nicht getan, so erweist das kopieren aller Daten als Bremsklotz. Es ist zu beachten, dass nicht nur eine benannte Variable als ByRef Parameter übergeben werden kann; unbenannte temporäre Variablen, wie zum Beispiel Rückgabewerte von Funktionen, können genauso als ByRef Parameter übergeben werden. Ein Buchstabe kann jedoch nicht als ByRef Parameter übergeben werden.

Falls beide Schlüsselwörter (ByRef und Const) mit einem Funktionsparameter verwendet werden, so ist die Reihenfolge der Schlüsselwörter ByRef und Const nicht wichtig, solange sie vor der zu verändernden Variable stehen.

Komplette Arrays können an Funktionen über- und von ihnen zurückgegeben werden, indem einfach der Arrayname ohne Klammern angegeben wird. Arrays sollten an eine benutzerdefinierte Funktion nur mit dem Schlüsselwort ByRef übergeben werden, da somit das unnötige und langwierige Kopieren der kompletten Daten des Arrays vermieden wird.

Optionale Parameter werden definiert, indem man ihnen einen Standardwert zuweist. Das kann eine globale Variable, ein Makro oder Literal sein.
Optionale Parameter erscheinen immer am Ende der Funktionsdeklaration. Wurde ein Parameter als optional deklariert, müssen alle folgenden Parameter ebenfalls optional sein und Standardwerte erhalten.
Innerhalb der Funktion kann die Anzahl der beim Aufruf angegebenen Parameter über das Makro @NUMPARAMS in Erfahrung gebracht werden. (siehe Beispiel 2)

Mit dem Schlüsselwort Return wird die Funktion verlassen. Im Gegensatz zu den eingebauten Funktionen geben benutzerdefinierte Funktionen immer 0 zurück, sofern kein anderer Returnwert gesetzt wurde.

Es ist zu beachten, dass Funktionsdeklarationen nicht innerhalb anderer Funktionsdeklarationen stattfinden dürfen.

 

Verwandte Funktionen

Dim/Global/Local, #include, Const

 

Beispiel


Opt('MustDeclareVars', 1)

Example1()
Example2()

; example1
Func Example1()
; Beispielskript mit drei benutzerdefinierten Funktionen
; Beachten sie die Nutzung von Variablen, ByRef und Return

Local $foo = 2
Local $bar = 5
MsgBox(0,"Heute ist der " & Datum(), "$foo hat den Wert " & $foo)
Vertauschen($foo, $bar)
MsgBox(0,"Nach dem Tausch von $foo und $bar", "enthält $foo jetzt " & $foo)
MsgBox(0,"Zum Schluss", "Der größere Wert von 3 und 4 ist " & Groesser(3,4))
EndFunc   ;==>Example1

Func Vertauschen(ByRef $a, ByRef $b)  ; Vertauscht den Inhalt zweier Variablen
    Local $t
    $t = $a
    $a = $b
    $b = $t
EndFunc

Func Datum()  ; Gibt das aktuelle Datum in der Form Tag.Monat.Jahr zurück.
return (@MDAY & "." & @MON & "." & @YEAR)
EndFunc

Func Groesser($x, $y)  ; Gibt die größere von zwei Zahlen zurück.
    If $x > $y Then
        return $x
    Else
        return $y
    EndIf
EndFunc

;Ende des Beispielskripts 1

; example2
Func Example2()
; Dieses Beispielskript verwendet @NumParams Makros
    Test_Numparams(1,2,3,4,5,6,7,8,9,10,11,12,13,14)
EndFunc   ;==>Example2

Func Test_Numparams($v1 = 0, $v2 = 0, $v3 = 0, $v4 = 0, $v5 = 0, $v6 = 0, $v7 = 0, $v8 = 0, $v9 = 0, _
    $v10 = 0, $v11 = 0, $v12 = 0, $v13 = 0, $v14 = 0, $v15 = 0, $v16 = 0, $v17 = 0, $v18 = 0, $v19 = 0)
    Local $val
    For $i = 1 To @NumParams
        $val &= Eval("v" & $i) & " "
    Next
    MsgBox(0, "@NumParams Beispiel", "@NumParams =" & @NumParams & @CRLF & @CRLF & $val)
EndFunc
 
;Ende des Beispielskripts 2