gxlpInit — initialize the z/OS XML parser

Description

The gxlpInit callable service initializes the PIMA and records the addresses of the caller's system service routines (if any). The PIMA storage is divided into the areas that will be used by the z/OS XML parser to process the input buffer and produce the parsed data stream.

Performance Implications

The initialization of structures used by the z/OS XML parser in the PIMA is only done once per parse and is therefore unlikely to affect performance. The caller may choose to reuse the PIMA after each parse to eliminate the overhead of storage allocation and the page faults that occur when referencing new storage. In this case, a control operation is required to reset the necessary fields in the PIMA before parsing can continue. For more information on the control operation, see gxlpControl — perform a parser control function.

Syntax

int gxlpInit (void * PIMA,
              long PIMA_LEN,
              int ccsid,
              int feature_flags,
              GXLHXSV sys_svc_vector,
              void * sys_svc_parm,
              int * rc_p,
              int * rsn_p);

Parameters

PIMA

Pointer to Parse Instance Memory Area (PIMA).

Type:: void *

PIMA_Len

Length of PIMA

Type:: long

The name of an area containing the length of the Parse Instance Memory Area. This service validates the length of this area against a minimum length value. The minimum length of the PIMA depends on whether or not validation will be performed during the parse:

GXLHXEC_NVPARSE_MIN_PIMA_SIZE (non-validating)
GXLHXEC_VPARSE_MIN_PIMA_SIZE (validating)

ccsid

Supplied parameter

Type:: Integer

The Coded Character Set IDentifier (CCSID) that identifies the document’s character set. The CCSID value in this parameter will override any character set or encoding information contained in the XML declaration of the document. A set of CCSID constants for supported encodings has been declared in GXLYXEC. See Supported encodings for a full list of supported encodings.

feature_flags

Supplied parameter

Type:: Integer

The name of the area that contains an integer value representing one or more of the following z/OS XML parser features. OR these flags together as needed to enable features. Choose any of the following:

GXLHXEC_FEAT_CDATA_AS_CHARDATA - return 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.
GXLHXEC_FEAT_FULL_END - expand the end tags to include the local name, prefix and URI corresponding to the qname on the end tag.
GXLHXEC_FEAT_JST_OWNS_STORAGE - allocate storage as Job Step Task (JST) related instead of task related. See the Usage notes below for more information.
GXLHXEC_FEAT_RECOVERY - this option is used to turn on the recovery routine.
Note: Because the recovery routine is automatically enabled for Language Environment-C, this option is only meaningful when using the Metal C compiler option.
GXLHXEC_FEAT_SOURCE_OFFSETS - include records in the parsed data stream which contain offsets to the corresponding structures in the input document.
GXLHXEC_FEAT_STRIP_COMMENTS - effectively strip comments from the document by not returning any comments in the parsed data stream.
GXLHXEC_FEAT_TOKENIZE_WHITESPACE - set the default token value for white space preceeding markup within the context of the root element to an explicit white space value. Use this value in conjunction with the special xml:space attribute to determine how such white space gets classified.
GXLHXEC_FEAT_VALIDATE - perform validation while parsing. See Usage notes for details of parsing with validation.
GXLHXEC_FEAT_SCHEMA_DISCOVERY - report schema location information and allow for an OSR to be loaded once the information has been reported. GXLHXEC_FEAT_VALIDATE must also be enabled, otherwise gxlpInit will return an error. See Usage notes for more information on schema discovery. Default: off.
GXLHXEC_FEAT_XDBX_INPUT - indicates that the data presented to z/OS XML in the input buffer is in XDBX binary XML form, rather than conventional text. This feature requires that GXLHXEC_FEAT_VALIDATE is also set, and that the encoding specified in the CCSID parameter is UTF-8. See Usage notes for more information on XDBX input streams. Default: off.
GXLHXEC_FEAT_ALLOW_VECTOR - this enables the parser to use vector instructions. Default: off.

Note: By using the values of off (zero), W3C XML compliant output is generated. Turning on options GXLHXEC_FEAT_STRIP_COMMENTS and GXLHXEC_FEAT_CDATA_AS_CHARDATA will cause the output to vary from standard compliance.

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.

sys_svc_vector

Supplied parameter

Type:: GXLHXSV

The name of a structure containing a count of entries that follow and then a list of 31 (64) bit pointers to system service routines. The GXLHXSV member XSV_COUNT must have a value of 0 if no services are provided. For more details on usage, see Usage notes. For more information on exit routines, see the z/OS XML System Services exit interface chapter.

sys_svc_parm

Supplied parameter

Type:: void *

The name of the area which is passed to all system service exits. This provides for communication between the z/OS XML parser caller and its exit routines. Specify the name of a location containing 0 if no parameter is required for communication.

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.

Return and Reason Codes:

On return from a call to this service, register 15 will contain the return code. The return and reason code are both also set as output parameters. The value of the reason code is undefined when the return code has no associated reasons. Return and reason codes are defined in the header file gxlhxr.h (see gxlhxr.h (GXLYXR) - defines the return codes and reason codes). For reason code descriptions, also see Reason codes listed by value.

Example

#include <stdlib.h>
#include <gxlhxec.h>

void *  pima_p;
long    pima_l;
GXLHXSV sysServiceVec;
int     rc, rsn;

if (pima_p = malloc(GXLHXEC_MIN_PIMA_SIZE))
  { /* pima malloc succeeded */   
   pima_l = GXLHXEC_MIN_PIMA_SIZE;
   sysServiceVec.XSV_COUNT = 0;

gxlpInit(pima_p, pima_l,
      GXLHXEC_ENC_UTF_8,
      GXLHXEC_FEAT_STRIP_COMMENTS,
      sysServiceVec,
      NULL,
      &rc, &rsn);

  } /* pima malloc succeeded */

Usage notes

System service exit routines cannot get control in the C/C++ environment. Instead, they must be coded to the assembler interface.

Addresses passed in the system_service_vec parameter must point to the entry point of the exit being supplied. To obtain the entry point address of a function in 31-bit NOXPLINK DLL compiled module, refer to the FDCB structure in z/OS® Language Environment® Vendor Interfaces, SA22-7568. Otherwise, taking the address of the function will return the entry point address.

This callable service is a direct map to the callable service GXL1INI (GXL4INI). Refer to Usage notes of GXL1INI (GXL4INI) for additional usage information.