GXL1PRS (GXL4PRS) — parse a buffer of XML text

Description

The GXL1PRS callable service parses a buffer of XML text and places the result in an output buffer.

Performance Implications

Ideal performance will be obtained when the PIMA is sufficiently large to contain all the needed data structures, and the input and output buffers are large enough to process the entire XML document. During the parsing process, the z/OS XML parser constructs persistent information in the PIMA that can be reused within a parse instance. If the caller is going to process multiple documents that contain similar sets of symbols (namespaces and local element and attribute names in particular), then reusing the PIMA will improve performance during the processing of subsequent documents. If this behavior is not required, the PIMA should be cleaned up by calling GXL1TRM (GXL4TRM) and reinitialized by calling GXL1INI (GXL4INI) before using the PIMA for another parse request.

Syntax

call gxl1prs,(PIMA,
             option_flags,
             input_buffer_addr,
             input_buffer_bytes_left,
             output_buffer_addr,
             output_buffer_bytes_left,
             return_code,
             reason_code)

Parameters

PIMA

Supplied parameter

Type:: Character string
Length:: Variable

The name of the Parse Instance Memory Area (PIMA which has been previously initialized with a call to GXL1INI (GXL4INI)).

option_flags

Supplied parameter

Type:: Integer
Length:: Fullword

Specify a word of zeroes for this parameter. In the future, this field will allow options to be compatibly added to the service.

input_buffer_addr

Supplied and returned parameter

Type:: Address
Length:: Fullword (Doubleword)

The name of a fullword (doubleword) that contains the address of the buffer with the XML text to parse. The z/OS XML parser updates this parameter to provide important return information when control returns to the caller. See the Usage notes below for details.

input_buffer_bytes_left

Supplied and returned parameter

Type:: Integer
Length:: Fullword (Doubleword)

The name of a fullword (doubleword) that contains the number of bytes in the input buffer that have not yet been processed. The z/OS XML parser updates this parameter to provide important return information when control returns to the caller. See the Usage notes for details.

output_buffer_addr

Supplied and returned parameter

Type:: Address
Length:: Fullword (Doubleword)

The name of a fullword (doubleword) that contains the address of the buffer where the z/OS XML parser should place the parsed data stream. The z/OS XML parser updates this parameter to provide important return information when control returns to the caller. See the Usage notes for details.

output_buffer_bytes_left

Supplied and returned parameter

Type:: Integer
Length:: Fullword (Doubleword)

The name of a fullword (doubleword) that contains the number of available bytes in the output buffer. When the z/OS XML parser returns control to the caller, this parameter will be updated to indicate the number of unused bytes in the output buffer. This buffer must always contain at least a minimum number of bytes as defined by the XEC_MIN_OUTBUF_SIZE constant, declared in macro GXLYXEC. This service will validate the length of this area against this minimum length value.

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 GXL1PRS example. For an AMODE 64 example using this callable service, see GXL4PRS example.

Usage notes

When the z/OS XML parser returns successfully to the caller, the input and output buffer addresses will be updated to point to the byte after the last byte successfully processed. The input_buffer_bytes_left and output_buffer_bytes_left parameters will also be updated to indicate the number of bytes remaining in their respective buffers. In the event of an error caused by a problem with the document being parsed, the input buffer address will point to the byte of the input stream where the problem was detected, and the associated bytesleft value will indicate the same position in the buffer. An error record will be written to the parsed data stream indicating the nature of the problem, and the output buffer address and bytesleft fields will point to the next available byte, as in the success case. See Parsing XML documents for more information about how input and output buffers are managed between the caller and z/OS XML parser.
In cases where parsing terminates because of an error, the z/OS XML parser will often have partially processed an item from the input document before returning to the caller. The caller has the option of retrieving the address of the diagnostic area using the GXL1CTL (GXL4CTL) service. The XD_LastRC/XD_LastRsn return/reason code combination will contain an indication of the item being parsed. Retrieving the reason code in this manner is an example of the indirect method for obtaining a specific reason code.
The z/OS XML parser will always check that the output buffer length passed to it is greater than the required minimum (XEC_MIN_OUTBUF_SIZE). If this minimum length requirement is not met, the z/OS XML parser will return with a return/reason code of XRC_FAILURE/XRSN_BUFFER_OUTBUF_SMALL. Output buffer spanning will only occur if the caller meets the minimum output buffer length requirement when the z/OS XML parser is invoked. Once parsing begins, and the buffer info record has been written to the output buffer, buffer spanning is enabled. The caller will then receive an end-of-output-buffer indication when the end of the output buffer is reached. In addition, many non-splittable records will be larger than the minimum output buffer size. If there is not enough space in the output buffer for the first record, then XRC_FAILURE/XRSN_BUFFER_OUTBUF_SMALL will be returned. Therefore, it's recommended that the output buffer sizes should be large enough to fit the largest record that is expected to be encountered.
When schema discovery is enabled, XRSN_NEED_OSR may be returned from a parse request. This signifies that the parser has finished parsing the root element start tag and has returned enough information to identify a schema. At this point, a load OSR operation may be performed without the operation resetting the parser. If a reset is intended, then an explicit call to GXL1CTL (GXL4CTL) with the XEC_CTL_FIN option must be made prior to the next parse.
When the z/OS XML parser returns a failure to the caller, GXL1CTL (GXL4CTL) must issue the control option XEC_CTL_FIN in order to continue document fragment parsing or non-fragment parsing.
When the z/OS XML parser returns successfully to the caller, it indicates the end of the provided input buffer was reached and the parsed XML data is well-formed. When document fragment parsing is enabled, this service will confine well-formedness checking to the scope of the document fragment. This behavior is enabled and disabled through use of the XEC_CTL_FRAGMENT_PARSE control operation.
If the caller disables fragment parsing by calling GXL1CTL (GXL4CTL) with the control option XEC_CTL_FRAGMENT_PARSE, and the z/OS XML parser returns to the input or output buffer during document fragment parsing, an error will occur.
If the caller performs validation in fragment parsing, the input buffer must be restricted to a single element and its descendants, optionally followed by comments and processing instructions.
If the caller performs document fragment parsing on an attribute, the input buffer should only contain the desired attribute’s value. See the following example:
```
XML Document: <root> <pfx:ln attr="attributeValue"/> </root>
Fragment Path = /root/pfx:ln/@attr
Input Buffer = attributeValue
```