Cross-memory facilities CRAM and M204XSVC

CRAM and M204XSVC are the main facilities used by Model 204 to access z/OS cross-memory services. This page presents an overview of these facilities.

CRAM

The Cross-Region Access Method (CRAM) allows a program running in one mainframe region to communicate with a version of Model 204 running in a different region on the same CPU. CRAM is used by:

IODEV=11 (CICS and TSO full screen threads)
IODEV=23 (IFAM2/IFSTRT threads)
IODEV=29 (IFAM2/IFDIAL, line-at-a-time threads)

If any CRAM-dependent connections are defined to an Online (any of the above IODEV specifications), the Online must be able to load the CRAM IGCLM244 module: CRAMLIB (the default CRAM load library as of Model 204 version 7.5) must be part of the Online job's STEPLIB concatenation, or IGCLM244 must be moved into the Online job's designated STEPLIB library.

The overview of CRAM on this page is a supplement to the considerable additional CRAM information on these pages:

Two CRAM types

For many years, CRAM functionality relied on operating-system SVC calls. Now referred to as CRAM-SVC, this approach is deprecated as of version 7.5 of Model 204. The more recent CRAM alternative, CRAM-XDM, uses z/OS cross memory services to move pages from one address space to another in one instruction, providing much better performance than CRAM-SVC.

Note: For a detailed description of the CRAM-XDM performance benefits, see CRAM-XDM performance versus CRAM-SVC.

Both types of CRAM can coexist: a Model 204 site might use a combination of both types for testing and production purposes. However, a given address space can use only one method. All channels within the Online address space can use CRAM-XDM or CRAM-SVC, but not both. Despite this compatibility, CRAM-XDM is now the recommended option, and no CRAM-SVC installation job or instructions are offered after Model 204 version 7.4.

If both CRAM types are installed at a site, and CRAM threads are defined (the IODEV values mentioned in the previous section), the CRAM type you invoke is determined by the XMEMOPT parameter value you specify: the XMEMOPT X'80' bit calls CRAM-XDM; absent the X'80' bit, any other non-zero XMEMOPT value calls CRAM-SVC.

CRAM-XDM

CRAM-XDM uses z/OS cross memory services to move pages from one address space to another in one instruction. It initializes a single cross-memory environment, M204XDM, that is shared among all Model 204 Onlines. The M204XDM job is the master XDM job; it must be submitted before the Online jobs that might use that XDM.

XDM (cross-region data mover) is an address space that executes the M204XDM module. It runs separate from the Online module, and it runs APF-authorized in order to run non-swappable and non-cancellable. It calls M204XSVC, described further below, to initialize the cross-memory environment for the Online.

XDM always loads the M204XCSA, M204XCRM, and M204XSVC modules from its JOBLIB or STEPLIB. These modules are described further in the next section. XDM does not load the IGCLM244 module; it gets the CRAM z/OS subsystem name from the M204XDM job card as a PARM parameter.

For convenience, XDM initially puts messages like the following into the JES log:

IEF403I QATCM77P - STARTED - TIME=09.20.14 M204XSVC 7.7.0D 03/02/16 LOADED AT AF302478 M204XCRM 7.7.0D 04/06/16 LOADED AT AF302000 M204XCSA 7.7.0D 04/06/16 LOADED AT 2BE16758

The XDM address space is largely a repository for executable shared code. Once active, XDM does nothing unless a MONITOR or EOJ command is issued. Except for these two commands, XDM cannot abend, because it does no work. All activity is run in the XDM address space on behalf of the calling address space, with CPU being charged to the TCB of the caller (client or server).

XDM allows more than one Online to use the same subsystem name. It keeps a table of all Onlines that are connected, along with their channel names.

For more information about bringing up and working with XDM, see Managing CRAM-XDM.

The XDM load modules

M204XSVC is used to establish the cross-memory control block for calls within the address space. This control block contains the PC call tables. M204XSVC is described further in the M204XSVC section.
M204XCSA is loaded and moved into CSA common storage. It handles opens and closes from the calling address space. It also handles callers that are swappable. The CSA is a part of the common area in z/OS that typically contains data that is referenced by multiple address spaces, thus enabling communication among them.
M204XCRM handles cross-region communication between non-swappable callers.
IGCLM244 is linked into the Online and CRAM load libraries and loaded by the caller (client or server). All CRAM calls enter through this module.
The location of the CRAM control blocks is identified by its z/OS secondary subsystem name (SSN). Initially provided in the CRAM installation JCL (the value of CRMSSN), the SSN value is found in the CRAMGEN macro at the end of the IGCLM244 module. Assembled as a constant, the SSN is then used, for example, by a BATCH2 job to ensure that it connects to the desired M204XDM job, and from there, that it connects to the desired Online job. Each of those jobs has also loaded a copy of IGCLM244 into its address space. The Model 204 system parameter XDMSSN lets you override the SSN that was associated with CRAM-XDM at installation.

