CONV_DONNEES

Paragraphe d'utilisation

Tous

Syntaxe

CONV_DONNEES donneesAConvertir formatOrig  donneesConverties formatDest

Description

L'instruction CONV_DONNEES permet de convertir le format des données contenues dans le paramètre donneesAConvertir.

Le paramètre formatOrig définit le format d'origine des données. Il est obligatoire lorsque la donnée d'origine n'est pas une variable de type classe sinon il ne doit pas être indiqué.

Le paramètre formatDest définit le format dans lequel les données doivent être converties. Il est obligatoire lorsque la donnée de destination n'est pas une variable de type classe sinon il ne doit pas être indiqué.

Le paramètre donneesConverties reçoit en retour les données converties.

Le paramètre donneesAConvertir contient les données à convertir.

Lorsque *FICHIER_SOURCE est indiqué, donneesAConvertir doit contenir le nom du fichier à convertir.

Dans le cas contraire, il contient les données à convertir, soit dans une variable alpha, soit dans une variable image.

Le paramètre formatOrig définit le format d'origine des données.

Les valeurs possibles sont :

• • 'JSON'   => Format JSON
    
    
  • 'JSON(suiteOptionsJson)'
    SuiteOptionsJson => optionJson | optionJson, suiteOptionsJson

optionJson => *WITH_ROOT | *DIGIT_NAME | *FEATURES

1. L'option *WITH_ROOT est valable seulement lorsque l'on souhaite désérialiser la donnée Json en classe.
   Si elle est indiquée, la conversion s'attend à avoir l'attribut racine dans la donnée Json.
   Sinon une exception est levée.
2. L'option *DIGIT_NAME force l'ajout d'un préfixe _DIGIT_ devant les noms de balises commençant par un chiffre (pour éviter d'avoir un fichier invalide en XML).
3. *FEATURES : lorsque la donnée de destination est une classe, cette option permet de paramétrer la désérialisation JSON en se basant sur les possibilités offertes par la librairie Jackson pour le provider com.fasterxml.jackson.jaxrs.JacksonJaxbJsonProvider.
   La liste détaillée des paramètres de désérialisation acceptés (description et valeur par défaut) est disponible sur le site de la librairie Jackson.
   Cette option accepte un ou plusieurs paramètres de désérialisation Jackson, sous la forme de propriétés booléennes encapsulées dans un fragment JSON :  "*FEATURES:{"jacksonParameter1":true/false, "jacksonParameter":true/false...}"
   Le nommage des paramètres Jackson au niveau de l'option *FEATURES est directement aligné sur le nommage correspondant de la libraire Jackson, selon la norme suivante :
   • Le nom des paramètres est préfixé par "deser"
   • Auquel est concaténé le nom du paramètre Jackson correspondant, en excluant les caractères "_" 
   • Le tout suit une notation de style "camel case"
   • Exemple : le paramètre Jackson "UNWRAP_ROOT_VALUE" devient "deserUnwrapRootValue" au niveau de l'option *FEATURES
   • Ce qui donne au final la valeur suivante pour le paramètre formatOrig de l'ordre CONV_DONNEES : 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserUnwrapSingleValueArrays":false})'

A noter : Si l'option *WITH_ROOT et le paramètre Jackon "deserUnwrapRootValue" sont tous deux renseignés, c'est la valeur du paramètre Jackson qui est retenue pour configurer la désérialisation.

• • 'XML'   => Format XML
    
    
  • 'XML(suiteOptionsXml)'
    SuiteOptionsXml => optionXml | optionXml, suiteOptionsXml

optionXml =>

<suitePathsBalises> |

*ARRAY=<suitePathsBalises> |

*IGNORE_EMPTY_ARRAY |

*ALPHA=< suitePathsAlpha> |

*ALL

suitePathsBalises : lorsqu'il est précédé du mot clé *ARRAY ou lorsqu'il n'est précédé d'aucun mot clé, indique les arborescences (séparées par une virgule) des balises que l'on souhaite sérialiser en tableau JSON. Lorsqu'il est précédé du mot clé *ALPHA, il indique les arborescences des balises que l'on souhaite convertir systématiquement en valeur alphanumérique (même si la valeur correspond à une valeur numérique).

Par défaut, on tente de convertir chaque valeur d'abord en numérique puis en décimale et en booléen. Si aucune conversion n'est possible le type de la valeur est alphanumérique.

Chaque arborescence doit commencer par le caractère "/".

L'option *ARRAY s'applique uniquement pour les balises contenant un seul élément. Les balises contenant plusieurs éléments sont naturellement converties en tableau JSON.

(par exemple : "XML(/LES_PERSONNES/Personnes)" ).

L'option *IGNORE_EMPTY_ARRAY doit être utilisée avec *ARRAY et permet d'obtenir des tableaux JSON vides :
"node":[]
Sans cette option, une balise XML vide convertie avec l'option *ARRAY génère le nœud JSON "node":[""]

