Before
beginning document fragment parsing, the caller must specify the fragment
path. The namespace binding information is also required when there
is namespace context associated with the fragment path. To load the
fragment context, the caller needs to issue a gxlpControl call with
the control option XEC_CTL_LOAD_FRAG_CONTEXT. This must occur before
document fragment parsing is enabled .
Note: A new OSR with the extra
Fragment Parsing Table information is required in order to parse a
document fragment with validation. Pre-z/OS V1R12 OSRs cannot be used
in this parsing environment. To load the OSR, the caller needs to
issue a control call with the control option XEC_CTL_LOAD_OSR. This
must occur before document fragment parsing is enabled.
To
enable fragment parsing, the caller needs to issue a gxlpControl call
with the control option XEC_CTL_FRAGMENT_PARSE and set the XFP_FLAGS_FRAGMENT_MODE
bit to 'ON' in the control data structure. This must occur prior to
issuing the gxlpParse call with the XML document fragment loaded into
the input buffer. The z/OS® XML
parser will perform regular parsing including well-formedness checking
and validation, however the root element is not required. The XML
declaration and Doctype Declaration are not allowed as part of the
document fragment.
If the z/OS XML parser reaches
the end of the input buffer, and the parsed document fragment is well-formed,
the z/OS XML parser ends the
parse successfully. If the z/OS XML
parser reaches the end of the input buffer, and the parsed document
fragment is not well-formed, the z/OS XML
parser will return an error. Otherwise, the z/OS XML parser will return to request more
input or output buffer space. Fragment parsing with validation is
restricted to a single attribute, as well as a single element and
its descendants, optionally followed by comments and processing instructions.
Attempts to parse multiple element fragments with validation will
result in an error . If the caller decides to finish parsing the document
fragment, and the z/OS XML
parser returns to request for more input and output buffer space during
fragment parsing, an error will occur. A gxlpControl call with the
control option XEC_CTL_FIN must be issued in order to parse another
document or document fragment.
When the caller finishes parsing a document fragment, they must
issue a gxlpControl call with the control option XEC_CTL_FRAGMENT_PARSE
and set the XFP_FLAGS_FRAGMENT_MODE bit to 'OFF' in the control data
structure to notify the z/OS XML parser that fragment
parsing has been disabled.
The following is an example call sequence for a validating fragment
parse:
gxlpLoad
gxlpInit
gxlpControl(XEC_CTL_LOAD_OSR)
gxlpControl(XEC_CTL_LOAD_FRAG_CONTEXT, FPATH)
gxlpControl(XEC_CTL_FRAGMENT_PARSE) -- enable the fragment mode
gxlpParse
gxlpControl(XEC_CTL_FRAGMENT_PARSE) -- disable the fragment mode
gxlpTerminate
If the caller wants to perform document fragment
parsing or non-fragment parsing on a different document, a gxlpControl
call with the control option XEC_CTL_FIN must be issued prior to a
gxlpParse call. This XEC_CTL_FIN operation will reset and prepare
the current parse instance for a new document parse. The loaded fragment
context will remain in storage and become active when fragment mode
is enabled again. If the next document fragment to be parsed requires
different fragment path or namespace binding information, then a new
XEC_CTL_LOAD_FRAG_CONTEXT control call must be made to update this
information. Failure to load the correct information may cause unexpected
results such as well-formedness or validation errors.
The following is an example call sequence for a validating parse
with fragments from two different documents:
gxlpLoad
gxlpInit
gxlpControl(XEC_CTL_LOAD_OSR)
gxlpParse
gxlpControl(XEC_CTL_LOAD_FRAG_CONTEXT, FPATH1)
gxlpControl(XEC_CTL_FRAGMENT_PARSE, BIT:ON) -- enable fragment mode #1
gxlpParse -- parse document fragment #1 part1 in FPATH1
gxlpParse -- parse document fragment #1 part2 in FPATH1
gxlpControl(XEC_CTL_FRAGMENT_PARSE, BIT:OFF) -- disable fragment mode #1
gxlpControl(XEC_CTL_FIN)
gxlpControl(XEC_CTL_LOAD_FRAG_CONTEXT, FPATH2)
gxlpControl(XEC_CTL_FRAGMENT_PARSE, BIT:ON) -- enable fragment mode #2
gxlpParse -- parse document fragment #2 in FPATH2
gxlpControl(XEC_CTL_FRAGMENT_PARSE, BIT:OFF) -- disable fragment mode #2
gxlpTerminate
Restrictions: Validation in fragment parsing cannot satisfy
all aspects of schema validation for an arbitrary input string as
various aspects of schema validation refer to other aspects of the
document. Although it may be possible to validate some aspects of
the following schema constructs, in general they require the entire
document to be available. The restriction falls into two broad categories:
those things that cannot be validated reasonably and those things
that can be validated in isolation but could possibly fail within
the context of a document. The first category is avoided by requiring
the client to ensure that the name of the element matches the element
that it is replacing. The second category includes the following:
- Namespaces
- The gxlpControl API allows the establishment of a namespace context
in which to do the validation. If none are provided, it will be assumed
that there are no namespaces bound to prefixes other than those bound
within the input to be validated.
- ID/IDREF
- This requires knowledge of other portions of the instance document
and will only be validated using the appropriate simple content validator.
- Unique elements and attributes
- Unique elements and attributes are contained within the subtree
of the element containing the unique schema indicator. If this element
is the root for the document fragment or is a descendant, then the
unique element or attribute can be handled normally. However, if
the unique specifier is an ancestor of the root, there could be collisions
which will not be detected.
- KEY/KEYREF
- This is similar to ID/IDREF in that the KEYs must be unique and
KEYREFs must match a KEY, and similar to unique attributes in that
it must be contained in the subtree. Those aspects that can be checked
are validated, but those aspects that refer to ancestral content are
not validated.
- Validating attributes and elements with attributes (other than
xsi:type)
- These attributes are meaningless in fragments and are only validated
using the appropriate simple type validator. This means that the
special characteristics of these attributes will not have an effect.
For example, schemaLocation will not indicate a schema but will just
be validated against string.
- xsi:type
- When xsi:type is an attribute on an element, it will have the
expected effect. Validating this as a single attribute will result
in it being validated using the qname simple type validator.
- DTDs
- Because the z/OS XML parser is
only passed the document fragment, it has no knowledge of the entity
definitions or default attribute values in the internal DTD subset.
Therefore, if the schema contains an attribute with a type of ENTITY,
it will fail. It will also fail if it relies on a default attribute
value defined in the internal DTD subset.
- Comments, processing Instructions and annotations
- These constructs can be included in the normal ways within an
element being validated.
- Attributes that rely on an xsi:type attribute to also be present
- When validating an attribute, the attribute is validated using
the type containing the attribute. Therefore, it cannot be a derived
attribute or an attribute only available on a derived type.
- The parser cannot determine the actual particle when an element
is indicated
- The parser cannot determine the actual particle when an element
is indicated. Rather, the designator is used to indicate a type so
information on the particle, such as fixed values and nillable are
not checked.
- The impact of the validation within its context is not checked
- The impact of the validation within its context is not checked.
Therefore, the effects of changing an element to a different element
(likewise with attributes) are not checked. Checking such characteristics
requires validating the parent and document fragment does not provide
this information.