A mapping is the set of rules used to determine how information
is converted between language structures and the Web service description (WSDL)
document.
When you run the Web services assistant jobs DFHWS2LS and DFHLS2WS,
you can use the MAPPING-LEVEL parameter to set a level
of mapping that can map language structures and elements in WSDL documents
with increasing levels of sophistication.
Mapping levels 1.0 and 1.1
are available when you apply APAR PK15904. Mapping level 1.2 is available
when you apply APAR PK23547. Each level of mapping inherits the functionality
of the previous mapping, with the highest level of mapping offering the best
capabilities available. This includes providing you with more control over
how data should be converted at run time, as well as lifting restrictions
on support for certain data types and XML elements. These restrictions are
explained in High level language and XML schema mapping for
each supported high level language.
Mapping level 1.0
This is the default mapping level.
This ensures that you can regenerate your older Web service binding files
with a newer level of the Web services assistant without having to make application
changes. It is provided for backwards compatibility and should not be used
for new applications.
In the default mapping:
Mapping level 1.1
At this level of mapping there are
improvements to DFHWS2LS when mapping XML character and binary data types,
in particular when mapping data of variable length. This is where
maxLength and
minLength attributes
are defined with different values in the XML schema. Data is handled in the
following ways:
- Variable length binary data types map to a container. A 16-byte field
is created in the language structure to store the name of the container. At
run time, the binary data is stored in a container and the container name
is put in the language structure.
- Variable length character data types that have a maximum length that is
greater than 32,767 bytes map to a container. A 16-byte field is created in
the language structure to store the name of the container. At run time, the
character data is stored in a container and the container name is put in the
language structure.
- Character and binary data types that have a fixed length that is greater
than 16MB map to a container for all languages except PL/I. In PL/I, fixed
length character and binary data types that are greater than 32,767 bytes
are mapped to a container. A 16-byte field is created in the language structure
to store the name of the container. At run time, the fixed length data is
stored in a container and the container name is put in the language structure.
As
containers are variable in length, fixed length data that is mapped to a container
is not padded with spaces or nulls, or truncated, to match the fixed length
specified in the Web service description. If the length of the data is important,
you can either write your application to check it or turn SOAP validation
on in the CICS region. Note that there is a significant performance impact
when using SOAP validation.
- Character and binary data types that have a fixed length of less than
16MB map to fixed length fields for all languages except PL/I. In PL/I, fixed
length character and binary data types that are 32,767 bytes or less map to
fixed length fields.
- XML schema <list> and <union> data
types map to character fields.
- Base64Binary data types in the XML schema map to a field in the language
structure. The size of the field is calculated using the formula: 4×(ceil(z/3))
where z is the length of the data type in the XML schema
and ceil(x) is the smallest integer greater than or equal
to x. If the length of z is greater
than 24566 bytes, the resulting language structure would fail to compile.
If you have base64Binary data that is greater than 24566 bytes, it is recommended
that you use a mapping level of 1.2. This allows you to map the base64Binary
data to a container instead of using a field in the language structure.
- Schema-defined XML attributes are mapped rather than ignored. A maximum
of 255 attributes are allowed for each XML element. See Support for XML attributes for further information.
- The xsi:nil attribute is supported. See Support for XML attributes for further information.
Mapping level 1.2
At this level of mapping you can
use additional parameters in DFHWS2LS and DFHLS2WS to control how character
and binary data is transformed at run time. If you decide to use the
CHAR-MULTIPLIER parameter
in DFHWS2LS, be aware that the rules below apply after the value of this parameter
is used to calculate the amount of space required for character data.
- DFHWS2LS maps variable length character data types that have a maximum
length of more than 32,767 bytes to a container. You can use the CHAR-VARYING-LIMIT parameter
to set a lower limit. A 16-byte field is created in the language structure
to store the name of the container. At run time, the character data is stored
in a container and the container name is put in the language structure.
- DFHWS2LS maps variable length character data types that have a maximum
length of less than 32,768 bytes to a VARYING structure for all languages
except C/C++ and Enterprise PL/I. In C/C++ these data types are mapped to
null terminated strings, and in Enterprise PL/I these data types are mapped
to VARYINGZ structures. You can use the CHAR-VARYING parameter
to select how variable length character data is mapped.
- DFHWS2LS maps variable length binary data that has a maximum length of
less than 32,768 bytes to a VARYING structure for all languages. If the maximum
length is equal to or greater than 32,768 bytes the data is mapped to a container.
A 16-byte field is created in the language structure to store the name of
the container. At run time, the binary data is stored in a container and the
container name is put in the language structure.
- In DFHLS2WS, character fields map to an xsd:string data
type and can be processed as fixed length fields or null terminated strings
at run time. You can use the CHAR-VARYING parameter
to select how variable length character data should be handled at run time
for all languages except PL/I.
- CICS encodes and decodes base64Binary data as well as hexBinary data.
DFHWS2LS maps base64Binary data types to a container if the maximum length
of the data is greater than 32,767 bytes or when the length is not defined.
If the length of the data is 32,767 or less, the base64Binary data type is
mapped to a VARYING structure for all languages.
If you have character data types in the XML schema that do not have a
length associated with them, you can assign a default length using the
DEFAULT-CHAR-MAXLENGTH parameter
in DFHWS2LS.