Examples of establishing addressability to data spaces

The best way to describe how to add an access list entry is through examples. This section contains three examples:

Example 1 sets up addressability to a data space, using the DU-AL. The example continues with a program passing a STOKEN to another program so that both programs can access the data space.
Example 2 sets up addressability to a data space, using the PASN-AL. This example continues with a program passing an ALET to another program so that both programs can access the data space.
Example 3 shows how to set up addressability so that two programs in different address spaces can access the same data space.

In these examples, programs share their data spaces with programs running under work units other than their own.

The examples all involve adding entries for data spaces. The reason the examples are not of address spaces is because of the additional decision that you have to make about EAX-authority when you add entries for address spaces to access lists. Getting EAX-authority is described in EAX-authority to an address space. Turn to that section after you understand how to add entries for data spaces.

Example 1: Getting Addressability Through a DU-AL:

Consider that a supervisor state program named PGM1 created a data space and received a STOKEN from DSPSERV. To add the entry to the DU-AL, PGM1 issues:

        ALESERV ADD,STOKEN=STOKDS1,ALET=ALETDS1,AL=WORKUNIT
        .
ALETDS1 DS F
STOKDS1 DS CL8

ALESERV accepts the STOKEN, adds an entry to the DU-AL and returns an ALET at location ALETDS1. Figure 1 shows PGM1 with the entry for DS1 on its DU-AL. It shows the STOKEN and the ALET.

Figure 1. Example 1: Adding an entry to a DU-AL

Consider that PGM2, also in supervisor state, and running under a TCB different from PGM1's TCB, would also like to have access to DS1. PGM1 passes PGM2 the STOKEN for DS1. PGM2 then uses the ALESERV ADD macro to obtain the ALET and add the entry. Figure 2 shows PGM2 with addressability to DS1.

Figure 2. Example 1: Sharing a data space through DU-ALs

Note: A problem state program with PSW key 8 - F can add entries to an access list only for a data space that the program created or owns.

Example 2: Getting Addressability Through a PASN-AL:

In Figure 3, consider that PROG1, adds an entry for a data space to the PASN-AL. PROG1 issues the following macro:

     ALESERV ADD,STOKEN=STOKDS2,ALET=ALETDS2,AL=PASN
     .
ALETDS2 DS F
STOKDS2 DS CL8

ALESERV accepts the STOKEN, adds an entry to the PASN-AL, and returns an ALET at location ALETDS2. Figure 3 shows PROG1 with the PASN-AL entry for DS2.

Figure 3. Example 2: Adding an entry to a PASN-AL

Note: A problem state program with PSW key 8-F can add entries to the PASN-AL only for the type of data space called SCOPE=SINGLE.

Consider that PROG2 (either in problem or supervisor state and running under a TCB different from PROG1's) would like to have access to DS2. In this case, both PROG1 and PROG2, because they run in the same address space, share the same PASN-AL. PROG2 does not have to add an entry to its PASN-AL; the entry is already there. PROG1 passes the ALET to PROG2. Figure 4 shows that PROG2 has the ALET for DS2 and, therefore, has addressability to DS2 through its PASN-AL.

Figure 4. Example 2: Sharing a data space through the PASN-AL

In a similar way, any supervisor state or problem state program that runs in AS1 and has the ALET for DS2 can access DS2.

The SCOPE parameter on DSPSERV determines how the creating program can share the data space. For more information on the SCOPE parameter, see Scope=single, scope=all, and scope=common data spaces.

Example 3: Passing ALETs Across Address Spaces:

Referring to Figure 4, consider that PROG1 wants to allow a program in another address space (whose home address space is different from PROG1's) to access data in DS2. Figure 5 shows that PROG1 passes the STOKEN for DS2 to PROG2, a supervisor state program in AS2. PROG2 uses the ALESERV macro to add the entry to its DU-AL. PROG2 also could have added the entry to its PASN-AL.

Figure 5. Example 3: Sharing data spaces between two address spaces

Remember that getting addressability to an address space is similar to getting addressability to a data space, with one difference: when you attempt to add an entry for an address space to an access list, ALESERV allows you to require that programs that access the address space through the entry have EAX-authority to the address space.