Selecting storage persistence

To select the storage persistence, you must decide how long you require the storage. Before making these decisions, you need to understand what determines the persistence of a virtual storage area.

The level of persistence is determined by whether the storage is owned by a task, a job step task, an address space, or the system. When the owner terminates, the system releases the storage. In the subpool table in Table 1, the "owner" heading shows the owner of each subpool. The four categories are:

Task: The storage is owned by a task's TCB.
Job step: The storage is owned by a job step task's TCB.
Address space: The storage is owned by the address space in which the storage resides.
System: The storage is owned by the system; it is not associated with a particular task or address space.

Note: Storage ownership as it is discussed here is unrelated to the OWNER keyword on the STORAGE, GETMAIN, and CPOOL macros.

To understand how the system determines the ownership of task and job step owned storage, you need to understand the concept of the input TCB. The input TCB is the TCB whose address is specified either explicitly or by default on a request to obtain or free private storage. The system uses the input TCB to assign ownership of the storage being obtained or to determine the ownership of the storage being freed. Note that the system does not necessarily assign storage ownership to the input TCB:

For task owned storage: the owning TCB is the input TCB.
For job step owned storage: the owning TCB is the job step task TCB of the input TCB.

Note: The rules for task and job step owned storage ownership are different for shared subpools. For information about how the system assigns ownership for storage obtained from shared subpools, see Additional considerations.

Task owned storage: For task owned storage, the input TCB is determined by the macro used to obtain or free the storage, the parameters specified, the dispatchable unit mode of the caller, and the address space in which the storage is obtained (the target address space). If the calling program is running in SRB mode or obtaining storage in an address space other than the home address space, the system assigns the input TCB to be the TCB that owns the cross memory resources in the address space in which the storage is being obtained. The address of this TCB is stored in the ASCBXTCB field of the ASCB of that address space. Table 1 shows how the system determines the input TCB for task-owned private storage.

Table 1. How the System Determines the Input TCB for Task Owned Storage
Macro	Conditions	Input TCB	Event Causing Storage to be Freed
GETMAIN and FREEMAIN macros	If the caller specifies SVC entry	TCB of the currently active task, whose address is in PSATOLD	Currently active task terminates
GETMAIN and FREEMAIN macros	If the caller specifies local branch entry and specifies GPR 4 with a value of zero	TCB owning the cross-memory resources in the target address space, whose address is in ASCBXTCB	Task, whose TCB address is in ASCBXTCB, terminates
GETMAIN and FREEMAIN macros	If the caller specifies local branch entry and specifies GPR 4 with a non-zero value	TCB address specified by the caller in GPR 4	Task, whose TCB address is passed in GPR 4, terminates
STORAGE macro	If the caller is in task mode and the target address space is the home address space	TCB of the currently active task, whose address is in PSATOLD	Currently active task terminates
STORAGE macro	If the caller is in SRB mode or the target address space is not the home address space	TCB owning the cross-memory resources in the target address space, whose address is in ASCBXTCB	Task, whose TCB address is in ASCBXTCB, terminates
STORAGE macro	If the caller specifies the TCBADDR parameter	TCB specified by the caller with the TCBADDR parameter	Task whose TCB address is specified with the TCBADDR parameter terminates
CPOOL macro	If the caller omits the TCB parameter	TCB of the currently active task, whose address is in PSATOLD	Currently active task terminates
CPOOL macro	If the caller specifies the TCB parameter with a value of 0	TCB owning the cross-memory resources in the target address space, whose address is in ASCBXTCB	Task, whose TCB address is in ASCBXTCB, terminates
CPOOL macro	If the caller specifies the TCB parameter with a non-zero value	TCB specified by the caller with the TCB parameter	Task, whose TCB address is specified with the TCB parameter, terminates

Job step owned storage: For job step owned storage, the owning TCB is the job step task TCB of the input TCB. That is, the owning TCB is the job step task TCB of the TCB that would own the storage according to Table 1.

Figure 1 shows an example of a task structure within an address space, including the locations of the ASCBXTCB and TCBJSTCB fields. Note that the task structure within an address space can vary and this example only shows one of many different possibilities.

Figure 1. Task Structure Within an Address Space

Address space owned storage: Address space owned storage is private storage that is owned by the address space in which it resides. It is not associated with a task.

System owned storage: System owned storage persists until explicitly freed using the FREEMAIN macro, the STORAGE macro with the RELEASE parameter, or the CPOOL macro with the DELETE parameter. If an area of system owned storage is not freed, it remains allocated for the life of the IPL. System owned storage is not associated with a task or an address space. Common storage subpools are system owned. Private storage subpools are all task, job step task, or address space owned.

The important consideration in selecting the type of storage ownership is to ensure that the storage you obtain remains in existence for the required duration. Because the system automatically frees all non-system-owned storage when the owner terminates, you must ensure that storage ownership is assigned to an entity that will not terminate while the obtained storage area is still needed.

You should always ensure that storage explicitly obtained is explicitly freed. It is not a good programming practice to rely on the system to free storage for you, except in cases where there is no alternative.

Now that you understand the types of storage ownership and how storage ownership is assigned, use the following guidelines to help you determine the type of storage ownership you need:

If you require the storage only during your program's processing, use task owned storage.
If you require the storage to persist after your program has terminated but not after the owning job step task has terminated, use job step owned storage. For instance, it is necessary to have storage persist after your program has terminated if your program obtains storage that must be accessed by another task that will be running after your program terminates.
If you require the storage to persist for the life of the address space, use address space owned storage. This is necessary, for instance, if the storage must be available to job step tasks running later in the same address space.
If you require the storage to persist after the address space has terminated, use system owned storage (which is exclusively common storage). This is necessary, for instance, if the storage must be available permanently to all address spaces.

Table 2 lists the types of storage ownership and the circumstances under which each is appropriate.

Table 2. Choosing Storage Ownership
If you need the storage:	Storage should be owned by:
Only during your program's processing	Task
After your program terminates but not after the job step task has terminated	Job step
For the life of the address space but not after the address space has terminated	Address space
After the address space has terminated	System