L'option *ALL force la conversion au format alphanumérique de toutes les valeurs de toutes les balises.

Le paramètre donneesAConvertir reçoit en retour les données dans leur nouveau format.

Lorsque *FICHIER_DEST est indiqué, les données sont stockées dans un fichier. Dans le cas contraire, elles sont stockées dans une variable de type alpha ou image.

Le paramètre formatDest définit le format de conversion.

Les valeurs possibles sont :

• • 'JSON' => Format JSON
    
    
  • 'JSON(suiteOptionsJson)
    SuiteOptionsJson => optionJson | optionJson, suiteOptionsJson
    optionJson =>
    < suiteNomsNoeuds > |  *DIGIT_NAME | *WITH_ROOT | *SER_INCLUSION | *FEATURES 
    
    1. suiteNomsNoeuds : format JSON où il est indiqué les noms des nœuds (séparés par une virgule) correspondant à une collection JSON d'éléments qu'on veut rendre anonyme en JSON.
       Pour indiquer le nœud racine, il est possible d'utiliser la valeur spéciale *ROOT  (par exemple : 'JSON(*ROOT , Personnes)' )
    2. L'option *DIGIT_NAME supprime l'éventuel préfixe _DIGIT_ devant les noms des balises XML pour définir le nom du nœud JSON (cas où le nom réel du nœud JSON doit commencer par un chiffre ce qui est invalide en XML).
    3. *WITH_ROOT : lorsque la donnée d'origine est une classe, ce mot-clé indique que l'on souhaite prendre en compte l'attribut racine lors de la sérialisation.
    4. *SER_INCLUSION : lorsque la donnée d'origine est une classe, cette option permet de définir la politique d'inclusion/exclusion des attributs nuls ou vides lors de la sérialisation JSON de la classe. Cette option accepte les valeurs suivantes, sous la forme  "*SER_INCLUSION:value" :
       
       • Always : valeur indiquant qu'un attribut doit toujours être inclus, indépendamment de sa valeur (valorisée, nulle ou vide).
         Il s'agit du comportement par défaut lorsque l'option *SER_INCLUSION n'est pas renseignée.
       • NonEmpty : valeur indiquant que seuls les attributs avec une valeur nulle, ou ce qui est considéré comme vide, ne doivent pas être inclus.
       • NonNull : valeur indiquant que seuls les attributs avec des valeurs non nulles doivent être inclus.
    5. *FEATURES : lorsque la donnée d'origine est une classe, cette option permet de paramétrer la sérialisation JSON en se basant sur les possibilités offertes par la librairie Jackson pour le provider com.fasterxml.jackson.jaxrs.JacksonJaxbJsonProvider.
       La liste détaillée des paramètres de sérialisation acceptés (description et valeur par défaut) est disponible sur le site de la librairie Jackson.
       Cette option accepte un ou plusieurs paramètres de sérialisation Jackson, sous la forme de propriétés booléennes encapsulées dans un fragment JSON :  "*FEATURES:{"jacksonParameter1":true/false, "jacksonParameter":true/false...}"
       Le nommage des paramètres Jackson au niveau de l'option *FEATURES est directement aligné sur le nommage correspondant de la libraire Jackson, selon la norme suivante :
       • Le nom des paramètres est préfixé par "ser"
       • Auquel est concaténé le nom du paramètre Jackson correspondant, en excluant les caractères "_" 
       • Le tout suit une notation de style "camel case"
       • Exemple : le paramètre Jackson "WRAP_ROOT_VALUE" devient "serWrapRootValue" au niveau de l'option *FEATURES
       • Ce qui donne au final la valeur suivante pour le paramètre formatDest de l'ordre CONV_DONNEES : 'JSON(*FEATURES:{"serWrapRootValue":true, "serIndentOutput":false})'
       A noter que si l'option *WITH_ROOT et que le paramètre Jackon "serUnwrapRootValue" sont tous deux renseignés, c'est la valeur du paramètre Jackson qui est retenue pour configurer la sérialisation.
       

• • 'XML'    => Format XML
    
    

Remarques : lorsque l'on souhaite convertir les données au format XML et que les données converties sont contenues dans un fichier, l'encodage est forcé en UTF-8.

Lorsque les données à convertir sont contenues dans une variable alphanumérique, elles doivent être dans la page de code de la plateforme courante.  

Lorsque les données converties sont contenues dans une variable alphanumérique, elles sont encodées dans la page de code de la plateforme courante.

Dans le cas d'une conversion de JSON vers XML, si le document JSON n'a pas de nœud racine alors le document XML aura un nœud racine de nom "Root".

Il est possible de tester le mot réservé *CODE_RETOUR après l'exécution de l'instruction.

