GXLHXEC_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 GXLHXEC_CTL_FRAGMENT_PARSE control operation that enables document fragment parsing. If fragment context is already loaded from a prior GXLHXEC_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.

Syntax

int gxlpControl (void * PIMA,
                 int ctl_operation,
                 void * ctl_data_p,
                 int * rc_p,
                 int * rsn_p);

Parameters

PIMA

Supplied parameter

Type:: void *

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

ctl_operation

Supplied parameter

Type:: int

The name of the parameter containing an integer value initialized to GXLHXEC_CTL_LOAD_FRAG_CONTEXT.

ctl_data_p

Supplied and returned parameter

Type:: void *

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 header gxlhctl.h. The name of the data structure is GXLHXFC. 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 GXLHXFC 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:

All the strings for fragment path and namespace binding passed into the GXLHXEC_CTL_LOAD_FRAG_CONTEXT control call needs to be in the encoding of the z/OS XML parser configured at initialization time.
If the caller disables document fragment parsing, the namespace contexts loaded through the GXLHXEC_CTL_LOAD_FRAG_CONTEXT control call will be removed and will not be available during the non-fragment parsing mode.
When the caller issues a GXLHXEC_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 GXLHXEC_CTL_LOAD_FRAG_CONTEXT control call again to load new namespace contexts.

rc_p

Returned parameter

Type:: int *

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

rsn_p

Returned parameter

Type:: int *

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

Example

void * PIMA;
void * fragContext;
void * fragParse;
void * ctl_data_p;
int * option_flags;
void * fragbuf; int fragbuf_left;
void * outbuf; int outbuf_left;
GXLHXFP xfp;
GXLHXFC xfc;
GXLHXFC_ENTRY xfc_entry[1];
char * nspfx_str; char * nsuri_str;
char * fragPath;
int rc, rsn;
/* Perform necessary setup */
nspfx_str = "ibm";
nsuri_str = "http://w3.ibm.com";
fragPath = "/ibm:root/ibm:person";
/* Perform a reset */
gxlpControl(PIMA, 
            GXLHXEC_CTL_FIN, 
            &ctl_data_p, 
            rc, 
            rsn);
/* setup the GXLHXFC structure with namespace binding information */
memset(&xfc,0,sizeof(GXLHXFC));
xfc.XFC_ENTRY_NSCOUNT = 1;
xfc_entry[0].XFC_ENTRY_NSPFX_LEN = strlen(nspfx_str);
xfc_entry[0].XFC_ENTRY_NSPFX_PTR = nspfx_str;
xfc_entry[0].XFC_ENTRY_NSURI_LEN = strlen(nsuri_str);
xfc_entry[0].XFC_ENTRY_NSURI_PTR = nsuri_str;
xfc.XFC_ENTRY_NS_PTR = &xfc_entry
xfc.XFC_FRAGPATH_PTR = fragPath;
xfc.XFC_FRAGPATH_LEN = strlen(fragPath);
fragContext = (void*)&xfc
/* initialize the GXLHXFP structure with zero and set the enable flag */
memset(&xfp,0,sizeof(GXLHXFP));
xfp.XFP_FLAGS = XFP_FLAGS_FRAGMENT_MODE;
fragParse = (void*)&xfp
/* Load the fragment parsing contexts */
gxlpControl(PIMA, 
            GXLHXEC_CTL_LOAD_FRAG_CONTEXT, 
            &fragContext, 
            rc, 
            rsn);