GXLHXEC_CTL_FRAGMENT_PARSE

Description

This indicates that the caller wants to either enable or disable document fragment parsing. This service will decide whether to enable or disable document fragment parsing based on the XFP_FLAGS_FRAGMENT_MODE bit set in the ctl_data_p parameter. Document fragment parsing is disabled by default. This control operation will not cause finish/reset processing to take place. If the caller wants to parse a new complete XML document, a GXLHXEC_CTL_FIN control operation must be called prior to a new parse request. If any error with return code greater than 4 has occurred during document fragment parsing, a GXLHXEC_CTL_FIN control operation must be issued in order to resume parsing. Calling the GXLHXEC_CTL_FIN control operation will disable the document fragment parsing and unload all fragment contexts.

Note:

Document fragment parsing can only be enabled once before disabling. Likewise, document fragment parsing can only be disabled once before enabling.
If the caller disables document fragment parsing, the parse will end and the caller is allowed to parse a new document.

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_FRAGMENT_PARSE.

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 parsing structure, which is mapped by the header gxlhctl.h. The name of the data structure is GXLHXFP. This structure allows the caller to specify whether to enable or disable document fragment parsing through the XFP_FLAGS_FRAGMENT_MODE bit set in the XFP_FLAGS field. Document fragment parsing is disabled by default.

The XFP_XD_PTR is where the service will store the address of the diagnostic area, which is mapped by macro GXLYXD. This provides additional information that can be used to debug problems in data passed to the z/OS XML parser. The diagnostic area resides within the PIMA, and will be overlaid on the next call to the z/OS XML parser.

Tips:

To enable document fragment parsing, set the XFP_FLAGS_FRAGMENT_MODE bit to on.
To disable document fragment parsing, set the XFP_FLAGS_FRAGMENT_MODE bit to off.

Note:

When the caller validates an attribute during fragment parsing, the document fragment passed to the parser should contain only the desired attribute’s value.
When the caller re-enables document fragment parsing after it has been disabled, and without calling load fragment context again, the previous loaded fragment context will be utilized in this new fragment parse. This includes the fragment path and any namespace binding information.
The OSR must be loaded by way of the XEC_CTL_LOAD_OSR control call prior to enabling fragment parsing.

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); 
/* Note: the OSR must be loaded at this point */
/* Enable document fragment parsing */
gxlpControl(PIMA, 
            GXLHXEC_CTL_FRAGMENT_PARSE, 
            &fragParse, 
            &rc, 
            &rsn); 
/* Parse the desired document fragments */ 
gxlpParse(PIMA, 
          option_flags, 
          &fragbuf, 
          &fragbuf_left, 
          &outbuf, 
          &outbuf_left,
          &rc, 
          &rsn); 
/* Disable document fragment parsing */ 
xfp.XFP_FLAGS = 0; 
gxlpControl(PIMA, 
            GXLHXEC_CTL_FRAGMENT_PARSE, 
            &fragParse, 
            &rc, 
            &rsn);