Si l'opération s'est bien déroulée, *CODE_RETOUR renvoie *NORMAL.

Voici les différents résultats :

-1 : Paramètres invalides.

-2 : Erreur à la lecture du fichier contenant les données à convertir.

-3 : Erreur à l'écriture du fichier contenant les données converties.

-4 : Erreur à la lecture du champ image contenant les données à convertir.

-5 : Les formats de conversion spécifiés ne sont pas corrects.

-6 : Erreur lors de la sérialisation de la classe en donnée JSON.

-7 : Erreur lors de la désérialisation de la donnée JSON.

-8 : Erreur d'analyse d'une donnée JSON (parsing)

-9 : Problème de mapping entre une donnée/format d'origine et une donnée/format  de destination

1 : Erreur interne.

2 : Erreur lors de l'analyse des données XML.

3 : Erreur lors de l'analyse des données JSON.

4 : Erreur lors de la conversion de caractères UTF8 en EBCDIC ou UCS2 (AS400).

5 : Le nom d'un élément de la donnée JSON en entrée n'est pas valide.

Exemple 1 :

CONV_DONNEES *FICHIER_SOURCE('c:\doc\personnes.xml') 'XML'  *FICHIER_DEST('c:\doc\personnes.json') 'JSON'

Exemple 2 :

Alpha(250) DATA_ORIG

IMAGE DATA_DEST

DATA_ORIG = '{"LES_PERSONNES":{"Personnes":[{"Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"},{"Nom":"DOLA","Prenom":"Laura","DateNaissance":"1990-11-01"}]}}'

CONV_DONNEES DATA_ORIG 'JSON' DATA_DEST 'XML'

Rend DATA_DEST avec la valeur <?xml version="1.0" encoding="UTF-8" standalone="yes"?><LES_PERSONNES> <Personnes><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance></Personnes> <Personnes><Nom>DOLA</Nom><Prenom>Laura</Prenom><DateNaissance>1990-11-01</DateNaissance></Personnes></LES_PERSONNES>

Exemple 3 :

DATA_ORIG =' <?xml version="1.0" encoding="UTF-8" ?><LES_PERSONNES> <Personnes><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance> </Personnes> <Personnes><Nom>DOLA</Nom><Prenom>Laura</Prenom><DateNaissance>1990-11-01</DateNaissance></Personnes></LES_PERSONNES>

CONV_DONNEES DATA_ORIG 'XML'  DATA_DEST 'JSON'

Rend DATA_DEST avec la valeur '{"LES_PERSONNES":{"Personnes":[{"Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"},{"Nom":"DOLA","Prenom":"Laura","DateNaissance":"1990-11-01"}]}}'

Exemple 4 :

DATA_ORIG =' <?xml version="1.0" encoding="UTF-8" ?><LES_PERSONNES> <Personnes><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance> </Personnes> <Personnes><Nom>DOLA</Nom><Prenom>Laura</Prenom><DateNaissance>1990-11-01</DateNaissance></Personnes></LES_PERSONNES>

CONV_DONNEES DATA_ORIG 'XML'  DATA_DEST 'JSON(*ROOT, Personnes)'

Rend DATA_DEST avec la valeur '[{"Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"}, {"Nom":"DOLA","Prenom":"Laura","DateNaissance":"1990-11-01"}]

Exemple 5 :

DATA_ORIG =' <?xml version="1.0" encoding="UTF-8" ?><LES_PERSONNES> <Personnes><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance> </Personnes></LES_PERSONNES>' 

CONV_DONNEES DATA_ORIG 'XML (*ARRAY=/LES_PERSONNES/Personnes) '  DATA_DEST 'JSON' 

Rend DATA_DEST avec la valeur ' {"LES_PERSONNES":{"Personnes":[{"Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"}]}}' 

Exemple 6 :

DATA_ORIG ='<?xml version="1.0" encoding="UTF-8" ?><LES_PERSONNES> <Personnes></Personnes></LES_PERSONNES>' 

CONV_DONNEES DATA_ORIG 'XML (*IGNORE_EMPTY_ARRAY, *ARRAY=/LES_PERSONNES/Personnes) '  DATA_DEST 'JSON' 

Rend DATA_DEST avec la valeur ' {"LES_PERSONNES":{"Personnes":[]}} '

Exemple 7 :

DATA_ORIG ='<?xml version="1.0" encoding="UTF-8" ?><LES_SALARIES> <Salaries><Matricule>52413</Matricule><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance></Salaries></LES_SALARIES> ' 

CONV_DONNEES DATA_ORIG 'XML(*ALPHA=/LES_SALARIES/Salaries/Matricule) '  DATA_DEST 'JSON' 

Rend DATA_DEST avec la valeur '{"LES_SALARIES":{"Salaries":{"Matricule":"52413","Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"}}}' 

