XEC_CTL_LOAD_FRAG_CONTEXT

Description

This indicates that the caller wants to load fragment context into the z/OS XML parser. This service allows the caller to load namespace binding information and fragment paths for document fragment parsing. Namespace binding information is optional. Fragment path is required . This service must be issued prior to a XEC_CTL_FRAGMENT_PARSE control operation that enables document fragment parsing. If fragment context is already loaded from a prior XEC_CTL_LOAD_FRAG_CONTEXT control operation and this service is called again, the new fragment context will overlay the previously loaded context. This control operation will not cause finish/reset processing to take place.

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 the initialization service.

ctl_option

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword containing an integer value initialized to XEC_CTL_LOAD_FRAG_CONTEXT.

ctl_data

Supplied and returned parameter

Type:

Address

Length:

Fullword (Doubleword)

This parameter must contain a pointer to where the service will locate the address of the document fragment context structure, which is mapped by the macro GXL1CTL (GXL4CTL). The name of the data structure is GXLXFC. This structure allows the caller to provide the fragment path and namespace binding information to assist document fragment parsing.

To validate an element during document fragment parsing, the fragment path represents the path from the root element of the complete document to the root element of the fragment, which consists of prefixes and localnames. To validate an attribute during fragment parsing, the fragment path represents the path from the root element of the complete document to the desired attribute name. The fragment path is required in order to perform validation in fragment parsing.

The fragment path syntax is defined below:

FragmentPath ::= ('/' ElementName)* FragmentData
FragmentData ::= '/' ElementName ('/@' AttributeName)?
ElementName ::= QName
AttributeName ::= QName

Namespaces bindings allow unique strings of text that identify a given space of names to be represented by a prefix. This allows references to elements with the same name to be differentiated, based on the namespace to which they belong. These bindings may not be present in the document fragment, and often these bindings exist in the ancestor elements’ start tag that is not part of the document fragment. The caller can provide a complete context containing multiple namespace bindings in the GXLXFC structure. The namespace binding is optional information.

However, if there is an XML instance document that uses a default namespace, the caller must still specify a prefix on the element names in the fragment path. The caller must also specify this prefix along with the namespace URI in the namespace binding information. The actual prefix does not matter; only the namespace URI matters, but the prefix will associate each element in the fragment path with the correct namespace.

Note:

1. All the strings for fragment path and namespace binding passed into the XEC_CTL_LOAD_FRAG_CONTEXT control call needs to be in the encoding of the z/OS XML parser configured at initialization time.
2. If the caller disables document fragment parsing, the namespace contexts loaded through the XEC_CTL_LOAD_FRAG_CONTEXT control call will be removed and will not be available during the non-fragment parsing mode.
3. When the caller issues a XEC_CTL_LOAD_FRAG_CONTEXT control call to load namespace contexts, the namespace contexts will be available when the z/OS XML parser switches into fragment parsing mode. The namespace contexts will only get unloaded and replaced if the caller terminates the parser or issues XEC_CTL_LOAD_FRAG_CONTEXT control call again to load new namespace contexts.

return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of the 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.