Variable arrays of elements in DFHJS2LS
JSON can contain arrays of varying numbers of elements. In general JSON Schemas that contain varying numbers of elements do not map efficiently into a single high-level language data structure. CICS® uses container-based mappings or inline mappings to handle varying numbers of elements in JSON data.
- The minItems keyword specifies the minimum number of times that the element can occur. It can have a value of 0 or any positive integer. It defaults to the value 0.
- The maxItems keyword specifies the maximum number of times that the element can occur. It can have a value of any positive integer greater than or equal to the value of the minItems keyword.
- If the maxItems keyword is missing it means the array is unbounded.
"properties":{
"component": {
"type":"array",
"maxItems":1,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]
The same effect can be produced
by not including the field name in the
"required"
keyword
value:
"properties":{
"component": {
"type": "string",
"maxLength": 8
}
}
- When CICS transforms JSON data to application data, it populates these structures with the application data and the application reads them.
- When CICS transforms the application data to JSON data, it reads the application data in the structures that have been populated by the application.
The following examples illustrate the format of these data structures. These examples use an array of simple 8-byte fields. However, the model supports arrays of complex data types and arrays of data types that contain other arrays.
Example 1. Fixed number of elements
"properties":{
"component": {
"type": "array",
"maxItems": 3,
"minItems": 3,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]
05 component PIC X(8) OCCURS 3 TIMES
Example 2. Varying number of elements at mapping level 2 and below
"properties":{
"component": {
"type": "array",
"maxItems": 5,
"minItems": 1,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]
05 component-num PIC S9(9) COMP-5
05 component-cont PIC X(16)
01 DFHJS-component
02 component PIC X(8)
You must examine the value of component-num , which will contain a value in the range 1 to 5, to find how many times the element occurs. The element contents are in the container named in component-cont ; the container holds an array of elements, where each element is mapped by the DFHJS-component data structure.
- If it is zero, the message has no component element and the contents of component-cont is undefined.
- If it is one, the component element is in the container named in component-cont.
Example 3. Variable number of elements at mapping level 2.1 and above
- The default value of INLINE-MAXOCCURS-LIMIT is 1 , which ensures that optional elements are mapped inline.
- A value of 0 for the INLINE-MAXOCCURS-LIMIT parameter prevents inline mapping.
- If maxItems is less than or equal to the value of INLINE-MAXOCCURS-LIMIT , inline mapping is used.
- If maxItems is greater than the value of INLINE-MAXOCCURS-LIMIT , container-based mapping is used.
05 component-num PIC S9(9) COMP-5 SYNC.
05 component OCCURS 5 PIC X(8).
The first field,
component-num
,
is identical to the output for the container-based mapping example
in the previous section. The second field contains an array of length
5 which is large enough to contain the maximum number of elements
that can be generated.
Inline mapping differs from container-based mapping, which stores the number of occurrences of the element and the name of the container where the data is placed, because it stores all the data in the current container. Storing the data in the current container will generally improve performance and make inline mapping preferable.
Example 4. Nested variable arrays
Complex JSON schemas can contain variable recurring elements, which in turn contain variable recurring elements. In this case, the structure described extends beyond the two levels described in the examples.
"properties":{
"component1": {
"type": "array",
"maxItems": 5,
"minItems": 1,
"items": {
"type": "object",
"properties":{
"component2":{
"type": "string",
"maxLength": 8
}
},
"required": ["component2"]
}
},
"required": ["component1"]
05 component1-num PIC S9(9) COMP-5
05 component1-cont PIC X(16)
However, the second data structure
contains these elements:
01 DFHJS-component1
02 component2-num PIC S9(9) COMP-5
02 component2-cont PIC X(16)
A third-level structure
contains these elements:
01 DFHJS-component2
02 component2 PIC X(8)
The number of occurrences of the outermost element "component1" is in component1-num.
The container named in component1-cont contains an array with that number of instances of the second data structure DFHJS-component1.
Each instance of component2-cont names a different container, each of which contains the data structure mapped by the third-level structure DFHJS-component2.
{"component1":
[
{
"component2": "string1"
},
{
"component2": "string2"
},
]
}
"component1"
occurs three times. The
first two contain an instance of
"component2"
; the
third instance does not.
- In the first, component2-num has a value of 1, and the container named in component2-cont holds string1.
- In the second, component2-num has a value of 1, and the container named in component2-cont holds string2.
- In the third, component2-num has a value of 0, and the contents of component2-cont are undefined.
- The root data structure in container DFHJS-DATA.
- The container named in component1-cont.
- Two containers named in the first two instances of component2-cont.
Optional structures and the required keyword
Data structures are defined by the JSON Schema "type" of "object". The schemas relate field names to individual types using the object provided by the "properties" keyword. The requirement for these fields to be part of the JSON data described by the JSON Schema is controlled by the array provided by the "required" keyword. This array lists all the field names that must be present in the JSON data. Optional fields are therefore represented by their absence from this array, or as the array is not allowed to be empty, the absence of the "required" keyword. In this case, all fields are optional.
Optional fields are treated as a variable array of 0 or 1 elements. This adds an additional field with the suffix "-num" appended to the element name. If the total length is more than 28 characters, the element name is truncated. At run time this will be non-zero to indicate the value was present in the JSON data and zero if it was not.
{
"type": "object",
"properties": {
"required-structure": {
"type":"string",
"maxLength": 8
},
"optional-structure": {
"type":"string",
"maxLength": 8
}
},
"required": [
"required-structure"
]
}
03 OutputData.
06 required-structure PIC X(8).
06 optional-structure-num PIC S9(9) COMP-5 SYNC.
06 optional-structure PIC X(8).