@JsonGet

Diese @Function liest einen Wert aus einem bestehenden JSON-Object oder JSON-Array und wandelt ihn, soweit möglich, in einen entsprechenden Engine-Datentyp um.

Das Verhalten des zweiten Parameters hängt davon ab, ob HJSON auf ein JSON-Object oder ein JSON-Array verweist.
Bei einem JSON-Object muss der zweite Parameter ein TEXT KEY sein. Der Wert des angegebenen Keys wird zurückgegeben.
Bei einem JSON-Array muss der zweite Parameter ein numerischer FN INDEX sein. JSON-Arrays verwenden eine 0-basierte Indizierung, das erste Element besitzt daher den Index 0.

Der optionale Parameter TEXT OPTIONS beeinflusst den Return-Typ sowie die Behandlung von JSON-Strings. Mehrere Optionen können innerhalb eines Strings kombiniert werden.

Wird ein JSON-Object oder JSON-Array zurückgegeben, erzeugt @JsonGet dafür ein eigenes VSPECHJSON (HJS) Handle. Dieses Handle muss nach seiner Verwendung mit @JsonRelease wieder freigegeben werden.

Kann der angegebene Key beziehungsweise Array-Index nicht gefunden werden, liefert die Funktion @ERROR.

Als Return-Wert liefert die @Function bei einem Fehler @ERROR, andernfalls den ermittelten JSON-Wert in einem geeigneten Engine-Datentyp.

VSPECHJSON HJSON:
Handle des JSON-Objects oder JSON-Arrays, aus dem ein Wert gelesen werden soll.
HJSON muss ein gültiges VSPECHJSON (HJS) Handle enthalten, das auf ein JSON-Object oder JSON-Array verweist.

TEXT KEY:
Key des aus einem JSON-Object zu lesenden Wertes.
Der Parameter muss bei einem JSON-Object vom Typ TEXT sein.

Beispiel:
HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Age\":42}");
NAME:=@JsonGet(HJSON;"Name");
liefert:
Max Mustermann

Existiert der angegebene Key nicht, liefert @JsonGet den @ERROR:
JSON VALUE NOT FOUND

FN INDEX:
Index des aus einem JSON-Array zu lesenden Elements.
Der Parameter kann als NUMBER oder FLOAT angegeben werden.
Die Indizierung von JSON-Arrays beginnt bei 0.

Beispiel:
HJSON:=@JsonLoad("[\"A\",\"B\",\"C\"]");
VALUE:=@JsonGet(HJSON;1);
liefert:
B

Bei einem FLOAT-Index wird der Wert bei der Umwandlung in den Array-Index auf einen ganzzahligen Wert reduziert.

Beispielsweise greift:
@JsonGet(HJSON;1.8);
auf Index 1 zu.

Negative Werte, nicht endliche Werte oder Indizes außerhalb des Arrays führen zu @ERROR:
JSON VALUE NOT FOUND

TEXT OPTIONS:
Optionaler Parameter zur Steuerung des Return-Typs beziehungsweise der Zeichensatzkonvertierung.

Folgende Optionen werden unterstützt:
"L" JSON-Array als Engine-Liste zurückgeben
"B" JSON-String als VSPECBINBUFFER zurückgeben
"H" JSON-String-Array als VHUGETEXTLIST zurückgeben
"T" JSON-Strings von UTF-8 nach LMBCS konvertieren
Die Optionen sind nicht case-sensitiv.

Mehrere Optionen können miteinander kombiniert werden, beispielsweise:
"LT"
"HT"
"BT"

"L", "B" und "H" bestimmen den Return-Typ. Werden mehrere dieser Optionen angegeben, gilt die zuletzt angegebene Return-Typ-Option.
Die Option "T" kann zusätzlich mit einer Return-Typ-Option kombiniert werden.
Unbekannte Optionen führen zu @ERROR:
INVALID JSON GET OPTION

Umsetzung der JSON-Datentypen
Ohne besondere Return-Type-Option erfolgt die Umsetzung folgendermaßen:

JSON String TEXT
JSON Integer FLOAT
JSON Real FLOAT
JSON Boolean NUMBER
JSON Object VSPECHJSON (HJS)
JSON Array VSPECHJSON (HJS)
JSON Null @ERROR

JSON String
Ein JSON-String wird standardmäßig als TEXT zurückgegeben.
VALUE:=@JsonGet(HJSON;"Name");

