CONV_DATA

Section for use

All

Syntax

CONV_DATA dataToConvert origFormat convertedData destFormat

Description

The CONV_DATA instruction is used to convert the format of data contained in the dataToConvert parameter.

The origFormat parameter defines the original format of the data. It is mandatory when the original data is not a class-type variable, otherwise it must not be specified.

The destFormat parameter defines the format into which the data must be converted. It is mandatory when the destination data is not a class-type variable, otherwise it must not be indicated.

The convertedData parameter receives the converted data in return.

The dataToConvert parameter contains the data to convert.

When *SOURCE_FILE is indicated, dataToConvert must contain the name of the file to convert.

Otherwise, it contains the data to convert, either in an alpha variable or in an image variable.

The origFormat parameter defines the original format of the data.

The possible values are:

• 'JSON'   => JSON format
  
  

• 'JSON(JsonOptionsSeries)'
  JsonOptionsSeries => Jsonoption | Jsonoption, JsonOptionsSeries

Jsonoption => *WITH_ROOT | *DIGIT_NAME | *FEATURES

1. The *WITH_ROOT option is valid only when you wish to deserialize the data Json in class.
   If this option is indicated, the conversion expects to have the root attribute in the Json data.
   Otherwise an exception is thrown.
2. The *DIGIT_NAME option forces the addition of a _DIGIT_ prefix in front of tag names starting with a number (to avoid having an invalid file in XML).
3. *FEATURES: when the destination data is a class, this option is used to configure JSON deserialization based on the possibilities offered by the Jackson library for provider com.fasterxml.jackson.jaxrs.JacksonJaxbJsonProvider.
   The detailed list of accepted deserialization parameters (default description and value) is available on the Jackson library website.
   This option accepts one or more Jackson deserialization parameters in the form of Boolean properties encapsulated in a JSON fragment:  "*FEATURES:{"jacksonParameter1":true/false, "jacksonParameter":true/false...}"
   The naming of Jackson parameters in the *FEATURES option is directly in line with the corresponding Jackson library naming, according to the following standard:

• • • The parameter name is prefixed with "deser"
    • To which the name of the corresponding Jackson parameter is concatenated, excluding the "_" characters 
    • It all uses "camel case" notation
    • E.g. the "UNWRAP_ROOT_VALUE" Jackson parameter becomes "deserUnwrapRootValue" in the *FEATURES option
    • This gives the following value for the origFormat parameter of the CONV_DATA instruction: 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserUnwrapSingleValueArrays":false})'

NB: If the *WITH_ROOT option and the "deserUnwrapRootValue" Jackson parameter are both entered, it is the Jackson parameter that is used to configure deserialization.

• 'XML'   => XML format
  
  
• 'XML(XmlOptionsSeries)'
  XmlOptionsSeries => XmlOption  | XmlOption, XmlOptionsSeries

XmlOption =>

<TagPathsSeries> |

*ARRAY=<TagPathsSeries> |

*IGNORE_EMPTY_ARRAY | 

*ALPHA=<TagPathsSeries> | 

*ALL

tagPathsSeries: when preceded by the keyword *ARRAY or not preceded by a keyword, indicates the tree views (separated by a comma) of the tags we want to serialize in a JSON array. When preceded by the keyword *ALPHA, it indicates the tree views of the tags we want to systematically convert into an alphanumeric value (even if the value corresponds to a numeric value).

By default, we try to convert each value into a numeric value first then into a decimal and Boolean value. If no conversion is possible, the value type is alphanumeric.

Each tree view must start with the "/" character.

The *ARRAY option only applies for tags containing a single element. Tags containing several elements are naturally converted into a JSON array.

(for example: "XML(/PEOPLE/People)").

The *IGNORE_EMPTY_ARRAY option must be used with *ARRAY and can be used to obtain empty JSON arrays:
"node":[]
Without this option, an empty XML tag converted with the *ARRAY option generates the JSON node "node":[""]

The *ALL option forces all the values from all the tags to be converted to alphanumeric format.

The dataToConvert parameter receives the data in its new format in return.

When *TARGET_FILE is indicated, the data is stored in a file. Otherwise, it is stored in an alpha- or image-type variable.

