GXL1INI (GXL4INI) — initialize a parse instance

Description

The GXL1INI (GXL4INI) callable service initializes the PIMA and records the addresses of the caller's system service routines (if any). The PIMA storage is divided into the areas that will be used by the z/OS XML parser to process the input buffer and produce the parsed data stream.

Performance Implications

The initialization of structures used by the z/OS XML parser in the PIMA is only done once per parse and is therefore unlikely to affect performance. The caller may choose to reuse the PIMA after each parse to eliminate the overhead of storage allocation and the page faults that occur when referencing new storage. In this case, a control operation is required to reset the necessary fields in the PIMA before parsing can continue.

Syntax

call gxl1ini,(PIMA,
             PIMA_len,
             ccsid,
             feature_flags,
             sys_svc_vector,
             sys_svc_parm,
             return_code,
             reason_code)

Parameters

PIMA

Supplied parameter

Type:: Character string
Length:: determined by the PIMA_len parameter

The name of the Parse Instance Memory Area (PIMA). The PIMA must be aligned on a doubleword boundary, otherwise, results are unpredictable. See the Usage notes below for additional details on the use of this area.

PIMA_len

Supplied parameter

Type:: Integer
Length:: Fullword (Doubleword)

The name of an area containing the length of the Parse Instance Memory Area. This service validates the length of this area against a minimum length value. The minimum length of the PIMA depends on whether or not validation will be performed during the parse. This minimum length value can be found in:

XEC_NVPARSE_MIN_PIMA_SIZE (non-validating parse)
XEC_VPARSE_MIN_PIMA_SIZE (validating parse)

ccsid

Supplied parameter

Type:: Integer
Length:: Fullword

The Coded Character Set IDentifier (CCSID) that identifies the document’s character set. The CCSID value in this parameter will override any character set or encoding information contained in the XML declaration of the document. A set of CCSID constants for supported encodings has been declared in GXLYXEC. See Supported encodings for a full list of supported encodings.

feature_flags

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains an integer value representing one or more of the following z/OS XML parser features. OR these flags together as needed to enable features. Choose any of the following:

XEC_FEAT_STRIP_COMMENTS - effectively strip comments from the document by not returning any comments in the parsed data stream.
XEC_FEAT_TOKENIZE_WHITESPACE - set the default token value for white space preceeding markup within the context of the root element to an explicit white space value. Use this value in conjunction with the special xml:space attribute to determine how such white space gets classified.
XEC_FEAT_CDATA_AS_CHARDATA - return CDATA in records with a CHARDATA token type. The content of these records may contain text that would normally have to be escaped to avoid being handled as markup.
XEC_FEAT_JST_OWNS_STORAGE - allocate storage as Job Step Task (JST) related instead of task related. See the Usage notes below for more information.
XEC_FEAT_RECOVERY - this turns on the recovery routine.
Note: The following only applies when the feature flag is ON:
- If running in SRB mode, an error message will be returned to the caller.
- If a parse request is made in SRB mode, the parse will fail.
- If there is an FRR, an error message will be returned to the caller during the parse step.
XEC_FEAT_SOURCE_OFFSETS - this includes records in the parsed data stream which contain offsets to the corresponding structures in the input document.
XEC_FEAT_FULL_END - this expands the end tags to include the local name, prefix and URI corresponding to the qname on the end tag.
XEC_FEAT_VALIDATE - this initializes a parse instance that allows for validation during parsing. See the usage notes below for details on validation.
XEC_FEAT_SCHEMA_DISCOVERY – report schema location information and allow for an OSR to be loaded once the information has been reported. XEC_FEAT_VALIDATE must also be enabled, otherwise GXL1INI (GXL4INI) will return an error. See Usage notes for more information on schema discovery. Default: off
XEC_FEAT_XDBX_INPUT - indicates that the data presented to z/OS® XML in the input buffer is in XDBX binary XML form, rather than conventional text. This feature requires that XEC_FEAT_VALIDATE is also set, and that the encoding specified in the CCSID parameter is UTF-8. See Usage notes for more information on XDBX input streams. Default: off.
XEC_FEAT_ALLOW_VECTOR - this allows the parser to use vector instructions. Default: off.

