Mit jedem Technologie Refresh gibt es neue und erweiterte Built-In-Functionen. So auch in Release 7.5 TR3. In diesem Artikel werden die neuen und erweiterten Built-In-Funktionen im Detail beschrieben.

String-Funktionen:

**%LEFT(string : length { : NATURAL | STDCHARSIZE } )**

Bei der Built-In-Function %LEFT() werden, ausgehend von der linken Seite des angegebenen Strings, die angegebene Anzahl an Zeichen oder Byte ermittelt. Die Built-In-Function kann als Syntax-Alternative für die Funktion %SUBST() angesehen werden, bei der die Start-Position 1 ist.

Sofern bei dieser Funktion mit dem Natural Language Support gearbeitet werden soll, muss für den 3. Parameter das Literal *NATURAL angegeben werden. Da per Default alle String-Funktionen die Positionen der einzelnen Zeichen in Byte ausgeben, ist diese Erweiterung dann extrem wichtig, wenn mit UTF-8 (CCSID 1208) gearbeitet wird. In UTF-8 kann ein Zeichen, 1, 2, 3 oder 4 Byte lang sein. Bei einer Längenangabe in Byte kann es damit zu falschen Ergebnissen kommen. Wird *NATURAL als 3. Parameter angegeben, werden die Positionen und Längen-Angaben in Anzahl Zeichen verarbeitet.

Anmerkung: Alle String-Funktionen wurden um einen zusätzlichen Parameter erweitert, in dem durch die Angabe von *NATURAL der Natural Language Support unterstützt wird.

Der folgende Source Code zeigt einige Beispiele, wie die Funktion %LEFT() eingesetzt werden kann.

Zunächst werden von der alphanumerischen Variable GblText, die mit ‘ABCDEFGHIJK‘ gefüllt wurde, die ersten 3 Zeichen, also ‘ABC‘ in die Variable GblResult übernommen.

Im zweiten Fall werden aus der vorgegebenen Konstante ‘Anderer Text‘ die ersten 8 Zeichen (also ‘Anderer‘) in die Variable GblResult übernommen.

Bei dem letzten Beispiel wird die Variable GblText mit einer Zahl mit Tausender-Trennzeichen und einem Dezimal-Komma gefüllt. Ausgehend von der linken Seite des String wird mit Hilfe der Funktion %SCAN() nach dem Dezimal-Trennzeichen gesucht und alle Zeichen davor in die Variable GblResult übernommen.

Da es sich bei allen Variablen um Single-Byte-Variablen handelt, liefert die Built-In-Function %LEFT() auch ohne den Natural Language Support (ohne *NATURAL) das korrekte Ergebnis zurück.

%RIGHT(string : length { : NATURAL | STDCHARSIZE } )

Bei der Built-In-Function %RIGHT() werden, ausgehend von der rechten Seite des Strings, die angegebene Anzahl an Zeichen zurückgegeben. Sofern bei dieser Funktion mit dem Natural Language Support gearbeitet werden soll, muss im 3. Parameter das Literal *NATURAL angegeben werden.

Achtung: bei Variablen mit fixer Länge! Folgende *Blanks müssen zunächst abgetrimmt werden!

In dem folgenden Beispiel werden von Variablen, die mit fixer und variabler Länge definiert sind, die letzten 4 Zeichen ermittelt.

Im ersten Fall handelt es sich um eine Variable mit variabler Länge und so werden die letzten 4 Zeichen (in diesem Fall ‘GmbH‘) in die Variable Result übernommen.

Bei der Variablen GblTextFix handelt es sich um eine Variable mit fixer Länge, d.h. nach dem eigentlichen Text folgt eine Reihe von Leerzeichen. Mit der Funktion %RIGHT() werden die letzten 4 Zeichen in die Variable GblResult übernommen. In diesem Fall handelt es sich um 4 Leerzeichen.

Um tatsächlich die letzten 4 Zeichen aus einer Variable mit fixer Länge zu ermitteln, müssen zunächst die folgenden Blanks, entweder mit der Built-In-Function %TRIM() oder der Built-In-Function %TRIMR() entfernt werden. Wie im letzten Beispiel gezeigt.

Da es sich bei allen Variablen um Single-Byte-Variablen handelt, liefert die Built-In-Function %RIGHT() auch ohne den Natural Language Support (ohne *NATURAL) das korrekte Ergebnis zurück.

%SPLIT(string {: separators { : ALLSEP {: NATURAL | *STDCHARSIZE}}})