Ist der String größer als die maximal zulässige Größe eines normalen TEXT-Wertes, kann er mit der Option "B" als VSPECBINBUFFER zurückgegeben werden:
BUFFER:=@JsonGet(HJSON;"Data";"B");

Der Buffer enthält die exakten Bytes des JSON-Strings.
Die Optionen "L" und "H" ändern bei einem einzelnen JSON-String den Return-Typ nicht; der Wert wird weiterhin als TEXT zurückgegeben.

JSON Integer und JSON Real
JSON Integer und JSON Real werden als Engine-FLOAT zurückgegeben.

Beispiel:
HJSON:=@JsonLoad("{\"Count\":42,\"Value\":12.75}");
COUNT:=@JsonGet(HJSON;"Count");
VALUE:=@JsonGet(HJSON;"Value");

COUNT enthält dabei den numerischen Wert 42, VALUE den Wert 12.75.
Auch ein JSON Integer wird als Engine-FLOAT zurückgegeben.

JSON Boolean
Ein JSON Boolean wird als Engine-NUMBER zurückgegeben.
false 0
true 1

Beispiel:
HJSON:=@JsonLoad("{\"Active\":true}");
ACTIVE:=@JsonGet(HJSON;"Active");

liefert:
1

JSON Object
Ein innerhalb der JSON-Struktur enthaltenes JSON-Object wird als neues VSPECHJSON (HJS) Handle zurückgegeben.

Beispiel:
HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Address\":{\"City\":\"Berlin\",\"Country\":\"Deutschland\"}}");
HADDRESS:=@JsonGet(HJSON;"Address");
CITY:=@JsonGet(HADDRESS;"City");
@JsonRelease(HADDRESS);
@JsonRelease(HJSON);

HADDRESS verweist auf das innerhalb des ursprünglichen JSON enthaltene Object:
{
"City":"Berlin",
"Country":"Deutschland"
}

Das von @JsonGet erzeugte Handle besitzt eine eigene Referenz auf diese JSON-Struktur. Es bleibt deshalb auch unabhängig vom ursprünglichen Handle gültig und muss separat mit @JsonRelease freigegeben werden.

JSON Array
Ein JSON-Array wird standardmäßig ebenfalls als neues VSPECHJSON (HJS) Handle zurückgegeben.

Beispiel:
HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"]}");
HNAMES:=@JsonGet(HJSON;"Names");
NAME:=@JsonGet(HNAMES;1);
@JsonRelease(HNAMES);
@JsonRelease(HJSON);

NAME enthält:
Bernd

Alternativ kann versucht werden, das JSON-Array in eine Engine-Liste umzuwandeln.

Option "L" – Array als Engine-Liste
Mit "L" wird ein JSON-Array nach Möglichkeit in einen entsprechenden Engine-Listentyp umgewandelt.

Folgende Array-Typen können konvertiert werden:
JSON Array aus Strings TEXTLIST
JSON Array aus Boolean-Werten NUMBERLIST
JSON Array aus Zahlen FLOATLIST

Bei numerischen Arrays dürfen JSON Integer und JSON Real miteinander gemischt sein. Das Ergebnis ist in beiden Fällen eine FLOATLIST.

Beispiel:
HJSON:=@JsonLoad("{\"Values\":[10,20.5,30]}");
VALUES:=@JsonGet(HJSON;"Values";"L");

ergibt eine FLOATLIST mit:
10 : 20.5 : 30

Ein String-Array:
HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"]}");
NAMES:=@JsonGet(HJSON;"Names";"L");

wird als TEXTLIST zurückgegeben.

Option "H" – Array als VHUGETEXTLIST
Mit "H" kann ein JSON-Array aus Strings als VHUGETEXTLIST zurückgegeben werden.

Dies eignet sich insbesondere dann, wenn die String-Liste die Größenbeschränkung einer normalen TEXTLIST überschreiten könnte.

Beispiel:
NAMES:=@JsonGet(HJSON;"Names";"H");

Die Option "H" ist nur für JSON-Arrays aus Strings sinnvoll.

Konvertierbarkeit von JSON-Arrays
Für die Umwandlung eines JSON-Arrays in eine Engine-Liste müssen die Elemente kompatible Datentypen besitzen.

Ein Array wie:
["A","B","C"]
kann in eine TEXTLIST beziehungsweise VHUGETEXTLIST umgewandelt werden.

