Array di variabili di elementi in DFHJS2LS

JSON può contenere array di numeri variabili di elementi. In generale, gli schemi JSON che contengono numeri variabili di elementi non si associano in modo efficiente in una singola struttura di dati del linguaggio di alto livello. CICS® utilizza le associazioni basate sul contenitore o le associazioni in linea per gestire numeri variabili di elementi nei dati JSON.

Un array con un numero variabile di elementi è rappresentato nello schema JSON utilizzando le parole chiave minItems e maxItems nello schema con valore "type" di "array" :

La parola chiave minItems specifica il numero minimo di volte in cui l'elemento può verificarsi. Può avere un valore 0 o qualsiasi numero intero positivo. Il valore predefinito è 0.
La parola chiave maxItems specifica il numero massimo di volte in cui l'elemento può verificarsi. Può avere un valore di qualsiasi numero intero positivo maggiore o uguale al valore della parola chiave minItems .
Se manca la parola chiave maxItems , significa che l'array non è limitato.

Un campo facoltativo può essere indicato da un array di variabili di "maxItems":1 . Ad esempio, una stringa di 8 byte facoltativa denominata "component" :

"properties":{
"component": {
"type":"array",
"maxItems":1,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]

Lo stesso effetto può essere prodotto non includendo il nome campo nel valore della parola chiave "required" :

"properties":{
"component": {
"type": "string",
"maxLength": 8
}
}

In generale, gli schemi JSON che contengono numeri variabili di elementi non si associano in modo efficiente in una singola struttura di dati di linguaggio di alto livello. Per gestire questi casi, CICS utilizza una serie di strutture dati connesse che vengono passate al programma applicativo in una serie di contenitori. Queste strutture vengono utilizzate come input e output dall'applicazione:

Quando CICS trasforma i dati JSON in dati di applicazione, popola queste strutture con i dati di applicazione e l'applicazione li legge.
Quando CICS trasforma i dati dell'applicazione in dati JSON, legge i dati dell'applicazione nelle strutture che sono state popolate dall'applicazione.

I seguenti esempi illustrano il formato di queste strutture dati. Questi esempi utilizzano una schiera di campi semplici a 8 byte. Tuttavia, il modello supporta array di tipi di dati complessi e array di tipi di dati che contengono altri array.

Esempio 1. Numero fisso di elementi

Questo esempio illustra un elemento che si verifica esattamente tre volte:

"properties":{
"component": {
"type": "array",
"maxItems": 3,
"minItems": 3,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]

In questo esempio, il numero di volte in cui l'elemento si verifica è noto in anticipo, quindi può essere rappresentato come un array a lunghezza fissa in una dichiarazione COBOL semplice o l'equivalente in altri linguaggi.

05 component PIC X(8) OCCURS 3 TIMES

Esempio 2. Numero variabile di elementi al livello di mappatura 2 e inferiore

Questo esempio illustra un elemento obbligatorio che può essere presente da una a cinque volte:

"properties":{
"component": {
"type": "array",
"maxItems": 5,
"minItems": 1,
"items": {
"type": "string",
"maxLength": 8
}
}
},
"required": ["component"]

La struttura dati principale contiene una dichiarazione di due campi. Quando CICS trasforma i dati JSON in dati binari, il primo campo component-num contiene il numero di volte in cui l'elemento viene visualizzato nei dati JSON e il secondo campo, component-cont , contiene il nome di un contenitore:

05 component-num PIC S9(9) COMP-5
05 component-cont PIC X(16)

Una seconda struttura di dati contiene la dichiarazione dell'elemento stesso:

01 DFHJS-component
02 component PIC X(8)

È necessario esaminare il valore di component-num , che conterrà un valore compreso tra 1 e 5, per individuare quante volte si verifica l'elemento. Il contenuto dell'elemento si trova nel contenitore denominato in component-cont ; il contenitore contiene un array di elementi, dove ogni elemento è associato dalla struttura dati DFHJS-component .

Se minItems="0" , o è mancante, e maxItems="1" , l'elemento è facoltativo. Per elaborare la struttura dati nel programma di applicazione, è necessario esaminare il valore component-num :

Se è zero, il messaggio non ha un elemento componente e il contenuto di component-cont non è definito.
Se è uno, l'elemento del componente si trova nel contenitore denominato in component-cont.

Il contenuto del contenitore viene associato dalla struttura dati DFHJS-component .

Nota: se i dati JSON sono costituiti da un singolo elemento ricorrente, DFHJS2LS genera due strutture del linguaggio. La struttura del linguaggio principale contiene il numero di elementi nell'array e il nome di un container che contiene l'array di elementi. La seconda struttura del linguaggio mappa una singola istanza dell'elemento ricorrente.

Esempio 3. Numero variabile di elementi al livello di associazione 2.1 e superiore

Al livello di associazione 2.1 e superiore, è possibile utilizzare il parametro INLINE-MAXOCCURS-LIMIT negli assistenti CICS . Il parametro INLINE-MAXOCCURS-LIMIT specifica il modo in cui vengono gestiti i numeri variabili di elementi. Le opzioni di associazione per numeri variabili di elementi sono associazioni basate sul contenitore, descritte nell' Esempio 2. Numero variabile di elementi al livello di associazione 2 e inferiore a o associazione in linea. Il valore di questo parametro può essere un numero intero positivo compreso tra 0 e 32767:

Il valore predefinito di INLINE-MAXOCCURS-LIMIT è 1 , che garantisce che gli elementi facoltativi siano mappati in linea.
Un valore di 0 per il parametro INLINE-MAXOCCURS-LIMIT impedisce l'associazione in linea.
Se maxItems è minore o uguale al valore di INLINE-MAXOCCURS-LIMIT , viene utilizzata l'associazione in linea.
Se maxItems è maggiore del valore di INLINE-MAXOCCURS-LIMIT , viene utilizzata l'associazione basata su contenitore.

L'associazione di numeri variabili di elementi in linea determina la generazione sia di un array, come accade con l'esempio di ricorrenza fissa precedente, sia di un contatore. Il campo component-num indica quante istanze dell'elemento sono presenti e sono indicate dall'array. Per l'esempio mostrato in Esempio 2. Variando il numero di elementi al livello di associazione 2 e al di sotto di , quando INLINE-MAXOCCURS-LIMIT è inferiore o uguale a 5, la struttura dati generata è simile alla seguente:

05 component-num PIC S9(9) COMP-5 SYNC.
05 component OCCURS 5 PIC X(8).

Il primo campo, component-num , è identico all'output per l'esempio di mapping basato su contenitore nella sezione precedente. Il secondo campo contiene una schiera di lunghezza 5 abbastanza grande da contenere il numero massimo di elementi che possono essere generati.

L'associazione in linea differisce dall'associazione basata su contenitore, che memorizza il numero di ricorrenze dell'elemento e il nome del contenitore in cui vengono inseriti i dati, poiché memorizza tutti i dati nel contenitore corrente. La memorizzazione dei dati nel contenitore corrente generalmente migliorerà le prestazioni e renderà preferibile l'associazione in linea.

Esempio 4. Array di variabili nidificati

Gli schemi JSON complessi possono contenere elementi ricorrenti variabili, che a loro volta contengono elementi ricorrenti variabili. In questo caso, la struttura descritta si estende oltre i due livelli descritti negli esempi.

In questo esempio viene illustrato un elemento facoltativo denominato "component2" nidificato in un elemento obbligatorio denominato "component1" , in cui l'elemento obbligatorio può essere presente da una a cinque volte:

"properties":{
"component1": {
"type": "array",
"maxItems": 5,
"minItems": 1,
"items": {
"type": "object",
"properties":{
"component2":{
"type": "string",
"maxLength": 8
}
},
"required": ["component2"]
}
},
"required": ["component1"]

La struttura dei dati di livello superiore è esattamente la stessa degli esempi precedenti:

05 component1-num PIC S9(9) COMP-5
05 component1-cont PIC X(16)

Tuttavia, la seconda struttura dati contiene questi elementi:

01 DFHJS-component1
02 component2-num PIC S9(9) COMP-5
02 component2-cont PIC X(16)

Una struttura di terzo livello contiene i seguenti elementi:

01 DFHJS-component2
02 component2 PIC X(8)

Il numero di ricorrenze dell'elemento più esterno "component1" è in component1-num.

Il contenitore denominato in component1-cont contiene un array con quel numero di istanze della seconda struttura dati DFHJS-component1.

Ogni istanza di component2-cont denomina un contenitore differente, ognuno dei quali contiene la struttura dati associata dalla struttura di terzo livello DFHJS-component2.

Per illustrare questa struttura, considerare il frammenti di dati JSON che corrisponde all'esempio:

{"component1":
[
{
"component2": "string1"
},
{
"component2": "string2"
},
]
}

"component1" si verifica tre volte. I primi due contengono un'istanza di "component2" ; la terza istanza non lo fa.

Nella struttura dati di primo livello, component1-num contiene un valore di 3. Il contenitore denominato in component1-cont ha tre istanze di DFHJS-component1 :

Nel primo, component2-num ha il valore 1 e il contenitore denominato in component2-cont contiene string1.
Nel secondo, component2-num ha un valore di 1 e il contenitore denominato in component2-cont contiene string2.
Nel terzo, component2-num ha un valore 0 e il contenuto di component2-cont non è definito.

In questo caso, la struttura dati completa è rappresentata da quattro contenitori in tutti:

La struttura dei dati root nel contenitore DFHJS-DATA.
Il contenitore denominato in component1-cont.
Due contenitori denominati nelle prime due istanze di component2-cont.

Strutture facoltative e parola chiave `required`

Le strutture dati sono definite dallo schema JSON "type" di "object". Gli schemi correlano i nomi dei campi a singoli tipi utilizzando l'oggetto fornito dalla parola chiave "properties" . Il requisito che questi campi facciano parte dei dati JSON descritti dallo schema JSON è controllato dall'array fornito dalla parola chiave "required" . Questo array elenca tutti i nomi campo che devono essere presenti nei dati JSON. I campi facoltativi sono quindi rappresentati dalla loro assenza da questo array o, poiché l'array non può essere vuoto, dall'assenza della parola chiave "required" . In questo caso, tutti i campi sono facoltativi.

I campi facoltativi vengono trattati come un array di variabili di 0 o 1 elementi. Questo aggiunge un campo aggiuntivo con il suffisso "-num" accodato al nome elemento. Se la lunghezza totale è superiore a 28 caratteri, il nome dell'elemento viene troncato. In fase di runtime, questo valore sarà diverso da zero per indicare che il valore era presente nei dati JSON e zero in caso contrario.

Questo esempio mostra due campi, uno obbligatorio denominato "required-structure" e l'altro facoltativo denominato "optional-structure" :

{
"type": "object",
"properties": {
"required-structure": {
"type":"string",
"maxLength": 8
},
"optional-structure": {
"type":"string",
"maxLength": 8
}
},
"required": [
"required-structure"
]
}

La struttura COBOL generata mostra entrambi i campi, ma il secondo è preceduto da "optional-structure-num" , che è un numero intero degli elementi, con 0 che rappresenta nessuno e 1 che è presente. Il valore è impostato per indicare se "optional-structure" contiene dati validi o meno.

03 OutputData.
06 required-structure PIC X(8).
06 optional-structure-num PIC S9(9) COMP-5 SYNC.
06 optional-structure PIC X(8).