Mit Hilfe der Funktion %SPLIT kann ein String in mehrere Array-Elemente aufgeteilt werden. Im ersten Parameter wird der String, der aufgeteilt werden soll, übergeben. Im zweiten Parameter wird das oder die Trennzeichen angegeben, bei denen aufgeteilt werden soll. Wird der zweite Parameter nicht übergeben, so wird bei Leerzeichen (*BLANK) aufgeteilt.

In dem folgenden Beispiel wird die ISO-Länderliste in die einzelnen Länder aufgeteilt. Die Länder sind durch ein Komma und ein Leerzeichen voneinander getrennt.

So weit so gut! Was passiert jedoch, wenn mehrere Trennzeichen aufeinander folgen? In diesem Fall werden per Default keine leeren Feldgruppen-Elemente produziert. Jetzt könnte es jedoch sein, dass bei aufeinanderfolgenden Trennzeichen genau diese leeren Elemente benötigt werden.

Aus diesem Grund wurde die Built-In-Function %SPLIT() um einen zusätzlichen optionalen Parameter erweitert, in dem der Sonderwert *ALLSEP angegeben werden kann. Wird die Funktion mit dem Sonderwert *ALLSEP aufgerufen, werden bei aufeinanderfolgenden Trennzeichen leere Elemente gebildet. Ohne *ALLSEP werden nur die „gefüllten“ Elemente ausgegeben.

In dem folgenden Beispiel folgen auf CA und FR mehrere Trennzeichen (,). Der Screen Shot zeigt den Aufruf und das Ergebnis mit und ohne den Sonderwert *ALLSEP. Beim Aufsplitten des Strings mit *ALLSEP werden nach CA zwei leere Elemente (3 aufeinander folgende Trennzeichen) und nach FR ein leeres Element (2 aufeinanderfolgende Trennzeichen) generiert.

Built-In-Function %SPLIT() mit und ohne Sonderwert *ALLSEP

Um Probleme mit Unicode-Strings zu vermeiden kann auch für diese Built-In-Function der Natural Language Support durch die Angabe des Literals *NATURAL in Form eines weiteren Parameters aktiviert werden.

Built-In-Functionen zum Prüfen von übergebenen Parametern

%PASSED (Return Parameter-Passed Condition)

Mit Hilfe der Built-In-Function %PARMS kann festgestellt werden, wieviele Parameter übergeben wurden.

Parameter am Ende der Parameter-Liste können mit der Option OPTIONS(*NOPASS) als optionale Parameter definiert werden. Mit der OPTION(*OMIT) ist es möglich Parameter so zu definieren, dass anstelle des Parameters der Sonderwert *OMIT (und dadurch ein NULL-Pointer) übergeben werden kann. Nicht übergebene Parameter dürfen innerhalb der Prozedur nicht angesprochen werden, da es ansonsten einen Abbruch mit Pointer-Fehler gibt.

Die Prüfung, ob Parameter übergeben wurden oder nicht war insbesondere dann etwas tricky, wenn der Parameter sowohl mit *NOPASS als auch *OMIT definiert wurde.

Mit Hilfe der neuen Built-In-Function %PASSED(Parameter) ist die Prüfung, ob ein Parameter übergeben wurde oder nicht wesentlich einfacher geworden. %PASSED(Parameter) liefert *OFF, wenn der Parameter entweder nicht oder mit dem Sonderwert *OMIT übergeben wurde.

%OMITTED (Return Parameter-Omitted Condition)

Mit Hilfe der neuen Built-In-Function %OMITTED(Parameter) kann festgestellt werden, ob der Parameter mit dem Sonderwert *OMIT übergeben wurde. %OMITTED(Parameter) liefert nur dann *ON zurück, wenn anstelle des mit OPTIONS(*OMIT) definierten Parameters der Sonderwert *OMIT übergeben wurde.

In dem folgenden Beispiel wird zunächst geprüft, ob der Parameter ParNoPassOmit übergeben wurde oder nicht.

Im ersten IF wird mit Hilfe der Built-In-Function %PASSED() geprüft, ob er Parameter ParNoPassOmit mit einem Wert übergeben wurde.

Da %PASSED() *OFF zurückliefert, ein Parameter jedoch mit dem Sonderwert *OMIT übergeben werden kann, wird im ELSEIF zusätzlich geprüft, ob der Parameter mit *OMIT übergeben wurde oder nicht.