Exemple 8 :

DATA_ORIG ='<?xml version="1.0" encoding="UTF-8" ?><LES_SALARIES> <Salaries><Matricule>52413</Matricule><Nom>RONDO</Nom><Prenom>Paul</Prenom><DateNaissance>1980-10-30</DateNaissance></Salaries></LES_SALARIES> ' 

CONV_DONNEES DATA_ORIG 'XML(*ARRAY=/LES_SALARIES/Salaries, *ALPHA=/LES_SALARIES/Salaries/Matricule) '  DATA_DEST 'JSON' 

Rend DATA_DEST avec la valeur ' {"LES_SALARIES":{"Salaries":[{"Matricule":"52413","Nom":"RONDO","Prenom":"Paul","DateNaissance":"1980-10-30"}]}} ' 

Exemple 9 :

DATA_ORIG = '{"n1" : "valn1" , "2x" : "val2x"}'

CONV_DONNEES DATA_ORIG 'JSON(*DIGIT_NAME)' DATA_DEST 'XML'

Rend DATA_DEST avec la valeur <?xml version="1.0" encoding="UTF-8" standalone="yes"?><Root><n1>valn1</n1><_DIGIT_2x>val2x</_DIGIT_2x>/Root>

Exemple 10 : option *SER_INCLUSION (cas de la sérialisation d'une classe au format JSON)

REF_CLASSE (PERSONNE) oPersonne

ALPHA (500)  DATA_DEST 

* Remarque : la classe  PERSONNE contient 2 attributs ALPHA ("Nom" et "Prenom") et un attribut nommé "Pays" qui est lui même une référence sur une classe

oPersonne = new PERSONNE()

oPersonne.setNom('Dupont')

• • Exemple 10.a : 

CONV_DONNEES oPersonne DATA_DEST  'JSON(*SER_INCLUSION:Always)'

Rend DATA_DEST avec la valeur : {"Nom":"Dupont", "Prenom": "", "Pays":null}

• • Exemple 10.b : 

CONV_DONNEES oPersonne DATA_DEST  'JSON(*SER_INCLUSION:NonEmpty)'

Rend DATA_DEST avec la valeur :  {"Nom":"Dupont"}

• • Exemple 10.c : 

CONV_DONNEES oPersonne DATA_DEST  'JSON(*SER_INCLUSION:NonNull)'

Rend DATA_DEST avec la valeur :  {"Nom":"Dupont", "Prenom": "" }

Exemple 11 : option *FEATURES et configuration de la désérialisation

REF_CLASSE (PAYS) oPays

ALPHA (500)  DATA_ORIG 

NUM_E (9,0) RET

* Remarque : la classe  PAYS contient 3 attributs ALPHA : "Langue", "Devise",  "Capitale" et un NUM_BIN_8 : "Population"

• • Exemple 11.a : 

DATA_ORIG = '{"PAYS":{"Langue": "Francais", "Devise":"euro", "Capitale":"Paris", "Population":68014001, "Superficie":67205}}'

CONV_DONNEES DATA_ORIG 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserFailOnUnknownProperties":false}' oPays

En retour l'instance de classe est correctement valorisée, malgré que l'attribut "Superficie" ne soit pas membre de la classe.

• • Exemple 11.b : 

DATA_ORIG = '{"PAYS":{"Langue": "Francais", "Devise":"euro", "Capitale":"Paris", "Population":68014001, "Superficie":67205}}'

CONV_DONNEES DATA_ORIG 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserFailOnUnknownProperties":true}' oPays

RET= *CODE_RETOUR

En retour RET vaut -9 et l'instance de classe n'est pas valorisée, car l'attribut "Superficie" n'est pas membre de la classe.

Exemple 12 : option *FEATURES et configuration de la sérialisation

REF_CLASSE (PAYS) oPays

ALPHA (500)  DATA_DEST 

* Remarque : la classe  PAYS contient 3 attributs ALPHA : "Langue", "Devise",  "Capitale" et un NUM_BIN_8 : "Population"

oPays= new PAYS()

oPays.setLangue('Francais')

oPays.setDevise('euro')

oPays.setCapitale('Paris')

oPays.setPopulation(68014001)

• • Exemple 12.a :

CONV_DONNEES oPays DATA_DEST  'JSON(*FEATURES:{"serWrapRootValue":false})'

Rend DATA_DEST avec la valeur :  {"Langue": "Francais", "Devise":"euro", "Capitale":"Paris", "Population":68014001}

• • Exemple 12.b : 

CONV_DONNEES oPays DATA_DEST  'JSON(*FEATURES:{"serWrapRootValue":true})'

Rend DATA_DEST avec la valeur : {"PAYS":{"Langue": "Francais", "Devise":"euro", "Capitale":"Paris", "Population":68014001}}

↑ Haut de page