jsonEncode()

The function encodes data into an JSON format string.

Synopsis

string jsonEncode(anytype any [, bool compactFormat = true | mapping options])

Parameters

Parameter Description
any The variable that is encoded. You can pass either a simple data type, a dyn_, a mapping, a simple value, a vector, a class or a struct.
compactFormat

Output format:

Compact (TRUE/1)

Output on one line (Default):

{"key_1":"1_123456","key_2":"2_123456","key_3":"3_123456","key_4":"4_123456","key_5":"5_123456","key_6":"6_123456","key_7":"7_123456"}
Indented (FALSE/0)

Output with line breaks:

{
 "key_1": "1_123456",
 "key_2": "2_123456",
 "key_3": "3_123456",
 "key_4": "4_123456",
 "key_5": "5_123456",
 "key_6": "6_123456",
 "key_7": "7_123456"   
}
options
compactFormat (bool)
Same meaning and default value as the already existing 2nd parameter compactFormat
timeAsMilliSeconds (bool)
If true, time values are converted to milliseconds since Epoch instead of UTC time strings
langIdx (int)
If given and non-negative, langStrings are returned as a single string translated for the given language instead of an object containing all translations. The index of the first language is 0; if the langIdx is greater or equal to the number of project languages, the translation for the first language is returned.
keepNanInf
By default, float values Nan and Inf are changed to null value. When setting this option to true this conversion can be deactivated.

Return value

JSON encoded string

Description

JSON is a data exchange format and uses human-readable text for transmitting data objects. JSON builds two structures:

  • Name/value pairs. In different languages this is implemented as an object (object), a set (record), a structure (struct), a dictionary or a directory (dictionary), a hash table (hash table), a key list (keyed list) or as an associative array (associative array).

  • An ordered list of values. In most languages it is implemented as an array, a vector or a list.

It is largely used instead of XML. Furthermore, it is used for asynchronous browser/server communication (AJAX).

The JSON text format is independent of programming languages and is therefore ideally suited for data exchange.

The function encodes:

  • a simple data type as an array with one element
  • a dyn_ as a JSON array
  • a mapping as a JSON object
  • a simple value or an enum as a string
  • a class or a struct as JSON object.
  • a vector as array

Thus, you can pass either a dyn_data type, a mapping, a simple value, an enum, a vector or a class/struct.

Restriction: A mapping is only allowed with string keys.

Other data types are handled as a 1 element dyn_ array of its type. Passing the int value 1, for example, is the same as if you would pass makeDynInt(1).

Note:

Since JSON only understands numeric and string data types, most of the WinCC OAdata types are converted to strings.

There are, however some exceptions:

  • atime -> object with elements:time, count, dpid
  • errClass -> object with elements: prio, type, id, text
  • langString -> object with one element per language
  • nullptr -> object with the JSON value of null
Note:

A data type of time is always encoded in ISO-8601 format in UTC timezone, according to:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString

Attention: The integer limits for IEEE 754 double precision data is 2^53 (-9007199254740992 to +9007199254740992). If values outside of these boundaries are passed into JSON, a loss of precision occurs.
Note:

The CTRL function jsonEncode() and C++ method JSONConverter::encode() produces non-standard JSON for "NaN" and "Inf" values. Those values are not recognized by normal JSON parsers as they are not part of JSON standard, which in this case defines usage of "null" instead.

"NaN" and "Inf" values are still recognized during JSON decoding as before, but will by default no longer be produced during JSON encoding.

If you need to still use non-standard behaviour in C++, use JSONConverter::encodeKeepNanInf() method instead.

For CTRL, insert the "keepNanInfo" attribute into JSON mapping as follows:

jsonEncode(data, makeMapping("keepNanInf", true));

The following example encodes a mapping as a string and writes it to the file tfile.TXT. The output format with line breaks is used.

main()
{
  mapping mMappe = makeMapping("key_1","1_123456",
  "key_2","2_123456",
  "key_3","3_123456",
  "key_4","4_123456",
  "key_5","5_123456",
  "key_6","6_123456",
  "key_7","7_123456");
  string s = jsonEncode(mMappe, 0); /* Encode the Mapping and defines the output format "Indented"      (Format with line breaks) */
  file f=fopen("C:/TEMP/tfile.TXT","w+"); //Open a file
  fprintf(f,s+"%s","");
  fclose(f); //Closes the file
  DebugTN(s);
}

Output:

WCCOAui1:2016.02.18 10:15:52.350["{
 WCCOAui1: \"key_1\": \"1_123456\",
 WCCOAui1: \"key_2\": \"2_123456\",
 WCCOAui1: \"key_3\": \"3_123456\",
 WCCOAui1: \"key_4\": \"4_123456\",
 WCCOAui1: \"key_5\": \"5_123456\",
 WCCOAui1: \"key_6\": \"6_123456\",
 WCCOAui1: \"key_7\": \"7_123456\"
 WCCOAui1:}
 WCCOAui1:"]

Assignment

Misc. Functions

Availability

UI, CTRL