DCameron: /* Two CRAM types */

2019-02-26T15:02:58Z

Two CRAM types

← Older revision		Revision as of 15:02, 26 February 2019
Line 29:		Line 29:

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

JAL: add category

2018-04-20T19:25:24Z

add category

← Older revision		Revision as of 19:25, 20 April 2018
Line 257:		Line 257:

	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 <var>[[XMEMSVC parameter\|XMEMSVC]]</var> is set). Once established, M204XSVC invokes routines by using PC instructions, and its only actual SVC call might be at initialization.		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 <var>[[XMEMSVC parameter\|XMEMSVC]]</var> is set). Once established, M204XSVC invokes routines by using PC instructions, and its only actual SVC call might be at initialization.

			[[Category: Model 204 operational issues]]

JAL: Created page with "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. TOC ==CRAM== Th..."

2017-05-23T18:16:44Z

Created page with "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. __TOC__ ==CRAM== Th..."

New page

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.
__TOC__

==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:
<ul>
<li>IODEV=11 (CICS and TSO full screen threads)
<li>IODEV=23 (IFAM2/IFSTRT threads)
<li>IODEV=29 (IFAM2/IFDIAL, line-at-a-time threads)
</ul>

If any CRAM-dependent connections are defined to an Online (any of the above <var>[[IODEV parameter|IODEV]]</var> specifications), the Online must be able to load the CRAM [[#The XDM load modules|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:
<ul>
<li>[[Defining the user environment (CCAIN)#CRAM (IODEV=11, 23, 29)|Defining the user environment (CCAIN)]] </li>

<li>[[HLI: Job requirements#IFAM2 jobs|HLI: Job requirements]] </li>

<li>[[Model 204 installation on IBM z/OS#CRAM|Model 204 installation on IBM z/OS]] </li>
</ul>

===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 [[Defining the user environment (CCAIN)#CRAM-XDM performance versus CRAM-SVC|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 <var>IODEV</var> values mentioned in the previous section), the CRAM type you invoke is determined by the <var>[[XMEMOPT parameter|XMEMOPT]]</var> parameter value you specify: the <var>XMEMOPT</var> X'80' bit calls CRAM-XDM; absent the X'80' bit, any other non-zero <var>XMEMOPT</var> 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 [[Defining the user environment (CCAIN)#The importance of non-swappability|non-swappable and non-cancellable]]. It calls M204XSVC, described further [[#The XDM load modules|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 [[Defining the user environment (CCAIN)#Activating XDM|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 <var>MONITOR</var> or <var>EOJ</var> 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 [[Defining the user environment (CCAIN)#Managing CRAM-XDM|Managing CRAM-XDM]].

====The XDM load modules====
<ul>
<li>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 [[#M204XSVC|the M204XSVC section]]. </li>

<li>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. </li>

<li>M204XCRM handles cross-region communication between non-swappable callers. </li>

<li>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 [http://m204wiki.rocketsoftware.com/index.php/Model_204_CRAM_link_job_stream_for_IBM_z/OS CRAM installation JCL] (the value of <code>CRMSSN</code>), the SSN value is found in the <code>CRAMGEN</code> 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 <var>[[XDMSSN parameter|XDMSSN]]</var> 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.
</li>
</ul>

===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 [[Defining the user environment (CCAIN)#Using CRAM on a z/OS operating system|Using CRAM on a z/OS operating system]].

====Component modules====

These are the CRAM-SVC component modules: 
<ul>
<li>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. </li>

<li>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 <code>CRAMGEN</code> 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|The XDM load modules]]. </li>

<li>CRLMXPCC (CMS). </li>
</ul>

====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:
<ul>
<li>Pageable Link Pack Area (PLPA) </li>
<li>Modified Link Pack Area (MLPA) </li>
<li>Fixed Link Pack Area (FLPA) </li>
</ul>

=====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 (<code>CLPA</code>) 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:
<ul>
<li>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. </li>

<li>Minimizing page faults
<ul>
<li>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. </li>

<li>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. </li>

<li>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. </li>

<li>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. </li>

<li>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. </li>
</ul></li>
</ul>

=====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 <var class="term">nnn</var> corresponds to the specified <code>MLPA=nnn</code> 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:
<ul>
<li>Page faults can occur when MLPA modules are referenced. Unlike PLPA
modules, IEAPAK00 cannot be used to minimize page faults. </li>
</ul>

=====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 <var class="term">nnn</var> corresponds to the specified <code>FIX=nnn</code> 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:
<ul>
<li>Because the FLPA is an area of real storage, page faults do not occur when
FLPA modules are referenced. </li>

<li>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. </li>

<li>IGC00nnx must be placed in the FLPA, because the <code>XMPOST</code> routine must be page fixed. </li>
</ul>

=====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:
<ul>
<li><var class="term">N</var> is a number, 0 or 1, that identifies the load module. </li>

<li><var class="term">nn</var> are the first two digits of the site-determined SVC number. </li>

<li><var class="term">x</var> 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 </li>
</ul>

SVC number values may be between 200 and 250 (or <code>NOSVC</code> for an SVC-less installation). Examples of derived names follow: 
<table>
<tr class="head">
<th>SVC number</th>
<th>SVC load module name</th></tr>

<tr><td>SVC244</td>
<td>IGC0024D</td></tr>

<tr><td>SVC240</td>
<td>IGC0024{ </td></tr>
</table>

==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:
<ul>
<li>[[IOS Branch Entry]] (including [[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|zIIP processing]] and [[Defining the runtime environment (CCAIN)#Disk buffers and Model 204 storage|ATB buffer pool buffers]]) </li>

<li>[[Timer PC]] </li>

<li>[[UL/DB2]] </li>
</ul>

===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|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 <var>XMEMOPT</var> parameter values in CCAIN):
<ul>
<li>CRAM-XDM </li>
<li>IOS Branch Entry (including zIIP processing and ATB buffer pool buffers) </li>
<li>Timer PC </li>
<li>UL/DB2 </li>
</ul>

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 ([[Release notes for Model 204 version 7.6#M204XSVC as an SVC|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 <var>[[XMEMSVC parameter|XMEMSVC]]</var> is set). Once established, M204XSVC invokes routines by using PC instructions, and its only actual SVC call might be at initialization.

Cross-memory facilities CRAM and M204XSVC - Revision history

DCameron: /* Two CRAM types */

JAL: add category

JAL: Created page with "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. __TOC__ ==CRAM== Th..."

JAL: Created page with "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. TOC ==CRAM== Th..."