GXL1QXD (GXL4QXD) — query an XML document

Description

This service allows a caller to obtain the XML characteristics of a document. The XML characteristics are either the default values, the values contained in an XML declaration or a combination of both.

Performance Implications

There are no performance implications.

Syntax

call gxl1qxd,(work_area,
             work_area_length,
             input_buffer,
             input_buffer_length,
             return_data,
             return_code,
             reason_code)

Parameters

work_area

Supplied parameter

Type:: Character string
Length:: Variable

The name of a work area. The work area must be aligned on a doubleword boundary. If not on a doubleword boundary, results are unpredictable. See the Usage notes below for additional details on the use of this area.

work_area_len

Supplied parameter

Type:: Integer
Length:: Fullword (Doubleword)

The name of an area containing the length of the work area. The minimum length of this area is declared as a constant XEC_MIN_QXDWORK_SIZE in macro GXLYXEC. This service validates the length of this area against this minimum length value.

input_buffer

Supplied parameter

Type:: Character string
Length:: Variable

The name of an input buffer containing the beginning of the XML document to process. See the Usage notes below for details.

input_buffer_length

Supplied parameter

Type:: Integer
Length:: Fullword (Doubleword)

The name of an area containing the length of the input buffer.

return_data

Returned parameter

Type:: Address
Length:: Fullword (Doubleword)

The name of a fullword (doubleword) where the service will return the address of the data which describes the XML document characteristics. This return information will contain values that are either extracted from the XML declaration or defaulted according to the XML standard. This return area is mapped by macro GXLYQXD (see gxlhqxd.h (GXLYQXD) - mapping of the output from the query XML declaration service), and is located within the work area specified by the work_area parameter. The caller must not free the work_area until it is done referencing the data returned from this service.

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 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 (see gxlhxr.h (GXLYXR) - defines the return codes and reason codes). For reason code descriptions, also see Reason codes listed by value.

Example

Usage notes

The input buffer passed to this service must contain the beginning of the XML document to process. This service will look for any XML declaration that is present and extract the version, encoding, and standalone value that are present. In the event that the document does not contain an XML declaration, or a given value is missing from the declaration, this service will return an appropriate default, as specified by the XML standard. On success, the return data address for this service will contain a pointer into the work area where the return data has been collected.
Unlike the GXL1PRS (GXL4PRS) or GXL1CTL (GXL4CTL) services that must be performed within a parse instance, this service does not require any of the internal resources that the z/OS XML parser creates in the PIMA during initialization. It does not advance the input pointer or modify the state of the parse in any way. It is a simple standalone service that allows a caller to query important information about the document before establishing a parse instance and performing the parse.
Buffer spanning is not supported by this service, as it is by GXL1PRS (GXL4PRS). If either the input buffer or the work area are too small, this service will terminate with an appropriate return/reason code.
This service is useful for checking to see if a conversion to one of the supported encodings is required before parsing the document.
Encoding names supported include the IANA recommended names which have corresponding IBM® CCSID values.
This service does not provide full well-formedness checking of the input it processes.