The destFormat parameter defines the conversion format.

The possible values are:

• • 'JSON' => JSON format
    
    
  • JSON(JsonOptionsSeries)'
    JsonOptionsSeries => Jsonoption | Jsonoption, JsonOptionsSeries
    Jsonoption =>
    < nodeNameSeq > | *DIGIT_NAME | *WITH_ROOT | *SER_INCLUSION | *FEATURES
    1. nodeNameSeq: Format where the node names are specified (separated by comma). These names correspond to a JSON collection of elements which the user wants to make anonymous in JSON.
       To specify the root node, it is possible to use the *ROOT special value (for example: 'JSON(*ROOT , People)' )
    2. The *DIGIT_NAME option removes the possible _DIGIT_ prefix in front of XML tag names to define the name of the JSON node (where the actual name of the JSON node must start with a number which is invalid in XML).
    3. *WITH_ROOT: When the original data is a class, this keyword indicates that the root attribute shall be taken into account during the serialization.
    4. *SER_INCLUSION: when the original data is a class, this option is used to define the inclusion/exclusion policy of null or empty attributes during the JSON serialization of the class. This option accepts the following values, in "*SER_INCLUSION:value" form:
       
       • Always: value indicating that an attribute must always be included, regardless of its value (with a value, null or empty).
         This is the default behavior when the *SER_INCLUSION option is not entered.
       • NonEmpty: value indicating that only attributes with a null value, or which are considered to be empty, must not be included.
       • NonNull: value indicating that only attributes with non-null values must be included.
    5. *FEATURES: when the original data is a class, this option is used to configure JSON serialization based on the possibilities offered by the Jackson library for provider com.fasterxml.jackson.jaxrs.JacksonJaxbJsonProvider.
       The detailed list of accepted serialization parameters (default description and value) is available on the Jackson library website.
       This option accepts one or more Jackson serialization parameters in the form of Boolean properties encapsulated in a JSON fragment:  "*FEATURES:{"jacksonParameter1":true/false, "jacksonParameter":true/false...}"
       The naming of Jackson parameters in the *FEATURES option is directly in line with the corresponding Jackson library naming, according to the following standard:
       • The parameter name is prefixed with "ser"
       • To which the name of the corresponding Jackson parameter is concatenated, excluding the "_" characters 
       • It all uses "camel case" notation
       • E.g. the "WRAP_ROOT_VALUE" Jackson parameter becomes "serWrapRootValue" in the *FEATURES option
       • This gives the following value for the destFormat parameter of the CONV_DATA instruction: 'JSON(*FEATURES:{"serWrapRootValue":true, "serIndentOutput":false})'
       Note that if the *WITH_ROOT option and the "serUnwrapRootValue" Jackson parameter are both entered, it is the Jackson parameter that is used to configure serialization.

• • 'XML'    => XML format

NB: when the user wants to convert data into XML format and the converted data is contained in a file, encoding is forced to UTF-8.

When the data to convert is contained in an alphanumeric variable, it must be in the current platform's code page.  

When the converted data is contained in an alphanumeric variable, it is encoded in the current platform's code page.

In the case of a conversion from JSON to XML, if there is no root node in the JSON document, then there will be a root node named "Root" in the XML document

Reserved word *RETURN_CODE can be tested after executing the instruction.

If the operation has been carried out successfully, *RETURN_CODE returns *NORMAL.

The table below shows the various possible results:

-1: Invalid parameters.

-2: Error when reading the file containing the data to convert.

-3: Error when writing the file containing the converted data.

-4: Error when reading the image field containing the data to convert.

-5: The specified conversion formats are not correct.

-6: Error during class serialization into JSON data.

-7: Error during deserialization of JSON data.

-8: JSON data analysis error (parsing)

-9: Mapping problem between original data/format and destination data/format

1: Internal error.

2: Error during the XML data analysis.

3: Error during the JSON data analysis.

4: Error when converting UTF8 characters into EBCDIC or UCS2 (AS400).

5: The name of an element of the input JSON data is invalid.

Example 1

