Managing memory resources

The z/OS XML parser processes a document using memory resources that are provided by the caller. This storage is passed from caller to z/OS XML parser in the form of a Parse Instance Memory Area (PIMA). This required data area is used by the z/OS XML parser to suballocate a call stack, control blocks, and the tables and trees that are used to hold assorted document-specific information for the document being parsed. The environment created by the z/OS XML parser in this memory area completely describes the context of a given document parse.

A memory allocation exit is supported by the z/OS XML parser so that the caller can provide a pair of allocation/deallocation services. The allocation service will be called by the z/OS XML parser in the event that a given document causes the z/OS XML parser to exhaust the PIMA. For performance reasons, it is best if the PIMA provided by the invoker is large enough that this exit is not used. However, the exit gives the z/OS XML parser a means to complete processing of a document in the event that the memory area provided at initialization time is too small. This exit is only used to extend the PIMA, and is not used in any way to manage input or output buffers.

The deallocation service will be called by the z/OS XML parser to free the memory extension created by the allocation service. The deallocation service will never free the original PIMA storage.

For callers that do not provide a memory allocation exit, the z/OS XML parser provides default routines to allocate and free memory. The z/OS XML parser also provides an option at initialization time allowing the caller to specify how the z/OS XML parser's default routine allocates memory. This feature should be specified when PIMAs are used on multiple tasks, in order to prevent task termination from causing storage extents to be freed before the z/OS XML parser is done using them. Normally, z/OS XML parser will allocate memory at the task level. However, when the feature is specified, the z/OS XML parser will allocate memory at the Job Step Task (JST) level instead.

In both cases, the caller is assuming the responsibility to call GXL1TRM (GXL4TRM) in the event the z/OS XML parser abends and the caller's recovery gets control.

When no memory allocation exit is provided, the subpool used will be as follows:

If running in SRB or cross memory mode, subpool 129 will be used. This is JST related and cannot be freed by unauthorized callers. The key will be the same as the key at the time the z/OS XML parser is invoked.
If running in task mode (PSATOLD not zero), with PRIMARY=SECONDARY=HOME, then the subpool chosen will depend on the authorization state of the caller and on the specification of the XEC_FEAT_JST_OWNS_STORAGE feature on the GXL1INI (GXL4INI) call. If the caller is running in key 0-7 or supervisor state, they will be considered authorized.
- Authorized and JST requested — subpool 129
- Authorized and JST not requested — subpool 229
- Unauthorized and JST requested — subpool 131
- Unauthorized and JST not requested — subpool 0
  Note: If running on a subtask which is sharing subpool 0, then this storage will be owned by the task that owns subpool 0.

These choices of subpool will eliminate the possibility of the z/OS XML parser running in an authorized state while using problem key storage which could be freed and reallocated.