Maintaining Information About the Callers of Your Subsystem

A common requirement for a subsystem is to maintain information specific to each of its callers. To accomplish this, a subsystem needs both:

A method of uniquely identifying each caller.
A work area to store information about each caller (or a place to store the address of a work area).

The subsystem affinity service solves both of these requirements. It allows a subsystem to store and retrieve data at the task control block (TCB) level, thus removing its dependence on information passed by callers.

Consider the following example: A subsystem provides service to many callers, and must also maintain use counts by caller. Each caller can be identified by the TCB that is associated with it.

The subsystem uses the subsystem affinity service to maintain a separate use count for each of its callers. For each caller, the subsystem affinity service provides the subsystem with a unique fullword entry, called a subsystem affinity entry.

Figure 1 shows how the subsystem uses a subsystem affinity entry for a particular caller, to hold a pointer to a work area. The subsystem records use counts in the work area. Because the subsystem affinity service allows each caller to be uniquely identified by the TCB that it runs under, the subsystem can track the use count for each of its callers.

Figure 1. Subsystem Affinity Service

Accessing the Subsystem Affinity Entry: To access the subsystem affinity entry for each of its callers, a subsystem needs to:

Invoke the verify subsystem function (SSI function code 15) through the IEFSSREQ macro to acquire its subsystem affinity index. See Verify Subsystem Function Call — SSI Function Code 15 for information on SSI function code 15.
Issue the SSAFF SET request to store data in the entry.

On subsequent invocations, the subsystem can issue the SSAFF OBTAIN request to retrieve the address of a work area from the entry.