Once connected, IGCLM244 resolves writes and reads into PCs (program calls) into M204XCRM (or M204XCSA, depending on swappability), and communication occurs.

CRAM-SVC

CRAM-SVC is CRAM functionality that relies on SVC calls. The information about this now-deprecated functionality is provided for historical purposes and for those sites that still have CRAM-SVC installed.

CRAM-SVC moves data by copying it first to common storage, posting the other side, and then letting the other side copy it. This method is less efficient than CRAM-XDM, which uses z/OS cross memory services.

For more information about working with CRAM-SVC, see Using CRAM on a z/OS operating system.

Component modules

These are the CRAM-SVC component modules:

The CR00MXA object module is the CRAM SVC for z/OS, and all CRAM SVC calls actually invoke CR00MXA (linked as load module IGC00nnx, where nnx is the the assigned SVC number). This module contains CRAM read/write logic, flow of control, and open/close code. It also coordinates inter-region waiting and data transfer.
The following CRAM-SVC object modules are the callers.
CRLMMXA (z/OS); linked as load module IGC01nnx and as duplicate load module IGCLM244.
IGCLM244 remains in a load library as the resident load module for CRAM, while IGC01nnx is added to the proper system library for inclusion into PLPA storage and use by the IGC00nnx module.

IGCLM244 is also used to locate the CRAM SVC. The SVC number is assembled as a constant and found in the CRAMGEN macro at the end of the IGCLM244 module. If CRAM is installed without an SVC, the SVC constant in the IGCLM244 assembly is set to zero.

CRAM-XDM also uses CRLMMXA/IGCLM244, as described above in The XDM load modules.
CRLMXPCC (CMS).

Link Pack Area storage

Type 4 SVC load modules such as the CRAM-SVC modules must reside in the z/OS Link Pack Area (LPA). The LPA is divided into three sections:

Pageable Link Pack Area (PLPA)
Modified Link Pack Area (MLPA)
Fixed Link Pack Area (FLPA)

Pageable Link Pack Area

The PLPA is an area of virtual storage that contains a copy of every module from the LPALST, and a directory listing each module. During an IPL with the Create Link Pack Area (CLPA) option, the control program copies all the modules from LPALST into a special paging data set. Subsequent IPLs without the CLPA option do not reinitialize this special paging data set, thus reducing the time required for IPL.

Additional considerations that apply to performance are:

Locating a Type 4 SVC load module
Type 4 SVC load modules are most frequently located in the PLPA. A module in the PLPA can be located by a hashed search of the PLPA directory.

When a PLPA module is found with a hashed search, a Contents Directory Entry (CDE) is created in fixed storage. The CDE contains the module name, virtual storage address, link editor attributes, and use count. Page faulting is likely to occur in systems having high paging loads.
Minimizing page faults
- A program fetch operation that brings in an entire module may be more efficient than allowing page fault processing routines to read the requested module from the PLPA paging data set into real storage.
- Page faults occur when a PLPA module is referenced while it is not in real storage. Two page faults can be generated if a module crosses a page boundary.
- Placing all the modules for a specific Type 4 SVC on the same page of virtual storage can reduce page faulting. In this case, a reference to one module automatically brings other modules into real storage.
- System paging rates can be reduced by controlling the allocation of virtual storage in the PLPA through the SYS1.PARMLIB member IEAPAK00. IEAPAK00 lists one or more groups of modules. Each group is started on a virtual storage page boundary with the modules loaded contiguously in the listed order.
- Using the z/OS Subsystem facility or placing the IGCLM244 module in the Fixed Link Pack Area avoids page faults that can occur when the PLPA page is needed by another module.
  When a PLPA page is needed by another module, the old page is not saved. If the old page is needed again, it is reloaded. In instances where the Common Service Area (CSA) address is stored in IGCLM244 and IGCLM244 is stored in the PLPA, the address is lost if that page of the PLPA is taken for another purpose. Using the z/OS Subsystem facility, where the CSA address is kept with the Subsystem entry, avoids this problem.

Modified Link Pack Area

The MLPA is an area of virtual storage that contains copies of LPA modules for testing without reference to the PLPA. A module in the MLPA temporarily replaces the version of the module contained in the PLPA.

