GXLGST31 (GXLGST64) — get memory

Description

This service allocates an area of memory of the size requested by the z/OS XML parser. The z/OS XML parser requests memory in large quantities and manages sub-allocations of this memory within the parser.

Performance Implications

There are no performance implications.

Syntax

call gxlgst31,(sys_svc_parm,
              memory_addr,
              memory_len,
              exit_diag_code,
              return_code,
              reason_code)

Parameters

sys_svc_parm

Supplied parameter

Type:: Address
Length:: Fullword (Doubleword)

The address of the system service parameter (or zero) that was passed to the z/OS XML parser at initialization time.

memory_addr

Returned parameter

Type:: Address
Length:: Fullword (Doubleword)

The address of a fullword (doubleword) where the memory allocation exit should store the address of the allocated memory. If the caller wants to terminate the parse, then it should set a nonzero return code.

memory_len

Supplied and Returned parameter

Type:: Integer
Length:: Fullword (Doubleword)

A fullword that contains the length of the memory area requested by the z/OS XML parser. The exit is allowed to return an area of greater size and set this parameter to the length returned.

exit_diag_code

Returned parameter

Type:: Integer
Length:: Fullword (Fullword)

The name of a fullword where the exit stores any diagnostic information (usually a reason code). This is stored in the diagnostic area and made available on the GXL1CTL (GXL4CTL) call.

return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the exit service stores the return code.

reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the exit service stores the reason code.

Return and Reason Codes:

The z/OS XML parser uses the convention that the exit will provide a return code value of zero when successful. Any nonzero value indicates failure. If a nonzero return code is provided by the exit, the z/OS XML parser does not look at the reason code. Instead, the z/OS XML parser saves the reason code, along with the return code and the diagnostic code, in the extended diagnostic area so that the caller of the z/OS XML parser has access to it by calling GXL1CTL (GXL4CTL). The z/OS XML parser will provide return and reason codes to the caller in the event of a failure by the exit, or if the parser detects a problem with the storage returned from the exit.

For reason code descriptions, see Reason codes listed by value.

Example

For an example using this exit service, see GXLEGTM (GXLGST example). These examples are located in SYS1.SAMPLIB .

Default Implementation

If the exit is not provided, then 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.

The CONTROL setting will be AUTH for authorized callers. This prevents the storage from being unallocated by an unauthorized caller in the same address space. The storage will be allocated in the caller's key.