CONV_DATA *SOURCE_FILE('c:\doc\people.xml') 'XML'  *TARGET_FILE('c:\doc\people.json') 'JSON'

Example 2

Alpha(250) ORIG_DATA

IMAGE DEST_DATA

ORIG_DATA = '{"PEOPLE":{"People":[{"Surname":"RONDO","FirstName":"Paul","DOB":"1980-10-30"},{"Surname":"DOLA","FirstName":"Laura","DOB":"1990-11-01"}]}}'

CONV_DATA ORIG_DATA DEST_DATA 'XML'

Returns DEST_DATA with the value <?xml version="1.0" encoding="UTF-8" standalone="yes"?><PEOPLE> <People><Name>RONDO</Name><FirstName>Paul</FirstName><>1980-10-30</DOB></People> <People><Name>DOLA</Name><FirstName>Laura</FirstName><DOB>1990-11-01</DOB></People></PEOPLE>

Example 3

ORIG_DATA =' <?xml version="1.0" encoding="UTF-8" ?><PEOPLE> <People><Name>RONDO</Name><FirstName>Paul</FirstName><DOB>1980-10-30</DOB> </People> <People><Name>DOLA</Name><FirstName>Laura</FirstName><DOB>1990-11-01</DOB></People></PEOPLE>

CONV_DATA ORIG_DATA 'XML'  DEST_DATA 'JSON'

Returns DEST_DATA with the value '{"PEOPLE":{"People":[{"Name":"RONDO","FirstName":"Paul","DOB":"1980-10-30"},{"Name":"DOLA","FirstName":"Laura","DOB":"1990-11-01"}]}}'

Example 4

ORIG_DATA =' <?xml version="1.0" encoding="UTF-8" ?><PEOPLE> <People><Name>RONDO</Name><FirstName>Paul</FirstName><DOB>1980-10-30</DOB> </People> <People><Name>DOLA</Name><FirstName>Laura</FirstName><DOB>1990-11-01</DOB></People></PEOPLE>

CONV_DATA ORIG_DATA 'XML'  DEST_DATA 'JSON(*ROOT, People)'

Returns DEST_DATA with the value '[{"Name":"RONDO","FirstName":"Paul","DOB":"1980-10-30"}, {"Name":"DOLA","FirstName":"Laura","DOB":"1990-11-01"}]

Example 5

ORIG_DATA =' <?xml version="1.0" encoding="UTF-8" ?><PEOPLE> <People><Name>RONDO</Name><FirstName>Paul</FirstName><DOB>1980-10-30</DOB> </People></PEOPLE>

CONV_DATA ORIG_DATA 'XML (*ARRAY=/PEOPLE/People) '  DEST_DATA 'JSON'

Returns DEST_DATA with the value ' {"PEOPLE":{"People":[{"Name":"RONDO","FirstName":"Paul","DOB":"1980-10-30"}]}}'

Example 6

ORIG_DATA ='<?xml version="1.0" encoding="UTF-8" ?><PEOPLE> <People></Personnes></PEOPLE>' 

CONV_DATA ORIG_DATA 'XML (*IGNORE_EMPTY_ARRAY, *ARRAY=/PEOPLE/People) '  DEST_DATA 'JSON' 

Returns DEST_DATA with the value ' {"PEOPLE":{"People":[]}} '

Example 7

ORIG_DATA ='<?xml version="1.0" encoding="UTF-8" ?><EMPLOYEES> <Employees><ID no.>52413</ID no.><Name>RONDO</Name><FirstName>Paul</FirstName><DOB>1980-10-30</DOB></Employees></EMPLOYEES> ' 

CONV_DATA ORIG_DATA 'XML(*ALPHA=/EMPLOYEES/Employees/ID no.) '  DEST_DATA 'JSON' 

Returns DEST_DATA with the value '{"EMPLOYEES":{"Employees":{"ID no.":"52413","Name":"RONDO","FirstName":"Paul","DOB":"1980-10-30"}}}' 

Example 8

ORIG_DATA ='<?xml version="1.0" encoding="UTF-8" ?><EMPLOYEES> <Employees><ID no.>52413</ID no.><Name>RONDO</Name><FirstName>Paul</FirstName><DOB>1980-10-30</DOB></Salaries></EMPLOYEES> ' 

