Description
This is a general purpose service
which provides control functions for interacting with the
z/OS XML parser. The function
performed is selected by setting the
ctl_option parameter
using the constants defined in GXLYXEC. These functions include:
- XEC_CTL_FIN
- The caller has finished parsing
the document. Reset the necessary structures so that the PIMA can
be reused on a subsequent parse, and return any useful information
about the current parse. For more information on this function, see XEC_CTL_FIN.
- XEC_CTL_FEAT
- The caller wants to change
the feature flags. A XEC_CTL_FIN function will be done implicitly.
Note: Some feature flags are not supported on GXL1CTL
(GXL4CTL). See
XEC_CTL_FEAT for information
on which feature flags are not supported.
For more information
on this function, see XEC_CTL_FEAT.
- XEC_CTL_LOAD_OSR
- The caller wants to load
and use an Optimized Schema Representation (OSR) for a validating
parse. For more information on this function, see XEC_CTL_LOAD_OSR.
- XEC_ CTL_QUERY_MIN_OUTBUF
- The caller is
requesting the minimum output buffer size required on a subsequent
parse. This function will also enable the parse to be continued after
a XRSN_BUFFER_OUTBUF_SMALL reason code has been received from GXL1PRS(GXL4PRS).
Note: Finish
and reset processing is performed by all operations available through
this control service, except XEC_CTL_QUERY_MIN_OUTBUF and XEC_CTL_LOAD_OSR.
See the descriptions of these operations under ctl_option for more
information.
For more information on this function, see XEC_CTL_QUERY_MIN_OUTBUF.
- XEC_CTL_ENTS_AND_REFS
- The
caller can request additional flexibility when processing character
and entity references as follows:
- When an unresolved entity reference is encountered, the caller
can request that the parser stop processing and return an error record.
- When a character reference which cannot be represented in the
current code page is encountered, z/OS XML System Services places a dash
(-) in the output stream for that character. The caller may specify,
with this control call, to output a character other than dash (-)
in the output stream.
- When a character reference which cannot be represented in the
current code page is encountered, the caller can request, using this
control call, an additional output record to be generated in the output
stream that contains information about this character reference.
Note: - Finish and reset processing is performed for this control operation.
See Usage notes for more information.
- If the parse instance has been initialized to
process XDBX binary XML streams, then the input stream will never
have any entity references to resolve. Performing the XEC_CTL_ENTS_AND_REFS
operation will have no effect on the output of the parser. In order
to prevent accidental attempted use of this operation in this environment,
the parser will return a failure.
For more information on this function, see XEC_CTL_ENTS_AND_REFS.
- XEC_CTL_LOAD_FRAG_CONTEXT
- The caller wants
to load fragment context including fragment path and namespace binding
information for document fragment parsing.
Note: - This control operation does not perform finish and reset processing
through the control service. See the description in ctl_option for
more information.
- Fragment parsing is not supported for XDBX input.
For this reason, attempting to load a fragment context for parse instances
initialized to handle XDBX streams will fail.
For more information on this function, see XEC_CTL_LOAD_FRAG_CONTEXT.
- XEC_CTL_FRAGMENT_PARSE
- The caller wants
to enable or disable document fragment parsing.
Note: - This control operation does not perform finish and reset processing
through the control service. See the description in ctl_option for
more information.
- Fragment parsing is not supported for XDBX input.
For this reason, attempting to enable document fragment parsing for
parse instances initialized to handle XDBX streams will fail.
For more information on this function, see XEC_CTL_FRAGMENT_PARSE.
- XEC_CTL_RESTRICT_ROOT
- The caller can restrict
the root element name on the next parse. This operation is only valid
if the PIMA has been configured for validation and schema information
is requested. For more information on this function, see XEC_CTL_RESTRICT_ROOT.
- XEC_CTL_ERROR_HANDLING
- With this control
operation, the caller can do the following:
- Enable the creation of auxiliary records which can include the
location of an error in the XML document, the string which is in error,
and also a possible expected string.
- Enable position indexes to be present in the error location path
in order to facilitate locating the error.
For more information on this function, see XEC_CTL_ERROR_HANDLING.
Performance Implications
The finish/reset
function allows the caller to re-initialize the PIMA to make it ready
to handle a new XML document. This re-initialization path enables
the z/OS XML parser to
preserve its existing symbol table, and avoid other initialization
pathlength that's performed by calling GXL1INI (GXL4INI).
Example
For an AMODE 31 example using this
callable service, see GXL1CTL example. For an
AMODE 64 example using this callable service, see GXL4CTL example.
Usage notes
The purpose of the
finish/reset function of the GXL1CTL (GXL4CTL) service is to perform
the following:
- Reset the necessary structures and fields within the PIMA to effect
a re-initialization so that it can be reused without the overhead
of full initialization. See the table below for list of structures
and fields reset by each control function.
- Allow the z/OS XML parser to
return extended diagnostic information to the caller in the event
of a failure. This allows the caller to identify certain problems
that can be corrected.
- The "finish and reset" operation can be thought of as the most
basic control operation that is a functional subset of all control
operations. It resets the state of the parser to the original state
immediately after the parse instance was first initialized. This
state includes the feature flags. If the caller initializes a parse
instance, then changes the feature settings with a feature control
operation, and still later performs a "finish and reset" control operation,
the feature flags will revert back to those settings at the time the
parse instance was originally initialized. If the caller wishes to
retain the current feature settings during a parser reset, they should
simply perform another feature control operation with the current
feature set.
- The OSR load operation allows the caller to specify an OSR for
the parser to use, and to bind a handle to associate with to it.
The GXLYXOSR macro provides the interface for passing information
to the parser about the OSR. See C/C++ header files and assembler macros for
more details about how it is used. As mentioned above, "finish and
reset" processing will occur as a part of this load operation. However,
the reset will occur through a feature control operation, using the
current feature set. In this way, the current feature flags for the
parse instance are not altered by the OSR load control operation.
- The entities and references operation allows the caller to specify
additional processing with regard to entity and character references.
The GXLYCTL macro provides the interface for passing the information
to the control function. As mentioned above, "finish and reset" processing
will occur as part of this control operation. However, the reset
will occur through a feature control operation, using the current
feature set. In this way, the current feature flags for the parse
instance are not altered by the entities and references control operation.
- When document fragment parsing operation is enabled, the z/OS XML parser will no longer
accept non-fragmented documents. If the caller wants to parse a complete
document after enabling document fragment parsing, this service must
be called again to disable document fragment parsing.
- When document fragment parsing is enabled, the well-formedness
checking in the subsequent parsing will be confined to the scope of
the document fragment. Well-formedness checking is performed again
on the whole document when document fragment parsing is disabled.
- When document fragment parsing is enabled, a whitespace token
will be placed into the output buffer when whitespace is parsed at
the end of the input buffer for each document fragment.
- The OSR context is unaffected by document fragment parsing. Any
OSR that is loaded when document fragment parsing is enabled will
still be loaded for the parse of the fragment, and will remain loaded
if fragment parsing is disabled.
For a list of properties and resources reset
by the control functions, see Properties and resources reset by control functions.