@JsonSerialize

Diese @Function serialisiert ein JSON-Object oder JSON-Array und gibt dessen vollständige JSON-Textdarstellung zurück.

Die erzeugte JSON-Darstellung wird im kompakten Format ohne zusätzliche Einrückungen oder Zeilenumbrüche ausgegeben. Strings innerhalb des JSON werden in UTF-8 ausgegeben.
Standardmäßig wird das serialisierte JSON als VSPECBINBUFFER zurückgegeben. Dadurch können auch JSON-Strukturen serialisiert werden, deren Textdarstellung die maximale Größe eines normalen TEXT-Wertes überschreitet.
Optional kann mit TEXT RETURNTYPE der Wert "A" angegeben werden. In diesem Fall wird das Ergebnis als TEXT zurückgegeben.
Überschreitet die serialisierte JSON-Darstellung dabei die maximal zulässige Größe eines TEXT-Wertes, liefert die Funktion @ERROR.

Das übergebene VSPECHJSON (HJS) Handle bleibt unverändert und weiterhin gültig. Es muss nach seiner Verwendung separat mit @JsonRelease freigegeben werden.

VSPECHJSON HJSON:
Handle des zu serialisierenden JSON-Objects oder JSON-Arrays.
HJSON muss ein gültiges VSPECHJSON (HJS) Handle enthalten.

TEXT RETURNTYPE:
Optionaler Typ des Return-Wertes.
"A" Rückgabe als TEXT

Die Angabe ist nicht case-sensitiv. Wird RETURNTYPE nicht angegeben, erfolgt die Rückgabe als VSPECBINBUFFER.
Nach der aktuellen Implementierung führen auch andere Textwerte als "A" zur standardmäßigen Rückgabe als VSPECBINBUFFER.

Als Return-Wert liefert die @Function bei einem Fehler @ERROR, andernfalls die serialisierte JSON-Darstellung als VSPECBINBUFFER oder TEXT.

Beispiel: @JsonSerialize(HJSON);

HJSON:=@JsonCreate("Array");
@JsonAdd(HJSON;"Text1");
@JsonAdd(HJSON;"Text2");
@JsonAdd(HJSON;100);
JSONBUFFER:=@JsonSerialize(HJSON);
@JsonRelease(HJSON);

Das Beispiel erzeugt ein JSON-Array und serialisiert es anschließend mit dem standardmäßigen Return-Typ als VSPECBINBUFFER.
Der Buffer enthält die UTF-8-kodierte JSON-Darstellung:
["Text1","Text2",100.0]
Die Rückgabe als VSPECBINBUFFER eignet sich insbesondere für große JSON-Strukturen und für die direkte Weiterverarbeitung beispielsweise in HTTP- oder REST-Anfragen.

Beispiel: @JsonSerialize(HJSON;RETURNTYPE);

HJSON:=@JsonCreate;
@JsonAdd(HJSON;"Max Mustermann";"Name");
@JsonAdd(HJSON;42;"Age");
@JsonAdd(HJSON;TRUE;"Active";"B");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

Das Beispiel erzeugt ein JSON-Object, fügt drei Werte hinzu und serialisiert die vollständige JSON-Struktur anschließend als TEXT.
Der Inhalt von JSONTEXT lautet:
{"Name":"Max Mustermann","Age":42.0,"Active":true}
Das JSON-Handle bleibt durch @JsonSerialize unverändert und wird anschließend mit @JsonRelease wieder freigegeben.