The MLPA is constructed on a page boundary at every IPL, with or without the CLPA option. Modules placed in the MLPA for the duration of a current IPL are listed in the SYS1.PARMLIB member IEALPAnnn, where nnn corresponds to the specified MLPA=nnn parameter. The control program loads each module, in the order listed in IEALPAnnn, from its library into the MLPA and creates a CDE. CDEs for MLPA modules are chained after the CDEs created for PLPA.

The following consideration applies:

Page faults can occur when MLPA modules are referenced. Unlike PLPA modules, IEAPAK00 cannot be used to minimize page faults.

Fixed Link Pack Area

The FLPA is an area of real storage that contains copies of selected modules. During an IPL the control program loads the modules listed in the SYS1.PARMLIB member IEAFInnn, where nnn corresponds to the specified FIX=nnn parameter, into the FLPA and creates a CDE. CDEs for FLPA modules are chained after the CDEs created for PLPA and before those created by IEALPAnnn (MLPA).

The following considerations apply:

Because the FLPA is an area of real storage, page faults do not occur when FLPA modules are referenced.
Performance is better when IGCLM244 and the SVC modules are placed in the FLPA, but the benefit from moving IGCLM244 there is negligible, and moving IGCLM244 is no longer recommended.
IGC00nnx must be placed in the FLPA, because the XMPOST routine must be page fixed.

SVC load module names

When using a Type 4 or Type 3 SVC and linking an SVC into the Link Pack Area, the SVC load module name is derived from the SVC number. The SVC name conversion is performed automatically by the Model 204 CRAM and M204XSVC installation jobs by setting parameters in those jobs to the assigned SVC number.

The format for the SVC load module name is:

IGC0Nnnx

Where:

N is a number, 0 or 1, that identifies the load module.
nn are the first two digits of the site-determined SVC number.
x is derived from the last digit of the SVC number, as follows:
Last digit: 0 1 2 3 4 5 6 7 8 9 x value: { A B C D E F G H I

SVC number values may be between 200 and 250 (or NOSVC for an SVC-less installation). Examples of derived names follow:

SVC number	SVC load module name
SVC244	IGC0024D
SVC240	IGC0024{

M204XSVC

The M204XSVC (Model 204 cross-memory services) object module supports cross-memory connections for an Online. It creates a control block that contains addresses of other control blocks and routines needed to execute program calls within the Model 204 address space.

Features supported

CRAM-XDM loads M204XSVC into its storage from the CRAMLIB load library to initialize the XDM environment. During Online initialization, M204XSVC sets up a program call environment for its calls for the various Model 204 authorized services that it supports in addition to CRAM-XDM, including:

IOS Branch Entry (including zIIP processing and ATB buffer pool buffers)
Timer PC
UL/DB2

Included and linked, with or without an SVC

M204XSVC is included (by default, as of Model 204 7.5) in the Online, IFAM1, and IFAM4 load modules. M204XSVC is linked by default into CRAMLIB, the CRAM load library. As described in The XDM load modules above, M204XSVC works with the M204XSCA, M204XCRM, and IGCLM244 modules to provide CRAM-XDM. It works without those modules to support the non-CRAM features listed below.

By default as of Model 204 7.5, the M204XSVC module is installed without an SVC. It supports the inline execution of cross-memory code (executing one instruction after another without the overhead of branching to the operating system) to improve performance.

The default installation assumes the Online and CRAM-XDM load libraries are APF-authorized. If these libraries are not APF-authorized, a site must install M204SVC as an SVC if it wants to use any of these features (which are enabled by the XMEMOPT parameter values in CCAIN):

CRAM-XDM
IOS Branch Entry (including zIIP processing and ATB buffer pool buffers)
Timer PC
UL/DB2

Although a job to install M204XSVC as an SVC is no longer part of Model 204 installation after Model 204 version 7.4, a 7.5 or higher site might have installed an M204XSVC SVC (by copying the more recent M204XSVC and renaming it as IGC002nnx with a standard link job, or by using a previous version of the M204XSVC installation job). Such an older M204XSVC SVC is supported in source in Model 204 7.7 and higher, and it is supported by maintenance (zap 76Z043) in version 7.6.

At a site with such an M204XSVC SVC, if a non-SVC version of the M204XSVC module is linked into the Online (and the Online is APF authorized), that non-SVC version is used to initialize the XDM environment. Otherwise, if the INCLUDEs for M204XSVC are removed from the Online and IFAM link jobs, the M204XSVC SVC is called (if XMEMSVC is set). Once established, M204XSVC invokes routines by using PC instructions, and its only actual SVC call might be at initialization.