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.
- 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.
- 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.
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.
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.
- 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.
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 |