longpelaexpertise.com.au/ezine/CrossMemoryBeginners.php?ezinemode=printfriend

LongEx Mainframe Quarterly - May 2010

technical: Cross Memory Communications for Beginners

One of the strengths of z/OS is its concept of address spaces. Every process (or address space) has its own storage, and believes that it has the entire z/OS to itself. Separating tasks into address spaces means that a task in one address space cannot access data or affect (crash) a task in another.

However there are times when a task in one address space needs to access data, or even run a program, in another address space. In this article, we look at the options for people new to cross memory communications.

1. SRB

In the early days of z/OS (or MVS, as it was called then), the only way to access storage or run a program in a different address space was to use an SRB (Service Request Block) routine. The SRB actually refers to the control block that holds information on the routine to be run.

SRBs are special beasts - they're not normal tasks. They operate outside the normal TCB-RB control block chain. They are aligned either with the ASCB (local SRB) or the master scheduler (global SRB). This means that they:

Always run in supervisor state.
Cannot call any SVCs except ABEND (but can use branch entry forms of some macros).
Cannot be interrupted except for a page fault or unavailable lock. This means that they can't WAIT.
Can run in cross memory and AR mode (we talk more about these shortly).
Can issue a PC, or schedule another SRB.
Can be very dangerous in the wrong hands.

Here's how they work:

The caller builds a routine to run as an SRB and stores it in CSA.
The caller creates and populates an SRB control block in CSA (not required if using IEAMSCHD).
The caller schedules the SRB using SCHEDULE or IEAMSCHD.
If the caller wants to wait for the SRB, it WAITs on an ECB in CSA.
The SRB runs in the remote address space.
If the caller is waiting, the SRB performs a cross-memory POST when done.

The SRB routine and ECB are put into CSA so they are addressable in the target address space.

Using the more modern IEAMSCHD macro is easier than SCHEDULE. You can include an automatic wait if required, and there's no need to manually build the SRB. You also have more control over the SRBs environment.

SRBs are intended for very short units of work - long running SRBs can 'freeze' an address space. SRBs can be scheduled in cross memory mode (which we talk about a bit later). Although SRBs are often used with existing system, few new ones are being written today. Most of the features can be performed with synchronous cross memory and PCs - with more control, and less scope for disaster.

Advantages:

The remote address space doesn't have to be swapped in.
The SRB can do whatever it likes in the remote address space.

Disadvantages:

Tricky to create.
Because the SRB is so powerful, it has a lot of scope for destroying not only address spaces, but the entire z/OS image.
SRBs require strong error handling and recovery.
The calling program cannot access memory directly. It must rely on the SRB routine to pass the memory back and forth.

2. Basic Cross Memory Mode

Cross memory mode was introduced after the SRB, and allowed a program to access memory in another address space before the invention of access registers and PC instructions. To use this, the caller:

Sets AXSET=1 to allow access to any address space.
Uses SSAR to set the secondary space to the remote address space.
Uses MVCS and MVCP to move data between address spaces.
Uses SSAR to set secondary space back.
Sets AXSET=0.

This is not very clearly documented by IBM, but works fine when the target address space is non-swappable. If the target address space is swapped out, a S0C4 abend will occur.

Advantages

Easy to understand – no complicated synchronous cross memory.
Easy to code.

Disadvantages

Remote address space must be non-swappable.
If another task has set AXSET to something other than 1 or 0, you can't then set it to 1. You're locked out.
Cannot access memory in more than two address spaces (primary and secondary) at the same time.
Caller must be APF authorised.
Must use MVCP and MVCS to move data between the primary and secondary address spaces - cannot use other instructions like CLC, MVST, MVCL to address anything in the secondary address space.

Sample Code

In this sample routine, the ASID of the target (remote) address space is already stored in the RMTASID word.

* ---------------------------------------------------
* Setup everything
* ---------------------------------------------------
        XC   RMTASN,RMTASN
        LH   R1,RMTASID     Get remote ASID
        ST   R1,REQASN+2    Save it
        XR   R2,R2
        ESAR R2             Get Our ASN
        ST   R2,HOMEASN     Save Our ASN
		
* ---------------------------------------------------
* Get into cross memory mode
* ---------------------------------------------------
        MODESET KEY=ZERO,MODE=PROB  Into key 0
        LA   R2,1
        AXSET AX=(R2)       Auth index = 1 (all)
        L    R2,RMTASN
        SSAR R2             Into Cross memory mode

* ---------------------------------------------------
* Move storage
* ---------------------------------------------------
    (use MVCS and MVCP for copying storage)

* ---------------------------------------------------
* Get out of cross memory mode
* ---------------------------------------------------
        MODESET KEY=NZERO,MODE=PROB Back to key 8
        L    R2,OURASN
        SSAR R2  
        XR   R2,R2  
        AXSET AX=(R2)       Auth index = 0 (none)

* ---------------------------------------------------
* Back to caller
* ---------------------------------------------------
        BR   R14

* ---------------------------------------------------
* Storage
* ---------------------------------------------------
HOMEASN DS   F              Home ASN
RMTASN  DS   F              Remote ASN

The basic cross memory facility introduced the idea of home, primary and secondary address spaces:

Home - where the program was called from, or where the program's TCB is.
Primary - where the instructions for the program are, and the default area where the data is.
Secondary - a second address space where data can be accessed.

