Topic: DMD0455
JSONBUILD - Build JSON Record
Note: this instruction can only be used with a BRX CPU !
The Build JSON Record (JSONBUILD) instruction is used to construct a JSON-formatted record using Numeric, String, and Boolean data from the PLC.
JSON records contain Arrays or Objects. Arrays contain a list of Values enclosed in square brackets. Objects are enclosed in curly brackets, and contain Field Name / Value pairs. A Field Name is text within double quotes; this can be either a String or a string literal. A Value can be text in double quotes, a String, a number, true, false, null, an Array, or another Object. Nested Objects are allowed. They are created by using separate JSONBUILD instructions, one to create the Value that is an Array or an Object, and another to add the Field Name for that Value. The instruction will automatically add the required enclosing brackets for Objects and enclosing brackets for Arrays.
Record Type selects the type of JSON element to create, enclosing the record with the proper bracket (curly vs. square), and using commas to separate the elements:
An { Object } is an unordered set of Field Name / Value pairs. JSONBUILD will automatically add the required beginning { (left brace) and ending } (right brace) to the Object.
Field Name is ASCII text, either a string literal (enclosed in double quotes), or a user-defined or system-defined String containing the ASCII text enclosed with double quotes.
Field Type / Value is one of the following:
A Numeric value from a PLC Numeric memory location or any constant value.
A Boolean value of false will be used if the specified Bit is OFF or the Numeric memory location contains a zero, a value of true will be used if the specified Bit is ON or Numeric memory location contains a non-zero value.
A String / Object / Array value can be from a string element or from a string literal. That string can be any of the following:
String is a sequence of zero or more Unicode characters, enclosed in double quotes. To use the keywords "true", "false", or "null" enter the keyword enclosed in double quotes.
The output from a previous JSONBUILD that is an Object.
The output from a previous JSONBUILD that is an Array.
If enabled, the Enclose in quotes option will enclose the string element with double quotes to make it a JSON String Value Type, applying backslash escape characters where necessary (embedded double quotes, backslashes, and control characters).
The Example field at the bottom will display a sample of the what the output will look like using the currently selected options.
An [ Array ] is an ordered collection of values of the same type. JSONBUILD will automatically add required beginning [ (left bracket) and ending ] (right bracket), and , (commas) that separate the individual array values.
A Numeric value from a PLC numeric memory location, a constant decimal value, or a constant value.
A Boolean value of false will be used if the specified Bit is OFF or Numeric memory location contains a value of zero; a Boolean value of true will be used if the specified Bit is ON or the Numeric memory location contains a non-zero value.
A String / Object / Array value can be from a string element or from a string literal. That string can be any of the following:
String is a sequence of zero or more Unicode characters, enclosed in double quotes. To use the keywords "true", "false", or "null" enter the keyword enclosed in double quotes.
The output from a previous JSONBUILD that is an Object.
The output from a previous JSONBUILD that is an Array.
If enabled, the Enclose in quotes option will enclose the string element with double quotes to make it a JSON String Value Type, applying backslash escape characters where necessary (embedded double quotes, backslashes, and control characters).
The Range of Array Elements specifies the size of the array.
Number of Elements is the number of contiguous Elements to add to the Array.
Range shows the first and last Element in the Array as defined by the current selections.
The Example field at the bottom will display a sample of the what the output will look like using the selected options.
Each JSONBUILD instruction can have up to 50 entries in the Field Name / Value pair table. The buttons below the table manage the contents of the table and their order within the table:
Add will add a new row at the end of the table.
Insert will add an empty row above the currently highlighted row in the table.
Insert Structure Fields will open a dialog where you can select an existing User Defined Structure or System Structure and have the fields from that structure added to the JSON output at the current location.
Structure Element is the structure that has the fields to add to the JSON record.
Fields to Include selects which fields from the structure to include in the JSON record: Most Useful Fields will include all from the structure except those marked as Do Not Show Field in Structure Status; All Fields will add all of the fields in the structure.
Format Bit Field Values as selects the data format to use in the JSON record that are Bit fields in the structure: Boolean (true, false) will set the JSON record format for Bit fields to use the keywords true and false, or Numeric (1, 0) will set the JSON record format for Bit fields to use a numeric 0 or 1.
After clicking the OK button you can edit the newly generated fields in the JSON record as needed.
Edit will open the contents of the highlighted row in the Object Editor.
Remove will delete the currently highlighted row from the table.
Move Up / Move Down will reposition the selected row one position toward the top or the bottom of the table respectively.
The JSON Output Record selects where to store the newly created JSON record in the BRX CPU. Strings are the preferred storage locations for the JSON records because of the ease of working with Strings using other instructions and tools within Do-more Designer. If the JSON record will contain 1024 characters or less then always use a String. If the JSON record is more than 1024 characters you will need to store the JSON record in the PLC in a Numeric Data Block of Bytes. Be aware when the data is stored this way you will not be able use any of the string manipulation instructions to process the data. Note: use the JSON Pretty Print utility to see the output record formatted for readability.
Select String to store the JSON record in a system-defined String, or a user-defined String.
Select Numeric Data Block Containing Text to store the JSON record in a numeric data block of bytes (a byte buffer).
Click Create Byte Buffer... to create a new data block of bytes to store the JSON record. You will need to specify the Data Block Name (1 to 16 letters) names must be unique, and consist of 1 to 16 characters (A-Z, a-z; no numbers, no spaces). The default name is JSONBUILDBuff, but it can be changed. You will also specify Number of Elements is the number of bytes (maximum of 65000) in the data block. The data blocks must be created on a DWord (4-byte) boundary. And specify whether to Make Data Block Retentive (retain values after power loss) will have the data block hold its state through a power cycle or a Program-to-Run mode transition. Memory NOT marked as retentive will be cleared at power up and during a Program-to-Run mode transition.
Output Record Start Address is the beginning offset into the specified byte buffer to begin storing the JSON record.
Buffer Size in Bytes is the maximum number of characters you want to allow the output record to use in the specified Byte buffer. This can be any constant value from 1 to the maximum size of the Byte buffer.
Buffer Range displays the beginning and ending address of the Buffer.
Number of Bytes Generated is a numeric location that will contain the number of contiguous bytes the JSON record consumed in the specified Byte buffer. This can be any writable numeric location.
Note: when using a Numeric Data Buffer to store the text for the JSON Output Record, use the Memory View with ASCII format to see the contents of the Numeric Data Buffer in readable text form.
Status Display
See Also
Related Topics
HTTPCMD - HTTP Request / Response with Server
MQTTPUB - IoT Publish MQTT Topics
MQTTSUB - IoT Subscribe to MQTT Topics
Example