Ein Array wie:
[10,20.5,30]
kann in eine FLOATLIST umgewandelt werden. JSON Integer und JSON Real dürfen hierbei gemischt sein.

Ein Array wie:
[true,false,true]
kann in eine NUMBERLIST umgewandelt werden.

Gemischte Arrays wie:
["A",10,true]
können nicht in eine Engine-Liste umgewandelt werden.

Dasselbe gilt für Arrays, deren Elemente Objects, weitere Arrays oder null enthalten.
In diesen Fällen liefert @JsonGet beispielsweise:
UNABLE TO CONVERT JSON ARRAY WITH MIXED VALUES
oder:
JSON ARRAY NOT CONVERTIBLE TO ENGINE LIST

Auch ein leeres JSON-Array kann nicht automatisch in einen Engine-Listentyp umgewandelt werden, da kein Element vorhanden ist, anhand dessen der benötigte Listentyp bestimmt werden könnte.

Option "T" – UTF-8 nach LMBCS
JSON-Strings werden intern als UTF-8 gespeichert.
Mit der Option "T" kann ein zurückgegebener JSON-String von UTF-8 nach LMBCS konvertiert werden.

Beispiel:
NAME:=@JsonGet(HJSON;"Name";"T");
Die Option kann auch mit anderen Optionen kombiniert werden:

BUFFER:=@JsonGet(HJSON;"Text";"BT");
NAMES:=@JsonGet(HJSON;"Names";"LT");
HUGENAMES:=@JsonGet(HJSON;"Names";"HT");

Bei "LT" werden beispielsweise alle Strings eines JSON-Arrays nach LMBCS konvertiert und anschließend als TEXTLIST zurückgegeben.
Bei "HT" erfolgt die entsprechende Konvertierung für eine VHUGETEXTLIST.

Die Option "T" wirkt nur auf JSON-Strings. Numerische Werte, Boolean-Werte sowie JSON-Objects werden dadurch nicht verändert.
Wird "T" allein auf ein JSON-Array angewendet, bleibt der standardmäßige Return-Typ des Arrays ein VSPECHJSON (HJS) Handle; eine Konvertierung der enthaltenen Strings findet in diesem Fall nicht statt.

JSON Null
Ein JSON-null besitzt keinen direkt entsprechenden Engine-Datentyp und kann daher von @JsonGet nicht zurückgegeben werden.

Beispiel:
{"Value":null}
VALUE:=@JsonGet(HJSON;"Value");

führt zu:
JSON NULL VALUE CANNOT BE REPRESENTED

Hinweise:
Ein von @JsonGet zurückgegebenes VSPECHJSON (HJS) Handle besitzt eine eigene Referenz auf das entsprechende JSON-Object beziehungsweise JSON-Array.
Das ursprüngliche JSON-Handle und das von @JsonGet erzeugte Handle können deshalb unabhängig voneinander mit @JsonRelease freigegeben werden.

Bei JSON-Arrays verwendet @JsonGet die in JSON übliche 0-basierte Indizierung:
0 erstes Element
1 zweites Element
2 drittes Element
…

Beispiel: Werte aus einem JSON-Object lesen

HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Age\":42,\"Active\":true,\"Score\":78.5}");
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
ACTIVE:=@JsonGet(HJSON;"Active");
SCORE:=@JsonGet(HJSON;"Score");
@JsonRelease(HJSON);

Die Return-Werte entsprechen:
NAME "Max Mustermann"
AGE 42
ACTIVE 1
SCORE 78.5

Beispiel: Array auslesen

HJSON:=@JsonLoad("[\"Text1\",\"Text2\",\"Text3\"]");
VALUE1:=@JsonGet(HJSON;0);
VALUE2:=@JsonGet(HJSON;1);
VALUE3:=@JsonGet(HJSON;2);
@JsonRelease(HJSON);

Die Werte entsprechen:
VALUE1 "Text1"
VALUE2 "Text2"
VALUE3 "Text3"

Beispiel: JSON-Array als Liste übernehmen

HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"],\"Values\":[10,20,30]}");
NAMES:=@JsonGet(HJSON;"Names";"L");
VALUES:=@JsonGet(HJSON;"Values";"L");
@JsonRelease(HJSON);

NAMES wird als TEXTLIST, VALUES als FLOATLIST zurückgegeben.