In the above example, the instruction SSAR is used to set the secondary address space, and ESAR to get it. EPAR can be used to get the primary address space (but there's no instruction to set it).

Many macros and services cannot be called in cross memory mode. Check the relevant documentation before using them.

The use of basic cross memory services is not recommended - Access Register mode is a far better option.

3. Access Register Mode

With access registers (ARs), cross memory became more stylish. For every general register (GPR), there is a corresponding AR. So AR3 is paired with GPR3. In AR mode, the AR can be used to determine the address space that the corresponding GPR refers to. To use this, the caller:

Gets the access list entry token (ALET) for the remote address space.
Puts the ALET into the access register (say AR3).
Sets AR mode (SAC 512 instruction).
Uses the corresponding general register when referring to memory in the remote address space (GPR3 in this case).
Gets out of AR mode (SAC 0) when done.
Clears the AR.

Advantages

Remote address space doesn't have to be swapped in.
Can call SVCs.
Can communicate with up to 16 address spaces at the same time.
Have access to all instructions (like CLC and MVI) to access remote address space memory. Do not need to move storage from one address space to another to reference it.

Code Example

In this example, the address of the ASSB for the target (remote) address space is already held in the RMTASSB word (this can be found in the ASCBASSB field of the target ASCB), and RMTADDR holds the address in the target address space of 50 bytes of data.

* -----------------------------------------------------
* Setup environment
* -----------------------------------------------------
        LAM  R0,R15,=16F'0'   Set all ARs to zero

* -----------------------------------------------------
* Get ALET of remote address space
* -----------------------------------------------------
        USING ASSB,R12
        L    R12,RMTASSB      Load remote ASSB addr
        ALESERV ADD,STOKEN=ASSBSTKN,ALET=RMTALET,CHKEAX=NO
        DROP R12
        LTR  R15,R15          Check return code
        BNZ  ERROR            If unsuccessful skip out

* -----------------------------------------------------
* Copy first word and next 50 bytes from remote
* address space
* -----------------------------------------------------
        LAM  R3,R3,RMTALET    Store ALET in AR3
        SAC  512              Into AR mode
        SYSSTATE ASCENV=AR    Tell macros are in AR mode
        L    R3,RMTADDR       Store address in GPR3
        L    R4,0(,R3)        Move first word into R4
        MVC  AREA1(50),4(R3)  Move 50 bytes from rmt a/s
        SAC  0                Out of AR mode
        SYSSTATE ASCENV=P     Tell macros out of AR mode

* -----------------------------------------------------
* Cleanup access registers and ALET
* -----------------------------------------------------
        LAM  R3,R3,=F'0'      Clear AR3
        ALESERV DELETE,ALET=RMTALET,CHKEAX=NO

Notes:

In this example, the access registers are set to zero at the beginning. This is a good habit to get in to, so there's no chance of accidentally addressing a different address space.
Always use the SYSSTATE macro when going into and out of AR mode, so any macros called will be expanded correctly. Some macros have a different expansion, depending on the addressing mode.
You don't have to use the ALESERV to get the ALET. There are three special ALETs:

0 = Primary Address Space
1 = Secondary Address Space
2 = Home Address Space

Many macros and services cannot be called in AR mode. Check the relevant documentation before using them.
Access Registers only affect the base register for all instructions. In the above example, the first word from the area in the remote address space is loaded into R4. We used the instruction
```
      L R4,0(,R3)
```
R3 is the base register. If we had used
```
      L R4,0(R3)
```
(with R3 as the index register) we would have moved the word from the primary address space, not the target address space.

4. Synchronous Cross Memory

This is the Program Call (PC) routine. A service provider creates a routine, and stores it in memory. The provider then sets up a PC routine number pointing to this routine, authorisation (who can access it - which address space, authorised or non-authorised etc.) and the environment.

z/OS provides some 'hard-wired' PCs with fixed PC numbers. For the rest of us, we need to setup PC routines with standard macros provided by z/OS. The service provider must:

Define a PC routine and environment using ETDEF.
Create an entry table using ETCRE.
Connect the PC routine to the linkage table for the client address space using a linkage index (LX) - either a system linkage (all address spaces can use it) or a non-system LX (specific address spaces can use it).
Provide the user with a PC number (obtained by concatenating the LX and the entry table index - EX). This cannot be known before the PC is created. The provider must also provide a way for callers to obtain this number: by storing this number in a control block accessible to the calling program (almost always in CSA) or using a Name/Token pair.
Create correct PT and SSAR authority for the PC routine using the ATSET and AXSET macros.

The caller must:

Obtain the PC number of the routine (from the control block or Name/Token pair).
Setup any parameters to be passed to the PC routine.
Call the PC routine.

There are two types of PC routine:

Basic - The original PC routine. It receives control in Primary mode, and supervisor or problem state (but almost always supervisor state so the PCLINK macro can be used to save and restore the caller's environment). The PC routine must manually save and restore the caller's environment.
Stacking - The new kid on the block. It receives control in Primary or AR mode, and the system automatically saves the caller's environment.

Almost everyone uses stacking PC instructions.

Advantages

Client does not have to be APF authorised.
Can use cross memory and AR mode to access memory in different address spaces.
PC routine owner has a lot of control as to who can use the PC routine, and in which environment.
No interrupt when PC is called (unlike SVC).
PC routine is dynamically added and changed.
There is no way to bypass or update the PC using something similar to the SVCUPDTE or SVC Screen Facility.
PC routine can be called from users that cannot call an SVC (as there's no interrupt).
PC routines can call another PC routine.

The PC routine can provide a client with resources to access other address spaces and perform authorised services. PC routines are rapidly replacing SVC routines.

References

Article Modifications

The special ALET values in the original article were incorrect, and modified in Jun-2014. Thanks to Benjamin Dissen and Phil Smith III for letting us know

David Stephens