System-level name/token pair

A system-level name/token pair contains data that is shared among programs that run in different address spaces in the same system.

Figure 1 shows the system-level name/token pair in a multiple address space environment.

Figure 1. Using the System Level in a Multiple Address Space Environment

In Figure 1:

TASK 1 initially creates a system-level name/token pair in ADDRESS SPACE 1 using the IEANTCR callable service.
Even though TASKS 2, 3, and 4 reside in different address spaces, they can retrieve the system-level name/token pair using the IEANTRT callable service.

System-level name/token pairs are owned by the job step task of the home address space of the task or SRB that created the pair. System-level pairs are deleted when the owning job step task terminates. However, the IEANTCR callable service provides an option that allows the system-level name/token pair to exist after the owning job step task terminates. This option, available through the persist_option parameter on the IEANTCR callable service, is helpful when a program is abnormally terminated and must be restarted. Upon restart, the program can check what data is stored in the name/token pair so the program can free or reuse the program storage.

If the persist option is specified as zero when the system-level name/token pair is created, the pair is deleted when the job step task in the home address space terminates. If the persist option is specified as a one, the pair is not deleted when the job step task in the home address space terminates. However, even if the persist option is specified as a one, the pair will be deleted by the system if the system itself fails and is started again.

If there is not sufficient storage in the system-level name/token pool to permit creation of a new system-level name/token pair, the system obtains additional storage. The system does not release the storage when the pair is deleted. Instead, the system holds the storage for the duration of the IPL, reserving the storage for new system-level name/token pairs. If you create many new system-level name/token pairs without deleting previously-created pairs, a potentially serious storage shortage could result. For this reason, use system-level name/token pairs sparingly.