PL/I to JSON schema mapping

The DFHLS2JS utility program supports mappings between PL/I data structures and JSON schema definitions. Because the Enterprise PL/I compiler and older PL/I compilers differ, two language options are supported: PLI-ENTERPRISE and PLI-OTHER.

How PL/I names are converted to JSON

PL/I names are converted to JSON names according to the following rules:
  1. Characters that are not valid in JSON property names are replaced with ' x '.

    For example, monthly$total becomes monthlyxtotal.

  2. Duplicate names are made unique by the addition of one or more numeric digits.

    For example, two instances of year become year and year1.

How PL/I data types are mapped to JSON

DFHLS2JS maps PL/I data types to schema elements according to Table 1.

Restriction:
  • PL/I types that are not shown in Table 1 are not supported by DFHLS2JS.
  • Data items with the COMPLEX attribute are not supported.
  • Data items with the FLOAT attribute are supported at a mapping level of 1.2 or higher. Enterprise PL/I FLOAT IEEE is not supported.
  • VARYING and VARYINGZ pure DBCS strings are supported at a mapping level of 1.2 or higher.
  • Data items that are specified as DECIMAL( p , q ) are supported only when p ≥ q
  • Data items that are specified as BINARY( p , q ) are supported only when q = 0.
  • If the PRECISION attribute is specified for a data item, it is ignored.
  • PICTURE strings are not supported.
  • ORDINAL data items are treated as FIXED BINARY(7) data types.
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to NULL, character arrays are mapped to an string and are processed as null-terminated strings; this mapping does not apply for Enterprise PL/I.
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to BINARY, character arrays are mapped to string and are processed as binary data.
  • If the  MAPPING-LEVEL  parameter is set to 1.2 or higher and the  CHAR-VARYING  parameter is set to COLLAPSE, leading and trailing white space will be removed and multiple spaces are replaced with a single space.
  • DFHLS2JS does not fully implement the padding algorithms of PL/I; therefore, you must declare padding bytes explicitly in your data structure. DFHLS2JS issues a message if it detects that padding bytes are missing. Each top-level structure must start on a doubleword boundary and each byte in the structure must be mapped to the correct boundary.

    Example

    Consider this code fragment: 
    3 FIELD1 FIXED BINARY(7),
3 FIELD2 FIXED BINARY(31),
3 FIELD3 FIXED BINARY(63);

    In this example:

    • FIELD1 is 1 byte long and can be aligned on any boundary.
    • FIELD2 is 4 bytes long and must be aligned on a fullword boundary.
    • FIELD3 is 8 bytes long and must be aligned on a doubleword boundary.

    The Enterprise PL/I compiler aligns the fields in the following order:

    1. FIELD3 is aligned first because it has the strongest boundary requirements.
    2. FIELD2 is aligned at the fullword boundary immediately before FIELD3.
    3. FIELD1 is aligned at the byte boundary immediately before FIELD3.

    Finally, so that the entire structure is aligned at a fullword boundary, the compiler inserts three padding bytes immediately before FIELD1.

    Because DFHLS2JS does not insert equivalent padding bytes, you must declare them explicitly before the structure is processed by DFHLS2JS. For example: 
    3 PAD1 FIXED BINARY(7),
3 PAD2 FIXED BINARY(7),
3 PAD3 FIXED BINARY(7),
3 FIELD1 FIXED BINARY(7),
3 FIELD2 FIXED BINARY(31),
3 FIELD3 FIXED BINARY(63);

    Alternatively, you can change the structure to declare all the fields as unaligned and recompile the application that uses the structure. For more information about PL/I structural memory alignment requirements, see Enterprise PL/I for z/OS product information.

Table 1. Mapping reference for PL/I data types
PL/I data description JSON schema definition
FIXED BINARY (n） 
"type":"integer",
"minimum":- (n + 1),
"maximum":n
where  n  is the maximum value that can be represented by the primitive.
UNSIGNED FIXED BINARY(n）
Restriction: Enterprise PL/I only
 
"type":"integer",
"minimum":0,
"maximum":n
where n is the maximum value that can be represented by the primitive.
FIXED DECIMAL( n , m ) 
"type":"number",
"format":"decimal",
"multipleOf":x,
"maximum":y,
"minimum":-z

where:

x is the smallest unit available = 1 / 10 m.

y is the maximum value that can be represented by the combination of n and m.

z is the maximum value that can be represented by the combination of n and m.
FIXED DECIMAL(15)

Supported at mapping level 3.0 and higher when DATETIME=PACKED15 

"type":"string",
"format":"date-time"

The format of the time stamp is defined by RFC3339.

BIT(n）

where n is a multiple of 8. Other values are not supported. 

"type":"string"
"maxLength":m
where m = n /8
CHARACTER( n )

VARYING and VARYINGZ are also supported at mapping level 1.2 and higher.

Restriction: VARYINGZ is supported only by Enterprise PL/I 
"type":"string"
"maxLength":n
GRAPHIC( n )

VARYING and VARYINGZ are also supported at mapping level 1.2 and higher.

Restriction: VARYINGZ is supported only by Enterprise PL/I
At a mapping level of 1.0 and 1.1, where m = 2* n : 
"type":"string"
"maxLength":m

At a mapping level of 1.2 or higher:

"type":"string"
"maxLength":n
WIDECHAR( n )
Restriction: Enterprise PL/I only
 At a mapping level of 1.0 and 1.1, where m = 2* n : 
"type":"string"
"maxLength":m

At a mapping level of 1.2 or higher:

"type":"string"
"maxLength":n

At mapping level 4.0 and higher, CICS® populates the application data structure field with UTF-16 data. 

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:maxlength value="n"/>
    <xsd:whiteSpace value="preserve"/>
  </xsd:restriction>
</xsd:simpleType>
ORDINAL
Restriction: Enterprise PL/I only
 
"type":"integer",
"minimum":0,
"maximum":255
BINARY FLOAT( n )

where n <= 21

Supported at mapping level 1.2 and higher.

Note: The IBM® Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values may not convert exactly from one representation to the other. Some extremely large or small values might not be valid for float data types. Some values may lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of BINARY FLOAT data types with fixed precision alternatives. 
"type":"number",
"format":"float"
BINARY FLOAT( n )

where 21 < n <= 53

Values greater than 53 are not supported.

Supported at mapping level 1.2 and higher.

Note: The IBM Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values may not convert exactly from one representation to the other. Some extremely large or small values might not be valid for float data types. Some values may lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of BINARY FLOAT data types with fixed precision alternatives. 
"type":"number",
"format":"double"
DECIMAL FLOAT( n )

where n <= 6

Supported at mapping level 1.2 and higher.

Note: The IBM Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values may not convert exactly from one representation to the other. Some extremely large or small values might not be valid for float data types. Some values may lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of DECIMAL FLOAT data types with fixed precision alternatives. 
"type":"number",
"format":"float"
DECIMAL FLOAT( n )

where 6 < n <= 16

Values greater than 16 are not supported.

Supported at mapping level 1.2 and higher.

Note: The IBM Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values may not convert exactly from one representation to the other. Some extremely large or small values might not be valid for float data types. Some values may lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of DECIMAL FLOAT data types with fixed precision alternatives. 
"type":"number",
"format":"double"
name ( n ) data description For primitives: 
"type":"array"
"maxItems":n
"minItems":n
"items":{
  "type":"object",
  "properties":{name:{data description JSON}}
  "required":[name]
         }
For data declarations: 
"type":"array"
"maxItems":n
"minItems":n
"items":{data description JSON}

where data description JSON is the JSON schema representation of the PL/I data description.