CONV_DATA ORIG_DATA 'XML(*ARRAY=/EMPLOYEES/Employees, *ALPHA=/EMPLOYEES/Employees/ID no.) '  DEST_DATA 'JSON' 

Returns DEST_DATA with the value ' {"EMPLOYEES":{"Employees":[{"ID no.":"52413","Name":"RONDO","FirstName":"Paul","DOB":"1980-10-30"}]}} ' 

Example 9

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

CONV_DATA ORIG_DATA 'JSON(*DIGIT_NAME)' DATA_DEST 'XML'

Returns DEST_DATA with the value <?xml version="1.0" encoding="UTF-8" standalone="yes"?><Root><n1>valn1</n1><_DIGIT_2x>val2x</_DIGIT_2x>/Root>

Example 10: *SER_INCLUSION option (class serialization in JSON format)

REF_CLASS (PERSON) oPerson

ALPHA (500)  DEST_DATA 

* Note: the PERSON class contains 2 ALPHA attributes ("Last name" and "First name") and an attribute called "Country" which is itself a reference to a class

oPerson = new PERSON()

oPerson.setName('Smith')

• • Example 10.a: 

CONV_DATA oPerson DEST_DATA  'JSON(*SER_INCLUSION:Always)'

Returns DEST_DATA with the following value: {"Last name":"Dupont", "First name": "", "Country":null}

• • Example 10.b: 

CONV_DATA oPerson DEST_DATA  'JSON(*SER_INCLUSION:NonEmpty)'

Returns DEST_DATA with the following value:  {"Name":"Smith"}

• • Example 10.c: 

CONV_DATA oPerson DEST_DATA  'JSON(*SER_INCLUSION:NonNull)'

Returns DEST_DATA with the following value:  {"Nom":"Smith", "Adam": "" }

Example 11: *FEATURES option and deserialization configuration

CLASS_REF (COUNTRY) oCountry

ALPHA (500)  ORIG_DATA 

NUM_E (9,0) RET

* Note: the COUNTRY class contains 3 ALPHA attributes: "Language", "Currency",  "Capital" and a NUM_BIN_8: "Population"

• • Example 11.a: 

ORIG_DATA = '{"COUNTRY":{"Language": "French", "Currency":"euro", "Capital":"Paris", "Population":68014001, "Area":67205}}'

CONV_DATA ORIG_DATA 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserFailOnUnknownProperties":false}' oCountry

As return data, the class instance has the correct value despite the fact that the "Area" attribute is not a member of the class.

• • Example 11.b: 

ORIG_DATA = '{"COUNTRY":{"Language": "French", "Currency":"euro", "Capital":"Paris", "Population":68014001, "Area":67205}}'

CONV_DATA ORIG_DATA 'JSON(*FEATURES:{"deserUnwrapRootValue":true, "deserFailOnUnknownProperties":true}' oCountry

RET= *RETURN_CODE

As return data, RET is -9 and the class instance has no value as the "Area" attribute is not a member of the class.

Example 12: *FEATURES option and serialization configuration

REF_CLASS (COUNTRY) oCountry

ALPHA (500)  DEST_DATA 

* Note: the COUNTRY class contains 3 ALPHA attributes: "Language", "Currency",  "Capital" and a NUM_BIN_8: "Population"

oCountry = new COUNTRY()

oCountry.setLanguage('English')

oCountry.setCurrency('pound')

oCountry.setCapital('London')

oCountry.setPopulation(55619430)

• • Exemple 12.a:

CONV_DATA oCountry DEST_DATA  'JSON(*FEATURES:{"serWrapRootValue":false})'

Returns DEST_DATA with the following value:  {"Language": "English", "Currency":"pound", "Capital":"London", "Population":55619430}

• • Example 12.b: 

CONV_DATA oCountry DEST_DATA  'JSON(*FEATURES:{"serWrapRootValue":true})'

Returns DEST_DATA with the following value: {"COUNTRY":{"Language": "English", "Currency":"pound", "Capital":"London", "Population":55619430}

↑ Top of page