GXLHXEC_CTL_RESTRICT_ROOT

Description

This operation indicates that the caller wishes to restrict the root element name on the next parse. If the root element name is not any of those listed in the GXLHXRR data area, this call will cause the parse to stop. This operation will reset the PIMA.

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

ctl_data_p

Supplied and returned parameter

Type:: void *

This parameter contains the address of an area with information about the restricted root element. This area is mapped by the header file gxlhxrr.h. This provides a list of names that must contain the name of the root element in order for the validating parse to succeed.

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 * ctl_data_p;
void * rootTable;
void * inbuf; int inbuf_left;
void * outbuf; int outbuf_left;
GXLHXRR_ENTRY *entry;
int * option_flags;
GXLHXRR xrr;
char * root_str; char * rootnsuri_str;
int rc, rsn;
/* Perform necessary setup */
root_str = "personal";
rootnsuri_str = "http://w3.ibm.com";
/* Perform a reset */
gxlpControl(PIMA, 
            GXLHXEC_CTL_FIN, 
            &ctl_data_p, 
            rc, 
            rsn); 
/* setup the GXLHXRR structure with namespace binding information */ 
memset(&xrr,0,sizeof(GXLHXRR)); 
xrr.XRR_ENTRY_COUNT = 1; 
entry.XRR_ENTRY_ROOT_LEN = strlen(root_str); 
entry.XRR_ENTRY_ROOT_PTR = root_str; 
entry.XRR_ENTRY_NSURI_LEN = strlen(rootnsuri_str); 
entry.XRR_ENTRY_NSURI_PTR = rootnsuri_str; 
xrr.XRR_ENTRY = entry; 
rootTable = (void*)&xrr
/* Enable Root Restriction */
gxlpControl(PIMA, 
            GXLHXEC_CTL_RESTRICT_ROOT, 
            &rootTable, 
            rc, 
            rsn);
/* Parse the desired document fragments */
gxlpParse(PIMA, 
          option_flags, 
          &inbuf, 
          &inbuf_left, 
          &outbuf, 
          &outbuf_left, 
          &rc, 
          &rsn); 
/* Disable document fragment parsing */ 
xrr.XRR_ENTRY_COUNT = 0; 
gxlpControl(PIMA, 
            GXLHXEC_CTL_RESTRICT_ROOT, 
            &rootTable, 
            &rc, 
            &rsn);