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 gxlhxec.h . These functions include:
- GXLHXEC_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 GXLHXEC_CTL_FIN.
- GXLHXEC_CTL_FEAT
- The caller wants to change the
feature flags. A GXLHXEC_CTL_FIN function will be done implicitly.
Note: Some feature flags are not supported on gxlpControl.
See
GXLHXEC_CTL_FEAT for a list of these
feature flags.
For more information on this function, see GXLHXEC_CTL_FEAT.
- GXLHXEC_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 GXLHXEC_CTL_LOAD_OSR.
- GXLHXEC_ 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 GXLHXRSN_BUFFER_OUTBUF_SMALL
reason code has been received from gxlpParse.
Note: Finish and reset
processing is performed by all operations available through this control
service, except GXLHXEC_CTL_QUERY_MIN_OUTBUF and GXLHXEC_CTL_LOAD_OSR.
See the descriptions of these operations under ctl_operation for more
information.
For more information on this function, see GXLHXEC_CTL_QUERY_MIN_OUTBUF.
- GXLHXEC_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 notesfor more information.
- If the parse instance has been initialized to
process XDBX binary XML streams, then the input stream will never
have entity references to resolve. Performing the GXLHXEC_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 this control request if the input
is an XDBX stream.
For more information on this function, see GXLHXEC_CTL_ENTS_AND_REFS.
- GXLHXEC_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_operation
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 GXLHXEC_CTL_LOAD_FRAG_CONTEXT.
- GXLHXEC_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_operation
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 GXLHXEC_CTL_FRAGMENT_PARSE.
- GXLHXEC_CTL_RESTRICT_ROOT
- The caller wishes to restrict
the root element name on the next parse. This operation is only valid
when the PIMA has been configured for validation and schema information
is requested. For more information on this function, see GXLHXEC_CTL_RESTRICT_ROOT.
- GXLHXEC_CTL_ERROR_HANDLING
- With this control operation,
the caller can do the following for a validating parse:
- 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 a non-validating parse, it can be used to:- Enable the ability to continue parsing when an undefined prefix
is encountered on an element or attribute. The "prefix:local name" will
be treated as the local name.
- Request an auxiliary information record that contains the tolerated
return and reason codes and the error offset.
For more information on this function, see GXLHXEC_CTL_ERROR_HANDLING.
Performance Implications
The finish-and-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 the initialization service.
The reset features function also allows the caller to re-initialize
the z/OS XML parser as
above and allows the feature flags to be reset as well.