Freeing a private memory object

When your program no longer needs the memory object, it uses IARV64 DETACH to free (delete) the memory object. You can free memory objects that are related to each other through the user token defined on the IARV64 GETSTOR request. Additionally, all programs can use the following parameters:

MATCH=SINGLE,MEMOBJSTART frees a specific memory object, as identified by its origin address.
MATCH=USERTKN, USERTKN frees a related set of memory objects by providing the user token specified when the memory objects were created.
COND=YES makes the request conditional, but only when you also pass a user token. IBM® recommends you use COND to avoid having the program abend because it asked to free a memory object that doesn't exist.

Authorized programs can use additional parameters:

ALETVALUE frees all memory objects in the primary address space or the home address space.
OWNER=YES,TTOKEN frees only memory objects that are owned by a specified task.
OWNER=NO (without TTOKEN) frees memory objects regardless of which task owns them.

Three conditions to avoid when you try to free a memory object are:

Freeing a memory object that does not exist.
If you try to free a memory object that doesn't exist, the system abends your program.
Freeing a memory object that has a range of addresses PAGEFIXED.
If you try to free a memory object that has a range of addresses pagefixed, the system will abend and address space termination might follow. See the paragraph about task information in this section.
Freeing a memory object that has I/O in progress.

If you specify the COND=YES parameter, you must also specify a user token. In the recovery routine that gets control at an abend, you can try one of the following:

Unfix any fixed pages. If you can unfix the pages, you can try again to free the memory object.
Ignore the abend and leave the memory object in an unusable state.

As part of normal task termination, RSM frees the memory objects owned by the terminating task; if RSM determines that there are fixed pages in the memory object, the system issues a CALLRTM TYPE=MEMTERM request that results in address space termination. To avoid this MEMTERM, your recovery routine should try to terminate any active I/O into the memory object that your program created and free any pages that your program fixed.