Note: By using the values of off (zero), W3C XML compliant output is generated. Turning on options XEC_FEAT_STRIP_COMMENTS, XEC_FEAT_TOKENIZE_WHITESPACE and XEC_FEAT_CDATA_AS_CHARDATA will cause the output to vary from standard compliance.

If none of the features are required, pass the name of a fullword field containing zero. Do not construct a parameter list with a zero pointer in it.

sys_svc_vector

Supplied parameter

Type:: Structure
Length:: Variable

The name of a structure containing a count of entries that follow and then a list of 31 (64) bit pointers to system service routines. Specify the name of a word containing 0 if no services are provided. See the z/OS XML System Services exit interface chapter for more details.

sys_svc_parm

Supplied parameter

Type:: Address
Length:: Fullword (Doubleword)

The name of a parameter which is passed to all system service exits. This provides for communication between the z/OS XML parser caller and its exit routines. Specify the name of a location containing 0 if no parameter is required for communication.

return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the service stores the return code.

reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the service stores the reason code. The reason code is only relevant if the return code is not XRC_SUCCESS.

All parameters in the parameter list are required.

Return and Reason Codes:

On return from a call to this service, register 15 will contain the return code. The return and reason code are both also set as output parameters. The value of the reason code is undefined when the return code has no associated reasons. Return and reason codes are defined in macro GXLYXR. For reason code descriptions, also see Reason codes listed by value.

Example

For an AMODE 31 example using this callable service, see GXL1INI example. For an AMODE 64 example using this callable service, see GXL4INI example.

Usage notes

The z/OS XML parser creates a variety of control blocks, tables, stacks, and other structures in the Parse Instance Memory Area. The caller must provide an area that is at least as large as constant XEC_MIN_PIMA_SIZE. In the event that this area is not large enough to parse the input document, the z/OS XML parser will allocate additional memory using either the default memory allocation mechanism or the memory allocation exit that the caller has provided.
When the PIMA is reused for subsequent parses, the same features, ccsid and service exits will apply. If any of these values need to change, you should terminate the parse instance (call GXL1TRM (GXL4TRM)) and call GXL1INI (GXL4INI) again with the options you require.
When the XEC_FEAT_TOKENIZE_WHITESPACE feature is set, the default classification for white space that precedes markup within the context of the root element will be XEC_TOK_WHITESPACE. This token type is returned if either the white space being parsed does not have an xml:space context, or if the xml:space setting is 'default'. When the tokenize white space feature is not enabled, or if the white space does not precede markup, this white space will be returned in the parsed data stream containing character data with a token type of XEC_TOK_CHAR_DATA.
The XEC_FEAT_JST_OWNS_STORAGE feature only applies to callers running in non-cross memory task mode who take the option of allowing the z/OS XML parser to allocate additional storage as needed. This feature should be specified when PIMAs are used on multiple tasks in order to prevent task termination from causing storage extents to be freed before the z/OS XML parser is done using them.
Before requesting the initialization of a validating parse instance, the validation function must be loaded – either through one of the methods that the system provides, or by the z/OS XML load service. Failure to do so will result in an error indicating that the function is not available. See the description of GXL1LOD (GXL4LOD) — load a z/OS XML function for more information.
Be sure that the size of the PIMA provided is large enough for the XML processing function, either validating or non-validating parse, that will be performed. Also, make sure that there is an appropriate minimum PIMA size constant defined for each in GXLYXEC.
The performance of a validating parse will be best when the parsed document is in the UTF-8 encoding. The other encodings supported by z/OS XML System Services are also supported during a validating parse, but there is significant additional overhead that will impact performance.
For usage notes on parsing XDBX input streams, see Parsing XDBX input streams.