GXLHXEC_CTL_FEAT

Description

This indicates that the caller wishes to re-initialize the z/OS® XML parser, as with the reset-and-finish function above, and in addition, that the caller wishes to reset some of the feature flags used during the parse.

Note: The following feature flags are not supported by this service:

GXLHXEC_FEAT_JST_OWNS_STORAGE
GXLHXEC_FEAT_RECOVERY
GXLHXEC_FEAT_VALIDATE
GXLHXEC_FEAT_SCHEMA_DISCOVERY
GXLHXEC_FEAT_XDBX_INPUT

Make sure that these feature flags are turned to the OFF state before calling this service to set the feature flags. If these features need to be changed (for example, if switching between validating and non-validating parses), the parse instance must be terminated and re-initialized with the required feature settings.

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

ctl_data_p

Supplied and returned parameter

Type:: void *

This parameter must contain the address of a fullword (doubleword), which is mapped by header file gxlhxft.h. See gxlhxft.h (GXLYXFT) - mapping of the control feature input output area for more information on this header file.

The GXLHXFT_FEAT_FLAGS parameter is an input parameter to the API and contains the value of feature flags to be used in the subsequent parse. It is defined as follows:

GXLHXEC_FEAT_STRIP_COMMENTS: This effectively strips comments from the document by not returning any comments in the parsed data stream. Default: off.
GXLHXEC_FEAT_TOKENIZE_WHITESPACE: This sets the default token value for white space preceding markup in the root element to an explicit white space value. Default: off – white space is returned as character data.
GXLHXEC_FEAT_CDATA_AS_CHARDATA: This returns CDATA in records with a CHARDATA token type. The content of these records may contain text that would normally have to be escaped to avoid being handled as markup. Default: off.
GXLHXEC_FEAT_SOURCE_OFFSETS: This feature is used to include records in the parsed data stream which contain offsets to the corresponding structures in the input document. Default: off.
GXLHXEC_FEAT_FULL_END: This feature is used to expand the end tags to include the local name, prefix and URI corresponding to the qname on the end tag. Default: off.

If none of the features are required, pass the name of a fullword field containing zero. Do not construct a parameter list with a zero pointer in it.

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;
int lastRetVal, lastRC, lastRSN;
GXLHXFT ft;                                 
ft.XFT_FEAT_FLAGS=0;                        
void *pft = &ft;                             
lastRetVal = gxlpControl(PIMA,                                        
                         GXLHXEC_CTL_FEAT,                            
                         &pft,                                        
                         &lastRC,                                     
                         &lastRSN);