Defining the user environment (CCAIN): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (merge "Activating XDM" section info)
 
(78 intermediate revisions by 4 users not shown)
Line 10: Line 10:
==Setting user parameters==
==Setting user parameters==
<p>
<p>
Specifications controlling the environment of each Online user are entered in the CCAIN input stream on user parameter lines following User 0's runtime specifications. Each user line defines the input/output  access method and device (IODEV parameter), followed by appropriate control parameters.</p>
Specifications controlling the environment of each Online user are entered in the CCAIN input stream on user parameter lines following User 0's runtime specifications. Each user line defines the input/output  access method and device (<var>IODEV</var> parameter), followed by appropriate control parameters.</p>
   
   
===Basic rules===
===Basic rules===
Line 27: Line 27:
<li> Initial setting of a parameter on one line remains in effect until a second parameter is read that explicitly resets the first. If no parameter needs to be set (because all previous parameter settings are  applicable), you can use a statement with a single asterisk.</li>
<li> Initial setting of a parameter on one line remains in effect until a second parameter is read that explicitly resets the first. If no parameter needs to be set (because all previous parameter settings are  applicable), you can use a statement with a single asterisk.</li>
   
   
<li> Terminal interface is initialized if one or more IODEV statements of the same type are encountered in CCAIN. </li>
<li> Terminal interface is initialized if one or more <var>IODEV</var> statements of the same type are encountered in CCAIN. </li>
</ul>
</ul>
   
   
Line 71: Line 71:
   
   
<p>
<p>
[[#z/OS and z/VSE device type codes|z/OS and z/VSE device type codes]] and [[#z/VM input/output device type codes|z/VM input/output device type codes]] list each access method with its associated IODEV setting and required system (User 0) and user parameters. Details on each IODEV setting follow.</p>
The "z/OS and z/VSE device type codes" and "z/VM input/output device type codes" tables in the following section list each access method with its associated <var>IODEV</var> setting and required system (User 0) and user parameters. Further details for each <var>IODEV</var> setting are provided in the individual sections that make up most of the rest of this page.</p>


===Device types (IODEV settings)===
===Device types (IODEV settings)===
<p>
<p>
The following table lists z/OS and z/VSE input/output device types with required parameters.</p>
The following table lists z/OS and z/VSE input/output device types with required parameters:</p>
   
   
<table>
<table>
Line 113: Line 113:
<li> Program Communication facilities</li>
<li> Program Communication facilities</li>
</ul> </td>
</ul> </td>
<td>CRFSCHNL <br />LOUTPB <br />MODEL <br />NOTERM <br />POLLNO</td>
<td>CRFSCHNL <br />LOUTPB <br />MODEL <br />NOTERM <br />POLLNO <br />XDMSSN</td>
</tr>
</tr>
   
   
Line 124: Line 124:
<tr>
<tr>
<td>23</td>
<td>23</td>
<td>CRAM, Host Language IFAM2 thread</td>
<td>CRAM, [[IFAM|Host Language IFAM2]] thread</td>
<td>IFAMCHNL</td>
<td>IFAMCHNL <br />XDMSSN</td>
</tr>
</tr>
   
   
Line 145: Line 145:
   
   
<td>
<td>
CRIOCHNL<br />NCCC<br />INMRL<br />NOTERM<br />OUTCCC<br />OUTMRL<br />POLLNO</td>
CRIOCHNL<br />INCCC<br />INMRL<br />NOTERM<br />OUTCCC<br />OUTMRL<br />POLLNO <br />XDMSSN</td>
</tr>
</tr>
   
   
Line 161: Line 161:
</table>
</table>
   
   
<p>The following table lists z/VM/CMS settings for the <var>IODEV</var> and <var>ALTIODEV</var> parameters.</p>
<p>The following table lists z/VM/CMS settings for the <var>ALTIODEV</var> as well as the <var>IODEV</var> parameters:</p>
   
   
<table>
<table>
Line 181: Line 181:
<td>SNA Communications Server 3270 (full screen)</td>
<td>SNA Communications Server 3270 (full screen)</td>
<td>LOUTPB <br />MODEL <br />NOTERM <br />NOUTBUF <br />NSUBTKS <br />TERMBUF <br /> TERMID <br />TERMOPT <br /> VTAMNAME</td>
<td>LOUTPB <br />MODEL <br />NOTERM <br />NOUTBUF <br />NSUBTKS <br />TERMBUF <br /> TERMID <br />TERMOPT <br /> VTAMNAME</td>
</tr>
<tr>
<td>19</td>
<td>Horizon SQL thread</td>
<td>INMRL<br />NOTHREAD<br />NSUBTKS<br />SQLBUFSZ<br /></td>
</tr>
</tr>
   
   
Line 214: Line 220:
<td>Single-user full-screen mode  thread (Service machine  console)</td>
<td>Single-user full-screen mode  thread (Service machine  console)</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
<td>49</td>
<td>Remote Command Line (RCL)</td>
<td>NOTHREAD <br />POLLNO</td>
</tr>
</tr>
</table>
</table>
<p>
<p>
The following sections provide details about each <var>IODEV</var> setting. </p>
The following sections provide details about each <var>IODEV</var> setting. </p>
Line 257: Line 268:
</table>
</table>
   
   
<b>Trigger example</b>
<p>
<p>
The following SOUL program illustrates how to use IODEV=3 as a trigger. After the example, details on data set definitions and buffer allocation are presented.</p>
The following SOUL program illustrates how to use <code>IODEV=3</code> as a trigger to monitor the DBMS. After the example, details about data set definitions and buffer allocation are presented.</p>
<b>Trigger example</b>
<p>The following example uses IODEV=3 as a trigger to monitor the DBMS.</p>
   
   
<p class="code">//I0301I DD *
<p class="code">//I0301I DD *
Line 319: Line 327:
===Input or output data set definitions===
===Input or output data set definitions===
<p>
<p>
Each user defined as an IODEV=3 thread must have separate input and output data sets defined. Define input and output data sets using the <code>INPUT=<i>ddname</i></code> and <code>OUTPUT=<i>ddname</i></code> parameters on each IODEV=3 statement.</p>
Each user defined as an <code>IODEV=3</code> thread must have separate input and output data sets defined. Define input and output data sets using the <code>INPUT=<i>ddname</i></code> and <code>OUTPUT=<i>ddname</i></code> parameters on each <code>IODEV=3</code> statement.</p>
   
   
<p>
<p>
Line 343: Line 351:
====z/OS JCL examples====
====z/OS JCL examples====
<p>
<p>
The following examples show how to define input and output data sets for IODEV=3 in a z/OS environment. Input and output DD statement names are first defined as files in the JCL and then referenced on the IODEV=3  <var>INPUT</var> and <var>OUTPUT</var> parameters.</p>
The following examples show how to define input and output data sets for <code>IODEV=3</code> in a z/OS environment. Input and output DD statement names are first defined as files in the JCL and then referenced on the <code>IODEV=3</code> <var>INPUT</var> and <var>OUTPUT</var> parameters.</p>
   
   
<p>
<p>
The first example uses user-defined names that are coded on the IODEV=3 statement: </p>
The first example uses user-defined names that are coded on the <code>IODEV=3</code> statement: </p>
   
   
<p class="code">//I0301I DD DSN=dataset name,DISP=SHR
<p class="code">//I0301I DD DSN=dataset name,DISP=SHR
Line 389: Line 397:
===Buffer allocation===
===Buffer allocation===
<p>
<p>
Each IODEV=3 requires allocation of a set of buffers. Buffer allocation is based upon the <var>INMRL</var> value for input and <var>OUTMRL</var> for output, unless DCB information is specified in the JCL. By default, <var>INMRL</var> is 80 bytes and  <var>OUTMRL</var> is 132 bytes. (See [[#User environment control parameters|User environment control parameters]] for parameter summaries.)</p>
Each <code>IODEV=3</code> requires allocation of a set of buffers. Buffer allocation is based upon the <var>INMRL</var> value for input and <var>OUTMRL</var> for output, unless DCB information is specified in the JCL. By default, <var>INMRL</var> is 80 bytes and  <var>OUTMRL</var> is 132 bytes. (See [[#User environment control parameters|User environment control parameters]] for parameter summaries.)</p>
   
   
<p>
<p>
Line 395: Line 403:
   
   
<p>
<p>
If <var>INMRL</var> or <var>OUTMRL</var> is set on an IODEV line above the first <code>IODEV=3</code>, or if they are set in User 0 definitions, the <var>INMRL</var> and <var>OUTMRL</var> values define the values for IODEV=3.</p>
If <var>INMRL</var> or <var>OUTMRL</var> is set on an IODEV line above the first <code>IODEV=3</code>, or if they are set in User 0 definitions, the <var>INMRL</var> and <var>OUTMRL</var> values define the values for <code>IODEV=3</code>.</p>
   
   
<p>
<p>
Line 408: Line 416:
<var class="product">Model&nbsp;204</var> verifies that DFSMS/HSM is active before attempting to recall a migrated data set. If DFSMS/HSM is not active and a data set is migrated, the <var>ALLOCATE</var> (or <var>DEFINE</var>) command fails.</p>
<var class="product">Model&nbsp;204</var> verifies that DFSMS/HSM is active before attempting to recall a migrated data set. If DFSMS/HSM is not active and a data set is migrated, the <var>ALLOCATE</var> (or <var>DEFINE</var>) command fails.</p>
<p>
<p>
<var class="product">Model&nbsp;204</var> also detects archived data sets (volser=ARCHIV is used by non-IBM data management products). Archived data sets must be recalled before the <var class="product">Model&nbsp;204</var> Online step begins. An attempt to dynamically allocate an archived data set fails.</p>
<var class="product">Model&nbsp;204</var> also detects archived data sets (<code>volser=ARCHIV</code> is used by non-IBM data management products). Archived data sets must be recalled before the <var class="product">Model&nbsp;204</var> Online step begins. An attempt to dynamically allocate an archived data set fails.</p>
<p>
<p>
If a dynamic allocation attempt fails in either of these circumstances, the following messages appear:</p>
If a dynamic allocation attempt fails in either of these circumstances, the following messages appear:</p>
Line 416: Line 424:
</p>
</p>
<p>
<p>
The restrictions on archived data sets do not apply to BATCH204 jobs.</p>
The restrictions on archived data sets do not apply to [[BATCH204]] jobs.</p>
   
   
<p>
<p>
Line 424: Line 432:
</p>
</p>
   
   
==SNA Communications Server terminal support (IODEV=7, 37)==
==<b id="snaterm"></b>SNA Communications Server terminal support (IODEV=7, 37)==
<p>
<p>
The SNA Communications Server terminals that can log on directly to <var class="product">Model&nbsp;204</var> are:</p>
The [[SNA Communications Server overview and initialization|SNA Communications Server]] terminals that can log on directly to <var class="product">Model&nbsp;204</var> are:</p>
   
   
<table>
<table>
Line 447: Line 455:
   
   
<p>
<p>
SNA Communications Server is a fully functional component of <var class="product">Model&nbsp;204</var>. (For details, see the [[Model 204 documentation#Installation guides for version 7.4|7.4 installation guide]] for your operating system.) Verify that other terminals compatible with SNA Communications Server operation are fully compatible with <var class="product">Model&nbsp;204</var> before using them.</p>
SNA Communications Server is a fully functional component of <var class="product">Model&nbsp;204</var>, linked into the <var class="product">Model&nbsp;204</var> Online load module. Verify that other terminals compatible with SNA Communications Server operation are fully compatible with <var class="product">Model&nbsp;204</var> before using them.</p>
   
   
<p>
<p>
<var class="product">Model&nbsp;204</var> supports full-screen SNA Communications Server terminals that do not use the standard 3270 data stream by supplying a mechanism for writing exit routines to perform data conversion. The rules for such routines are provided in [[#Rules governing data conversion exit routines|Rules governing data conversion exit routines]].</p>
<var class="product">Model&nbsp;204</var> supports full-screen SNA Communications Server terminals that do not use the standard 3270 data stream by supplying a mechanism for writing exit routines to perform data conversion. The rules for such routines are provided in [[Coding SNA Communications Server conversion exit routines#Rules governing data conversion exit routines|Rules governing data conversion exit routines]].</p>
 
<p>
<p>
SNA Communications Server terminals are supported in z/OS, z/VSE, and CMS environments. For direct SNA Communications Server terminal support in a CMS environment, the optional CMS/SNA Communications Server Interface feature must be installed. Only full-screen terminals (IODEV=7) are supported by the CMS/SNA Communications Server Interface, which is described in [[#CMS/SNA Communications Server Interface for full-screen terminals|CMS/SNA Communications Server Interface for full-screen terminals]].</p>
SNA Communications Server terminals are supported in z/OS, z/VSE, and CMS environments. For direct SNA Communications Server terminal support in a CMS environment, the optional CMS/SNA Communications Server Interface feature must be installed. Only full-screen terminals (IODEV=7) are supported by the CMS/SNA Communications Server Interface, which is described in [[#CMS/SNA Communications Server Interface for full-screen terminals|CMS/SNA Communications Server Interface for full-screen terminals]].</p>
Line 457: Line 465:
===SNA Communications Server network definition requirements===
===SNA Communications Server network definition requirements===
<p>
<p>
An APPL statement in VTAMLST for each IODEV type (IODEV=7, IODEV=37) is required for direct SNA Communications Server terminal support by <var class="product">Model&nbsp;204</var>. The 1- to 8- character APPL names are used as the values for the VTAMNAME (full-screen) and VTAMNTO (line-at-a-time) parameters within the User 0 CCAIN lines.</p>
For direct SNA Communications Server terminal support by <var class="product">Model&nbsp;204</var>, you must define Model&nbsp;204 as an SNA Communications Server application program. Each <var>IODEV</var> type (IODEV=7, IODEV=37) requires an APPL statement in the SYS1.VTAMLST library (z/OS) or in a file with a VTAMLST filetype (CMS). The 1- to 8- character APPL names are used as the values for the <var>[[VTAMNAME parameter|VTAMNAME]]</var> (full-screen) and <var>[[VTAMNTO parameter|VTAMNTO]]</var> (line-at-a-time) parameters within the User 0 CCAIN lines.</p>
   
<p>
<p><var class="product">Model&nbsp;204</var> has no further requirements regarding the APPL statements or other network definition statements. For example, network concerns alone determine the setting of logmode table entries.</p>
For example, the following <code>VBUILD</code> and <code>APPL</code> statements in the VTAMLST data set define Model&nbsp;204 as an SNA Communications Server application node with major node name <code>M204</code> and minor node name <code>M204PROD</code>: </p>
<p class="code">M204 VBUILD  TYPE=APPL
<p class="note"><b>Note: </b><var class="product">Model&nbsp;204</var> supports both definite response and exception response protocols on messages outbound to the terminal. Requests for SNA definite responses to messages coming inbound from the terminal are not supported. For an exception response protocol on outbound messages, set the '02' value of the TERMOPT parameter setting on each IODEV=7 statement that refers to the terminal. </p>
M204PROD  APPL  </p>
<p>
In this case, the <code>M204PROD</code> APPL statement label must correspond to the value of the <var>VTAMNAME</var> parameter. If the APPL statement has an appended <code>ACBNAME=<i>altname</i></code> specification, <var class="term">altname</var> becomes the required <var>VTAMNAME</var> value, although Rocket recommends that you <i>do not use</i> <var>ACBNAME</var>. </p>
<p>
Appending <code>AUTH=(PASS)</code> to the APPL statement is required if your site uses the [[Program_Communication_facilities#SNA Communications Server Transfer Control|SNA Communications Server Transfer Control]] facility. </p>
<p>
<var class="product">Model&nbsp;204</var> has no further requirements regarding the APPL statements or other network definition statements. For example, network concerns alone determine the setting of logmode table entries.</p>
   
   
<p class="note"><b>Note: </b><var class="product">Model&nbsp;204</var> supports both definite response and exception response protocols on messages outbound to the terminal. Requests for SNA definite responses to messages coming inbound from the terminal are not supported. For an exception response protocol on outbound messages, include the '02' value in the <var>[[TERMOPT parameter|TERMOPT]]</var> parameter setting on each <code>IODEV=7</code> statement that refers to the terminal. </p>
===IP address using TN3270 connection to VTAM session: IPADDR===
===IP address using TN3270 connection to VTAM session: IPADDR===
<p>
<p>
TN3270 connections via Telnet can be made to a <var class="product">Model&nbsp;204</var> job with IODEV=7 connections defined in the job. For such a connection it may be desirable to know the IP address of that user's VTAM session. This information is now available via the IPADDR parameter. You can retrieve the IP address using the:</p>
TN3270 connections via Telnet can be made to a <var class="product">Model&nbsp;204</var> job with <code>IODEV=7</code> connections defined in the job. For such a connection it may be desirable to know the IP address of that user's VTAM session. This information is now available in the <var>IPADDR</var> parameter. You can retrieve the IP address using the:</p>
   
   
<ul>
<ul>
<li> VIEW command
<li><var>VIEW</var> command
<p class="code">VIEW IPADDR
<p class="code">VIEW IPADDR
</p> </li>
</p> </li>
   
   
<li> SOUL <var>$View</var> function
<li>SOUL <var>$View</var> function
<p class="code">%ipaddr=$view('IPADDR')
<p class="code">%ipaddr=$view('IPADDR')
</p></li>
</p></li>
Line 480: Line 495:
===CCAIN requirements===
===CCAIN requirements===
<p>
<p>
The following CCAIN parameters are relevant to IODEV=7 terminals:</p>
The following CCAIN parameters are relevant to <code>IODEV=7</code> terminals:</p>
   
   
<table>
<table>
Line 509: Line 524:
   
   
<tr>
<tr>
<td>NSUBTSKS</td>
<td>NSUBTKS</td>
<td>IPADDR</td>
<td>IPADDR</td>
</tr>
</tr>
Line 519: Line 534:
</table>
</table>
   
   
<p>The following CCAIN parameters are relevant to IODEV=37 terminals:</p>
<p>The following CCAIN parameters are relevant to <code>IODEV=37</code> terminals:</p>
   
   
<table>
<table>
Line 533: Line 548:
   
   
<tr>
<tr>
<td>NSUBTSKS </td>
<td>NSUBTKS </td>
<td>INMRL</td>
<td>INMRL</td>
</tr>
</tr>
Line 569: Line 584:
   
   
<p>
<p>
IODEV=7 terminals under CMS require an additional systemwide parameter VTGCSSRV (see the next section for details).</p>
<code>IODEV=7</code> terminals under CMS require an additional system parameter, <var>VTGCSSRV</var> (see the next section for details).</p>
   
   
<p>
<p>
All CCAIN parameters relevant to each IODEV type are listed in [[#z/OS and z/VSE device type codes|z/OS and z/VSE device type codes]] and [[#z/VM input/output device type codes|z/VM input/output device type codes]].</p>
All CCAIN parameters relevant to each <var>IODEV</var> type are listed in [[#z/OS and z/VSE device type codes|z/OS and z/VSE device type codes]] and [[#z/VM input/output device type codes|z/VM input/output device type codes]].</p>
   
   
===CMS/SNA Communications Server Interface for full-screen terminals===
===CMS/SNA Communications Server Interface for full-screen terminals===
<p>
<p>
<var class="product">Model&nbsp;204</var> under CMS implements its own SNA Communications Server communications requests using the CMS/SNA Communications Server Interface:</p>
<var class="product">Model&nbsp;204</var> under CMS implements its own SNA communications requests using the CMS/SNA Communications Server Interface:</p>
   
   
<ul>
<ul>
<li> All SNA Communications Server terminals logged on to <var class="product">Model&nbsp;204</var> are driven directly by the ONLINE, as in a z/OS or z/VSE environment. The ONLINE then becomes a SNA Communications Server APPL and an APPL statement is required for <var class="product">Model&nbsp;204</var> in the network's VTAMLST files.</li>
<li>All SNA terminals logged on to <var class="product">Model&nbsp;204</var> are driven directly by the ONLINE, as in a z/OS or z/VSE environment. The ONLINE then becomes an SNA application program, and an APPL statement is required for <var class="product">Model&nbsp;204</var> in the network's VTAMLST files.  
<p>
For a simple example, see [[#SNA Communications Server network definition requirements|SNA Communications Server network definition requirements]], above. </p></li>
   
   
<li> An additional systemwide CCAIN parameter, VTGCSSRV, is required. The CMS/SNA Communications Server Interface, although using the same SNA Communications Server terminal handler software module as in a z/OS environment (VT75), employs further software, which runs under z/VM's Group Control System (GCS). See the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var> for full details about setting up the CMS/SNA Communications Server Interface.</li>
<li>An additional system CCAIN parameter, <var>[[VTGCSSRV parameter|VTGCSSRV]]</var>, is required. The CMS/SNA Communications Server Interface, although using the same SNA terminal handler software module as in a z/OS environment (VT75), employs further software, which runs under z/VM's Group Control System (GCS). GCS is a virtual machine supervisor that supports a native VM SNA network. ACF/VTAM, for example, runs in a GCS virtual machine on z/VM.  
<p>
See [[#Preparing the GCS server componen|Preparing the GCS server component]] for details about setting up the GCS server. </p></li>
   
   
<li> Using the CMS/SNA Communications Server Interface for terminal support means that users are logged on to the ONLINE machine through SNA Communications Server services. A virtual machine is not required for each user. </li>
<li> Using the CMS/SNA Communications Server Interface for terminal support means that users are logged on to the ONLINE machine through CMS/SNA Communications Server Interface services. A virtual machine is not required for each user. </li>
</ul>
</ul>
<p>
<p>
The CMS/SNA Communications Server Interface is an optional feature. To use the <var class="product">Model&nbsp;204</var> distributed application facility, Horizon, under CMS, however, the CMS/SNA Communications Server Interface must be installed. For further information about Horizon, see the section [[#Managing IODEV=27 threads|Managing IODEV=27 threads]].</p>
The CMS/SNA Communications Server Interface is an optional feature. To use the <var class="product">Model&nbsp;204</var> distributed application facility, Horizon, under CMS, however, the CMS/SNA Communications Server Interface must be installed. For further information about Horizon, see the section [[#Managing IODEV=27 threads|Managing IODEV=27 threads]].</p>
   
   
<ul>
<ul>
<li> IODEV=37 terminals are not supported by the CMS/SNA Communications Server Interface.  </li>
<li><code>IODEV=37</code> terminals are not supported by the CMS/SNA Communications Server Interface.  </li>
   
   
<li> IODEV=41 support for full-screen terminals under CMS remains available whether or not the CMS/SNA Communications Server Interface is installed.</li>
<li><code>IODEV=41</code> support for full-screen terminals under CMS remains available whether or not the CMS/SNA Communications Server Interface is installed.</li>
</ul>
</ul>


==CRAM (IODEV=11, 23, 29)==
====Preparing the GCS server component====
The GCS server component contains the following elements:
<table>
<tr><td>GCS service machine directory entry</td>
<td>See [[#Defining the GCS directory entry|Defining the GCS directory entry]]. </td></tr>
 
<tr><td>M204VMVT LOADLIB</td>
<td>This file contains the program that runs the <var>VT204</var> command. The <var>VT204</var> command controls the CMS/VTAM Interface GCS service machine. </td></tr>
 
<tr><td>PROFILE GCS </td>
<td>GCS service machine uses this profile to start the <var>VT204</var>
command automatically at IPL time. </td></tr>
</table>
 
====Defining the GCS directory entry====
You need to define the Group Control System (GCS) service
machine directory entry only if you will be using the CMS/SNA Communications Server Interface or the [[Horizon]] interface.
 
The following sample shows a z/VM directory entry for the CMS/VTAM
Interface service machine. Items in italics, for example, password, should
conform to your installation configuration parameters and standards.
Enter items not in italics exactly as they are shown:
<p class="code">USER M204VMVT <i>password</i> 5M 6M G
ACCOUNT <i>account distcode</i>
OPTION MIH ECMODE MIH MAXCONN <i>nnn</i>
MACHINE <i>mode</i>
&#42; Allow any virtual machine to use server:
IUCV ALLOW MSGLIMIT 255
IPL GCS PARM AUTOLOG
CONSOLE 009 3270
&#42; For z/OS add:
NAMESAVE GCS
SPOOL 00C 2540 READER *
SPOOL 00D 2540 PUNCH A
SPOOL 00E 1403 A
&#42; Provide links so that IPL CMS is possible:
LINK MAINT 190 190 RR
LINK MAINT 19D 19D RR
LINK MAINT 19E 19E RR
&#42; LINK to disk with PROFILE and M204VMVT LOADLIB:
LINK MAINT204 193 191 RR
</p>
<p>
<p>
The Cross-Region Access Method (CRAM) is an interregional facility that lets applications access <var class="product">Model&nbsp;204</var>. The access is defined by device type codes and channel names in User 0's CCAIN stream. (See [[#CRAM channel names and parameters|CRAM channel names and parameters]].)</p>
Notes: </p>
<ul>
<li><code>OPTION</code> statement
<p>
The <code>OPTION MAXCONN <i>nnn</i></code> statement specifies how many concurrent IUCV paths this virtual machine can open. The CMS and VTAM interfaces use one IUCV path per opened VTAM access control block (ACB).
Set the <code>MAXCONN</code> number high enough to accommodate all ACBs that are opened at once.
Usually this is at least two per ONLINE virtual machine: one
for terminal handling (<code>IODEV=7</code>), and one for each link the system manager defines for the Online. Use a number somewhat higher than you currently need to avoid changing this directory entry each time a new ACB is added. </p></li>
 
<li><code>LINK</code> statements
<p>
The 191 disk of the GCS service machine is read-only. Link to the MAINT204
193 disk where the <code>M204VMVT LOADLIB</code> and sample <code>PROFILE GCS</code> are installed. </p></li>
 
<li><code>IUCV ALLOW</code> service machine
<p>
The sample directory entry authorizes any virtual machine in the system to
connect to an <code>IUCV ALLOW</code> service machine. You can restrict connections to
specifically authorized virtual machines by omitting <code>IUCV ALLOW</code> and using <code>IUCV</code> user ID statements instead. Be sure to add the <code>MSGLIMIT 255</code> operand.
For more information about the <code>IUCV</code> statement and other options, refer to the appropriate IBM documentation. </p></li>
 
<li>VTAM GCS group
<p>
The z/VM system programmer must allocate a slot in the CMS/SNA Communications Server's GCS group for
this service machine. This machine should not be in the authorization list; it is intended to run entirely in problem state. </p></li>
</ul>
 
==<b id="cram112329"></b>CRAM (IODEV=11, 23, 29)==
<p>
The Cross-Region Access Method (CRAM) is an interregional facility that lets applications access <var class="product">Model&nbsp;204</var>. The access is defined by device type codes and channel names in User 0's CCAIN stream. </p>
   
   
<ul>
<ul>
<li> For IFAM applications, communication handled by CRAM is a two-way conversation.</li>
<li>For [[IFAM]] applications, communication handled by CRAM is a two-way conversation.</li>
   
   
<li> For non-IFAM applications, communication handled by CRAM involves one program as the master and the other as a user. The master is always the <var class="product">Model&nbsp;204</var> service program, which can communicate with multiple users over the same channel. After a connection is established, the user thread can issue requests, as required, for the application.  </li>
<li>For non-IFAM applications, communication handled by CRAM involves one program as the master and the other as a user. The master is always the <var class="product">Model&nbsp;204</var> service program, which can communicate with multiple users over the same channel. After a connection is established, the user thread can issue requests, as required, for the application.  </li>
</ul>
</ul>
 
===Facilities requiring CRAM===
<p>
<p>
Remote User Language (IODEV=11, 29) and IFSTRT protocol IFAM2 (IODEV=23) threads require the use of CRAM. Terminals are considered remote User Language threads when either CICS or TSO is used. (See [[CICS terminal interface]] and [[TSO terminal interface]] for information about these interfaces.)</p>
Remote User Language (<code>IODEV=11</code>, <code>IODEV=29</code>), [[Introduction to the HLI facility#IFSTRT and IFDIAL threads|IFDIAL protocol]] IFAM2 (<code>IODEV=29</code>), and [[Introduction to the HLI facility#IFSTRT and IFDIAL threads|IFSTRT protocol]] IFAM2 (<code>IODEV=23</code>) threads require the use of CRAM. Terminals are considered remote User Language threads when either [[CICS terminal interface|CICS]] or [[TSO terminal interface|TSO]] is used. </p>
===Facilities requiring CRAM===
<p>
<p>
You must install CRAM if you use the products and interfaces in the following table (products are grouped according to IODEV value):</p>
The products and interfaces that require CRAM installation are displayed by <var>IODEV</var> value in the following table:</p>
<table>
<table>
<tr class="head">
<tr class="head">
<th><p>Facilities</p></th>
<th>Facilities</th>
<th><p>IODEV value</p></th>
<th>IODEV</th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>Full-screen support for:</p>
<td>Full-screen support for:
   
   
<ul>
<ul>
<li> CICS</li>
<li>CICS</li>
   
   
<li> TSO</li>
<li>TSO</li>
</ul></td>
</ul></td>
<td><p>11</p></td>
<td><p>11</p></td>
Line 630: Line 720:
   
   
<tr>
<tr>
<td><p>Host Language IFAM2/IFSTART</p></td>
<td>Host Language IFAM2/IFSTART</td>
<td><p>23</p></td>
<td>23</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>Line-at-a-time User Language thread for:</p>
<td>Line-at-a-time User Language thread for:
   
   
<ul>
<ul>
<li> BATCH2</li>
<li>[[BATCH2 (CRAM)|BATCH2]]</li>
   
   
<li> CICS</li>
<li>CICS</li>
   
   
<li> IFAM2/IFDIAL</li>
<li>IFAM2/IFDIAL</li>
   
   
<li> TSO</li>
<li>TSO</li>
</ul></td>
</ul></td>
<td><p>29</p></td>
<td>29</td>
</tr>
</tr>
</table>
</table>
   
   
===CRAM options for z/OS===
===Using CRAM on a z/OS operating system===
====Two CRAM options====
<p>
<p>
On z/OS sites, <var class="product">Model&nbsp;204</var> provides two CRAM options: CRAM SVC and Cross-Memory Data Mover (CRAM-XDM). CRAM-XDM is the default and CRAM SVC is deprecated as of Model&nbsp;204 version 7.5.</p>  
On z/OS sites, <var class="product">Model&nbsp;204</var> supports two CRAM options: CRAM-SVC and CRAM-XDM (Cross-Memory Data Mover). [[Model 204 installation on IBM z/OS#CRAM|CRAM-XDM is the default]], and CRAM-SVC is deprecated as of Model&nbsp;204 version 7.5.</p>  
<p>
<p>
z/VM and z/VSE sites support only the CRAM SVC option.</p>
z/VSE sites support only the CRAM-SVC option, and z/VM sites support neither.</p>
   
   
<p>
<p>
You can run the following CRAM options on the same machine. A <var class="product">Model&nbsp;204</var> Online, however, can operate only one CRAM option at a time.</p>
You can run both CRAM options on the same z/OS machine. A <var class="product">Model&nbsp;204</var> Online, however, can operate only one CRAM option at a time.</p>
   
   
<ul>
<ul>
<li>CRAM SVC
<li>CRAM-SVC
<p>
CRAM-SVC is CRAM functionality accomplished with SVC calls. 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.  </p>
<p>
<p>
CRAM SVC continues to work for both z/OS and z/VSE, but it is deprecated as of version 7.5 of Model&nbsp;204.</p></li>
Although earlier CRAM-SVC installations continue to work for both z/OS and z/VSE sites, it is deprecated as of version 7.5 of Model&nbsp;204 and no installation instructions are offered.</p></li>
   
   
<li>CRAM-XDM  
<li>CRAM-XDM  
<p>
<p>
To choose the CRAM-XDM option, set the <var>[[XMEMOPT parameter|XMEMOPT]]</var> parameter X'80' bit in the User 0 CCAIN stream. If the X'80' bit is not set, the CRAM SVC option is attempted.</p>  
CRAM-XDM uses z/OS cross memory services to move pages from one address space to another in one instruction. All data moves are done using access registers. CRAM-XDM initializes a single cross-memory environment, M204XDM, that is shared among all Model&nbsp;204 Onlines. The M204XDM job is the master XDM job; it must be submitted separately, <i>before</i> the Online jobs that might use that XDM. </p>
<p>
<p>
CRAM-XDM initializes a single cross-memory environment that is shared among all Onlines. <i>You must submit the <code>M204XDM</code> (XDM master) job before any Online jobs.</i> For Onlines that use CRAM-XDM, the XDM master must be running.</p>
The XDM address space must be [[#The importance of non-swappability|defined as non-swappable]], and it uses a system Linkage Index (LX). It is recommended that you define the address space as non-cancellable, in which case it will always recover from an abend.</p></li>
<p>
The XDM address space must be [[#Implementing CRAM-XDM usage for z/OS operating systems|defined as non-swappable]], and it uses a system Linkage Index (LX). It is recommended that you define the address space as non-cancellable, in which case it will always recover from an abend.</p>
<p>
Because only one Subsystem Access Control Block (SSACB) is established per z/OS image, XDM always reuses the same system LX, even if forced down. A new address space is always used, because a system LX always makes the address space nonreusable. (However, XDM must be started and left active for the life of the IPL.)</p>
<p>
XDM terminates, on request, only if all cross-memory connections have been disconnected. An outstanding operator reply is used to communicate to XDM. In addition to terminate, a <code>MONITOR,ONLINES</code> command lists on the operator console all address spaces that have connections to XDM. All data moves are done using access registers.</p></li>
</ul>
</ul>
====CRAM-XDM performance versus CRAM SVC====
<p>
<p>
When you install Model&nbsp;204, you decide which option of CRAM to use. As of version 7.5 of Model&nbsp;204, CRAM-XDM is the default and CRAM SVC is deprecated. </p>
For additional background information about CRAM and its constituent modules, see [[Cross-memory facilities CRAM and M204XSVC]]. </p>


If you use CRAM-XDM, you can expect the following performance enhancements:
====CRAM-XDM performance versus CRAM-SVC====
If you use CRAM-XDM, the default CRAM option as of version 7.5 of Model&nbsp;204, you can expect the following performance enhancements compared to CRAM-SVC:
   
   
<table>
<table>
Line 712: Line 796:
This lets you support more concurrent connections between multiple Onlines and multiple XDM clients connecting to those Onlines (CICS tasks and batch IFAM tasks).</p>  
This lets you support more concurrent connections between multiple Onlines and multiple XDM clients connecting to those Onlines (CICS tasks and batch IFAM tasks).</p>  
<p>
<p>
For example: Without XDM, a single CICS region that communicates to 3 Online regions needs 3 ALETS, one for each Online. With XDM, each CICS region may talk to multiple Onlines using one ALET. So for 3 CICS regions to communicate to 3 Online regions, a total of 6 ALETS is needed: one ALET for each CICS region, and one for each Online.</p></td>
For example: With XDM prior to version 7.5, a single CICS region that communicates to three Online regions needs three ALETs, one for each Online. With XDM version 7.5 and higher, a CICS region may use the same ALET to talk to multiple Onlines (and similarly, each Online uses a single, separate ALET to talk to one or more CICS regions). So for three CICS regions to communicate with three Online regions under 7.5 and higher, a total of six ALETs is needed (versus nine ALETs under XDM version 7.4).</p></td>
</tr>
</tr>
</table>
</table>


<p>
<p>
You might decide to use CRAM without XDM at your site because:</p>
You might decide <i>not</i> to use CRAM-XDM at your site because:</p>
<ul>
<ul>
<li> Your site does not allow non-swappable, APF-authorized tasks in your environment.</li>
<li>Your site does not allow non-swappable, APF-authorized tasks in your environment.</li>
   
   
<li> CRAM performance is a non-issue.</li>
<li>CRAM performance is a non-issue.</li>
   
   
<li> CSA storage limitations are a non-issue.</li>
<li>CSA storage limitations are a non-issue.</li>
</ul>
</ul>


===Invoking a CRAM option===
====The importance of non-swappability====
<p>
<p>
The CRAM option that is invoked is determined by the setting of the <var>[[XMEMOPT parameter|XMEMOPT]]</var> parameter in an Online's CCAIN input: </p>
Defining the XDM address space as non-swappable (described below in [[#Activating CRAM-XDM|Activating CRAM-XDM]]) is required.
Defining the Model&nbsp;204 address space as non-swappable (described further in [[Performance monitoring and tuning#z.2FOS|Performance monitoring and tuning]]) is not required but is <i>strongly recommended</i>. </p>
<p>
If an address space is swappable, performance degrades due to the necessity of resuming an SRB and the z/OS scheduling delays that entails. The performance penalty when running a multi-user Online as swappable is extremely high in terms of user response times. </p>
<p>
A non-swappable address space requires no SRBs and associated z/OS scheduling delays. The fastest environment therefore involves:</p>
 
<ul>
<li>Non-swappable application</li>
   
   
<table>
<li>Non-swappable Online</li>
<tr class="head">
<th><p>This XMEMOPT setting...</p></th>
<th><p>Initializes...</p></th>
</tr>
   
   
<tr>
<li>CRAM-XDM</li>
<td><p>X'80' </p></td>
</ul>
<td><p>CRAM-XDM environment</p></td>
 
</tr>
====Invoking a CRAM option====
<tr>
<td><p>Any other setting</p></td>
<td><p>CRAM SVC environment(if CRAM threads are defined)</p></td>
</tr>
</table>
<p>
<p>
CRAM-XDM Onlines are compatible with the CRAM SVC option; both can be used on the same z/OS subsystem. However, a given address space can use only one method. All channels within the Online address space can use either the CRAM-XDM option or the CRAM SVC option, but not both.</p>
If CRAM threads are defined in an Online's CCAIN input, the CRAM option that is invoked is determined by the setting of the <var>[[XMEMOPT parameter|XMEMOPT]]</var> parameter in CCAIN: </p>
   
   
====Care with CRAM-XDM LXs====
<ul>
<li>X'80' bit included: initializes CRAM-XDM environment </li>
 
<li>X'80' bit <i>not</i> included: initializes CRAM-SVC environment
</ul>
<p>
<p>
As [[#CRAM options for z/OS|mentioned earlier]], CRAM-XDM uses a system LX. A system LX is intended for a long-running task and must be used carefully because it is a limited system resource. The address space that uses a system LX is, by definition, not reusable, and the following z/OS warning message is issued if you EOJ the XDM job: </p>
CRAM-XDM Onlines are compatible with the CRAM-SVC option; both can be used on the same z/OS subsystem. However, a given address space can use only one method. All [[#Communicating with multiple regions of Model 204|channels]] within the Online address space use either the CRAM-XDM option or the CRAM-SVC option, but not both.</p>
<p class="code">IEF352I ADDRESS SPACE UNAVAILABLE </p>
<p>
Bouncing XDM jobs frequently could exhaust the supply of address spaces and require an IPL. </p>


====The importance of non-swappability====
====CRAM OPEN processing====
<p>
<p>
Although a non-swappable address space is not required, defining the Model&nbsp;204 address space as non-swappable (described in the next section) is <i>strongly recommended</i>. If an address space is swappable, performance degrades due to the necessity of resuming an SRB and the z/OS scheduling delays that entails. The performance penalty when running a multi-user Online as swappable is extremely high in terms of user response times. </p>
CRAM can operate in two modes: converser and master/user:</p>
<p>
A non-swappable address space requires no SRBs and associated z/OS scheduling delays. The fastest environment therefore involves:</p>
 
<ul>
<ul>
<li> Non-swappable application</li>
<li>Converser mode is like a telephone conversation: either side can speak, and one waits for the other if there is a conflict. IFAM applications use the converser mode.</li>
   
   
<li> Non-swappable Online</li>
<li>Master/user is like a half-duplex conversation: the end-user requests to speak, and the <var class="product">Model&nbsp;204</var> Online (master) gives permission. The Online controls the entire conversation by telling the user what to do next. </li>
</ul>
<p>
Internally, an Online makes CRAM communication possible by issuing a master <code>CRAM OPEN</code> command, specifying a channel name, a block size, and the number of connections (subchannels) available. The information needed to issue this <code>OPEN</code> is derived from parameters (which must include an <var>IODEV</var> set to 11, 23, or 29) specified on User&nbsp;0's parameter line. Subsequently, <var class="product">Model&nbsp;204</var> applications can issue IFAM calls on a particular channel.</p>
   
   
<li> CRAM-XDM</li>
====CRAM storage requirements====
</ul>
<p>
When a CRAM master opens a channel, space is allocated in the Common Service Area (CSA). You must allocate sufficient CSA space to allow the <var class="product">Model&nbsp;204</var> [[Host Language Interface (HLI)]] to provide support for <var>IODEV</var> 11, 23, or 29 threads.</p>


===Implementing CRAM-XDM usage for z/OS operating systems===
<ul>
<li><b>CRAM CSA space for HLI</b>
<ul>
<li>CRAM-XDM
<p>
<p>
To implement CRAM-XDM after you have installed and tested <var class="product">Model&nbsp;204</var>, take the following steps: </p>
The following Model&nbsp;204 7.7 calculation determines the approximate requirements for each active XDM region:</p>
   
   
<ol>
<p class="code">CSA Space = 1888 + 30 + (60 * <i>onln</i>) + (50 * <i>chnl</i>) + (60 * <i>cnct</i>) + (20 * <i>asid</i>) + <i>trace</i>
<li>[[Model 204 installation on IBM z/OS#CRAM|Install CRAM-XDM]].</li>
</p>
<p>
Where (the values shown are in hexadecimal):</p>
   
   
<li>Start CRAM-XDM:
<ul>
<ol>
<li>1888 is the size of the XMEMCSA module (resident in CSA).</li>
<li>Make sure the XDM address space is non-swappable.
<p>
<li>30 is the SSACB length.</li>
A systems programmer must include a PPT (Program Properties Table) entry in SYS1.PARMLIB(SCHD<i>xx</i>) for the <code>M204XDM</code> module. Specify <code>NOSWAP</code> (non-swappable); and specifying <code>NOCANCEL</code> (non-cancelable) is recommended. </p>
<p class="warn"><b>Attention:</b>
<li><var class="term">onln</var> is the SSCB length.</li>
If you make CRAM-XDM cancelable, and the operator cancels <var class="product">Model&nbsp;204</var> XDM, CSA storage is orphaned. To reclaim the orphaned storage, you must IPL z/OS.</p></li>
<li><var class="term">chnl</var> is the IICB length.</li>
   
   
<li>Submit an M204XDM job like the following <i>before bringing up any Onlines</i>, substituting with values appropriate to your site. The job assumes the default installation of CRAM-XDM in its own (CRAMLIB) load library.
<li><var class="term">cnct</var> is the UICB length.</li>
   
   
<p class="code">//XDMNC    EXEC PGM=M204XDM,PARM='<i>ssn</i>',TIME=NOLIMIT
<li><var class="term">asid</var> is the ASID table entry.</li>
//STEPLIB  DD  DSN=M204V76.CRAM.LOADLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=X
//
</p>
<p>
<var class="term">ssn</var> is the name of the z/OS secondary subsystem that points to the XDM control blocks to use. It is a maximum of four characters. The default SSN was specified as the value of <code>CRMSSN</code> in the [[Model 204 CRAM link job stream for IBM z/OS|CRAM installation JCL]]. LKCRAMJ links the IGCLM244 load module and provides it with the subsystem name.</p>
<p>
<code>TIME=NOLIMIT</code> is required to initialize M204XDM. </p>
<p class="note"><b>Note:</b> You must submit this job every time you IPL z/OS. </p></li>
   
   
<li>Set the appropriate <var>XMEMOPT</var> parameter option in your <var class="product">Model&nbsp;204</var> Online CCAIN stream. Include the X'80' bit.
<li><var class="term">trace</var> is the trace table (length default is 3K per channel).</li>
<p class="note"><b>Note:</b> An INCLUDE for the <code>M204XSVC</code> object module is added to the Online link-edit job by default as of version 7.5; and <code>M204XSVC</code> is also linked by default into CRAMLIB, the CRAM load library. <code>M204XSVC</code> is <i>not</i> installed as an SVC. As a result, no <var>XMEMSVC</var> parameter setting for XDM is required in CCAIN.</p></li>
</ul><br></li>


<p class="note"><b>Note:</b> No <var>XMEMSVC</var> parameter setting for XDM is required in CCAIN. The <code>M204XSVC</code> object module, which is linked by default into the CRAM load library, is <i>not</i> installed as an SVC as may have been the case in earlier versions. An INCLUDE for the <code>M204XSVC</code> module is also added to the Online link-edit job by default as of version 7.5. </p></li>
<li>CRAM-SVC
<p>
The amount of CSA space necessary for CRAM-SVC is equal to the amount of virtual storage shown in the calculation in the following subsection.</p></li>
</ul></li>


<li>Submit the M204XDM job prior to bringing up any Online. Otherwise, if M204XDM is unavailable and an Online CCAIN specifies an <var>XMEMOPT</var> value that includes the X'80' bit, the Online cannot initialize.</li>
<li><b>Virtual storage</b>
</ol></ol>
 
===Monitoring XDM===
<p>
<p>
After CRAM is installed and the M204XDM job is up and running, you can monitor CRAM-XDM from the console or from a batch job.</p>
The following calculation determines the approximate virtual storage requirements for each <var class="product">Model&nbsp;204</var> Online that has <var>IODEV</var> 11, 23, or 29 threads defined.</p>
<p class="note"><b>Note:</b> This same amount of space is also required in CSA if CRAM-SVC is used. </p>
   
   
====Using console commands====
<p class="code">Virtual storage requirement = Min(<i>nif</i>,1) * (68 + (<i>nif</i> * (IFAMBS + 100)))
<p>
+ Min(<i>nul</i>,1) * (68 + (<i>nul</i> * (Max(INMRL,OUTMRL) + 100)))
To monitor XDM, you can issue a <var>MONITOR</var> command. (Authorized users can also issue console commands from SDSF using the <code>/<i>nn</i> </code> syntax). When the XDM master address space is active, it displays the following reply message on the operator console:</p>
+ Min(<i>nfs</i>,1) * (68 + (<i>nfs</i> * (LOUTPB + 100)))
<p class="syntax">*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
</p>
</p>
<p>
<p>
Line 821: Line 900:
   
   
<ul>
<ul>
<li><var class="term">nn</var> is the message number to reply to.</li>
<li><code>Min</code> is the Minimum function.</li>
   
   
<li><var class="term">jobname</var> is the end-user-defined jobname running M204XDM.</li>
<li><code>Max</code> is the Maximum function.</li>
</ul>
   
   
<p>
<li><var class="term">nif</var> is the number of <code>IODEV=23</code> users.</li>
The following table lists the available <var>MONITOR</var> commands:</p>
   
   
<table class="thJustBold">
<li><var class="term">nul</var> is the number of <code>IODEV=29</code> users.</li>
<caption>Available MONITOR commands</caption>
<tr>
<td><b>Command</b></td>
<td><b>Description</b></td>
</tr>
   
   
<tr>
<li><var class="term">nfs</var> is the number of <code>IODEV=11</code> users.</li>
<th><br>MONITOR<br>MONITOR,ONLINES<br>ONLINES</th>
<td>Lists all Onlines connected to an XDM master; can be abbreviated:
<ul>
<li>M/MO/MON, and so on.</li>
<li>MONITOR,O/ON/ONL, and so on.</li>
<li>O/ON/ONL, and so on.</li>
</ul></td>
</tr>
   
   
<tr>
<li>The <var>IFAMBS</var> parameter sets the IFAM2 block size.
<th><br>MONITOR,USERS<br>USERS</th>
<p>
<td>Lists all jobs using XDM to connect to any Online; can be abbreviated: 
<var>IFAMBS</var> must be set between 2 to 5 times the value of the <var>LIBUFF</var> or <var>LOBUFF</var> parameter. (Most host language parameters are assumed to be <var>LIBUFF</var> long and to occupy a <var>LIBUFF</var> portion of <var>IFAMBS</var> during processing by the IFAM2 interface.)</p> </li>
<ul>
<li>MONITOR,U/US/USE and so on.  </li>
<li>U/US/USE and so on.  </li>
</ul></td>
</tr>
<tr>
<th>MONITOR,ONLINE=<i>jobname</i><br>ONLINE=<i>jobname</i> </th>
<td>Lists all jobs using XDM to connect to the specified Online. </td>
</tr>
</table>
   
   
<li><var>LOUTPB</var> is the length of the output page buffer required for full-screen features. </li>
</ul></li>
</ul>
====CRAM buffer allocation====
<p class="note"><b>Note:</b> The CRAM buffer sizing discussed below applies only if CRAM-SVC is being used. CRAM-XDM does not use these buffers. </p>
<p>
For <code>IODEV=29</code>, the size of the CRAM buffer is the maximum of (<var>[[INMRL parameter|INMRL]]</var>, <var>[[OUTMRL parameter|OUTMRL]]</var>) + 4. If neither of these parameters is specified on the User 0 parameter line, the default of 256 bytes applies.
If an application program uses the extended communication buffer, you can set <var>INMRL</var> and <var>OUTMRL</var> up to 32K to accommodate it.</p>
<p>
For <code>IODEV=23</code>, the size of the CRAM buffer is <var>[[IFAMBS parameter|IFAMBS]]</var> which defaults to 2048.  Its maximum is 32,688. </p>
<p>
For <code>IODEV=11</code>, the size of the CRAM buffer is <var>[[LOUTPB parameter|LOUTPB]]</var>, which default to 0.  Its maximum is 32,767. </p>
<p>
CRAM buffers are allocated as users are activated, or, in the case of <code>IODEV=11</code> (<var>LOUTPB</var>), during initialization. The minimum CSA usage, without active users, is 68 bytes per channel and 100 bytes per user as defined by the number of <var>IODEV</var> definitions of the same type. When the first user opens a thread (<code>IODEV=23</code> or <code>IODEV=29</code>), the associated CRAM buffer, sized by <var>IFAMBS</var> or max(<var>INMRL</var>, <var>OUTMRL</var>)+4, is allocated.</p>
<p>
<p>
The output is sent to the z/OS console and CCAPRINT in the M204XDM job. If you want another report, issue another <var>MONITOR</var> command. The new output is also sent to the console and is appended to the existing CCAPRINT.  </p>
CRAM buffers are reusable, and they are freed only when <var class="product">Model&nbsp;204</var> terminates.</p>
 
====<b id="Communicating with multiple regions of Model 204"></b>Communicating with multiple regions of Model 204: channel names====
<p>
<p>
In the following display example, three jobs are using no XDM threads and three jobs are using a total of 12 XDM threads. The <code>CAT11C</code> job is using 4 XDM threads, and so on.</p>
You can communicate with several regions of <var class="product">Model&nbsp;204</var> concurrently by establishing a distinct CRAM channel name for each region. One <var>IFDIAL</var> remote User Language thread and several <var>IFSTRT</var> IFAM2 threads can communicate over a particular channel when the channel name is specified in the <var>[[IFDIAL (HLI function)|IFDIAL]]</var> or <var>[[IFSTRT (IFAM2/IFAM4) (HLI function)|IFSTRT]]</var> call that establishes the connection. You must use one <var>IODEV</var> definition for each terminal.</p>
<p class="code">M204XDM.313: XDM Master Jobname=CAT141A ACTIVE (Subsystem=CAT1)
_M204XDM.314:    Online Jobname=CAT108  Users=0
_M204XDM.314:    Online Jobname=CAT11C  Users=4
_M204XDM.314:    Online Jobname=CAT11S  Users=2
_M204XDM.314:    Online Jobname=CAT112  Users=0
_M204XDM.314:    Online Jobname=CAT109  Users=6
_M204XDM.314:    Online Jobname=CAT102  Users=0
_M204XDM.318: (Totals)  Onlines=6  Users=12
</p>
   
   
====Using a batch job====
<p>
<p>
To monitor XDM, use a standalone batch job, when: </p>
CRAM channel names (as many as eight characters) are specified on the User 0 parameter line.
<ul>
The following table shows the default CRAM channel names and how to establish a connection using an alternate channel name.</p>
<li>You might not be authorized to issue console commands. </li>
<table>
 
<caption>Default and alternate channel names</caption>
<li>You do not want voluminous <var>MONITOR</var> command output sent to the JES log of the XDM task, or to the console log. </li>
<tr class="head">
 
<th><p>IODEV</p></th>
<li>You need to get additional information. The batch job provides options for more detailed reporting and you can dump the control blocks for problem diagnosis. </li>
<th><p>Access method</p></th>
</ul>
<th><p>Default channel name</p></th>
<th><p>To define an alternate channel name...</p> </th>
</tr>
   
   
<p>  
<tr>
Execute the report with the following JCL: </p>
<td><p>11 </p></td>
<td><p>Full-screen</p></td>
<td><p>M204FULL</p>
</td>
<td><p>Specify a <var>CRFSCHNL</var> parameter value on the User 0 parameter line.</p></td>
</tr>
   
   
<p class="code">//MON    EXEC  PGM=M204XMON,PARM='<i>parameter</i>'
<tr>
//STEPLIB  DD  DSN=<i>your</i>.LOADLIB,DISP=SHR
<td><p>23</p></td>
//CCAPRINT DD  SYSOUT=* </p>
<td><p>IFSTRT protocol IFAM2 threads</p></td>
<td><p>IFAMPROD </p>
<p>&nbsp;</p></td>
<td><p>Specify an <var>IFAMCHNL</var> parameter value on the User 0 parameter line.</p>
<p>
<p>
The output goes to CCAPRINT. Unless you request otherwise, no output is written to the operator console. </p>  
To access the Online, call <var>[[IFSTRTN (IFAM2) (HLI function)|IFSTRTN]]</var> and specify the alternate channel name. <var>IFSTRT</var> accesses only the default channel.</p> </td></tr>
<p>
The argument string can be in one of the following forms: </p>
   
   
<p class="syntax">SSNAME=<span class="term">ssss</span>,ONLINE=<span class="term">oooooooo</span>,DETAIL=<span class="term">nnn</span>,
<tr>
OUTPUT=CONSOLE </p>
<td><p>29</p></td>
<td>
<p>
<p>
or: </p>
IFDIAL protocol IFAM2, line-at-a-time</p></td>
<td><p>M204PROD</p></td>
<td><p>
<var>Specify a CRIOCHNL</var> parameter value on the User 0 parameter line. </p>
<p>To access the Online, call
<var>[[IFDIALN (HLI function)|IFDIALN]]</var> and specify the alternate channel name. <var>[[IFDIAL (HLI function)|IFDIAL]]</var> accesses only the default channel.</p></td>
</tr>
</table>
 
====Debugging CRAM====
The debugging utility for CRAM-XDM is M204XMON, and the debugging utility for CRAM-SVC is SNAPCRAM. A SNAPCRAM utility also debugs [[#SNAPCRAM utility for z/VSE|CRAM under z/VSE]].
 
=====M204XMON=====
<p>
The <code>M204XMON</code> utility is used to debug CRAM-XDM. You can run M204XMON with the parameters shown in the following JCL example:</p>
   
   
<p class="syntax"><span class="term">ssss</span>
<p class="code">// Job Card...
//JOBLIB  DD DSN=<i>Model204Cram</i>.LOADLIB,DISP=SHR
//XDMNC  EXEC PGM=M204XMON,PARM='SSNAME=<i>xxxx</i>,DETAIL=255'
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=A
/*
//
</p>
</p>
<p>
where <var class="term">xxxx</var>  is the [[#xdmjob|secondary subsystem name]] used by the CRAM-XDM region.  </p>


<p>Where: </p>
=====SNAPCRAM=====
<p>
The SNAPCRAM utility is used to debug CRAM-SVC under z/OS.
SNAPCRAM prints out the CRAM control blocks in dump format. Sample JCL for running SNAPCRAM is:</p>
   
   
<ul>
<p class="code">// Job Card...
<li><var class="term">ssss</var> is the CRAM z/OS subsystem name to report on (required). </li>
//SNAPCRAM EXEC PGM=SNAPCRAM
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
<li><var class="term">oooooooo</var> is the Online name to report on (optional). If not specified, reports on all Onlines using XDM. </li>
//        DD DSN=M204.CRAMLIB,DISP=SHR
//CCASNAP DD SYSOUT=A
/*
</p>
<p>
If CRAM is installed in a separate library, the M204.CRAMLIB concatenation shown above is required.</p>
 
===Managing CRAM-XDM===
 
====Care with CRAM-XDM LXs====
<p>
As [[#Two CRAM options|mentioned earlier]], CRAM-XDM uses a system LX.
A system LX is intended for a long-running task and must be used carefully because it is a limited system resource. </p>
<p>
Because only one Subsystem Access Control Block (SSACB) is established per z/OS image, XDM always reuses the same system LX, even if forced down. A new address space is always used, because a system LX always makes the address space non-reusable. (However, XDM must be started and left active for the life of the IPL.)</p>
<p>
Since the address space that uses a system LX is not reusable, the following z/OS warning message is issued if you EOJ the XDM job: </p>
<p class="code">IEF352I ADDRESS SPACE UNAVAILABLE </p>
<p>
Bouncing XDM jobs frequently could exhaust the supply of address spaces and require an IPL. </p>
 
====Activating CRAM-XDM====
<p>
To implement a new version of CRAM-XDM, take the following steps: </p>
<ol>
<li>Install CRAM-XDM.
<p>
See the Model&nbsp;204 installation on z/OS [[Model 204 installation on IBM z/OS#CRAM|instructions for CRAM]]. That CRAM section also includes ways to configure versions of CRAM and Model&nbsp;204 that are not the same. For example, you might want to wait to install CRAM-XDM until after you install and test <var class="product">Model&nbsp;204</var> with an existing production version of CRAM. Or you might be making the recommended transition from CRAM-SVC to CRAM-XDM. </p></li>
   
   
<li><var class="term">nnn</var> specifies what to report (optional). If not specified, defaults to 3. </li>
<li>Bring down the Online(s) with which you want to test this new CRAM version. </li>
 
<li>Start CRAM-XDM:
<ol type="a">
<li>Make sure the XDM address space is non-swappable.
<p>
A systems programmer must include a PPT (Program Properties Table) entry in SYS1.PARMLIB(SCHD<i>xx</i>) for the <code>M204XDM</code> module. Specify <code>NOSWAP</code> (non-swappable); and specifying <code>NOCANCEL</code> (non-cancelable) is recommended. </p>
<p class="warn"><b>Attention:</b>
If you make CRAM-XDM cancelable, and the operator cancels <var class="product">Model&nbsp;204</var> XDM, CSA storage is orphaned. To reclaim the orphaned storage, you must IPL z/OS.</p></li>
   
   
<li><code>CONSOLE</code> specifies that the report is sent to both the console and CCAPRINT (otherwise to CCAPRINT only). </li>
<li id="xdmjob">Submit an M204XDM job like the following <i>before bringing up any Onlines</i>, substituting with values appropriate to your site. The job assumes the default installation of CRAM-XDM in its own (CRAMLIB) load library.
   
   
<li><code>DETAIL=<i>nnn</i></code> is the sum of the following values:
<p class="code">//XDMNC    EXEC PGM=M204XDM,PARM='<i>ssn</i>',TIME=NOLIMIT
//STEPLIB  DD  DSN=M204V76.CRAM.LOADLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=X
//
</p>
<p>Where: </p>
<ul>
<li id="cramssn"><var class="term">ssn</var> is the name of the z/OS secondary subsystem that points to the XDM control blocks to use. It is a maximum of four characters. The default SSN was specified as the value of <code>CRMSSN</code> in the [[Model 204 CRAM link job stream for IBM z/OS|CRAM installation JCL]], which links the IGCLM244 load module and provides it with the subsystem name. </li>
 
<li><code>TIME=NOLIMIT</code> is required to initialize M204XDM. </li>
</ul>
<blockquote class="note">
<b>Notes:</b>
<ul>
<li>If you do not submit the M204XDM job prior to bringing up an Online that specifies an <var>XMEMOPT</var> value that includes the X'80' bit, the Online cannot initialize. </li>
 
<li>You must submit the M204XDM job every time you IPL z/OS. </li>
</ul></blockquote></li>
</ol>
   
   
<table>
<li>Prepare the job to bring up the Online:
<tr class="head">
<ol type="a">
<th><p>Value</p></th>
<li>Set the [[#Device types (IODEV settings)|appropriate CCAIN parameters]], especially <var>IODEV</var>, <var>XMEMOPT</var> (including the X'80' bit), and <var>[[XDMSSN parameter|XDMSSN]]</var>, bring up the Online(s) with which you want to test this new CRAM version.
<th><p>Purpose</p></th>
 
</tr>
<p id="204xsvc" class="note"><b>Note:</b> No <var>XMEMSVC</var> parameter setting for XDM is required in CCAIN. The <code>[[Cross-memory facilities CRAM and M204XSVC#M204XSVC|M204XSVC]]</code> object module, which is linked by default into the CRAM load library, is <i>not</i> installed as an SVC as may have been the case in earlier versions. An <code>INCLUDE</code> for the <code>M204XSVC</code> module is also added to the Online link-edit job by default as of version 7.5. </p>
 
<li>Concatenate the CRAM load library to the Online job, or use the <var>XDMSSN</var> parameter in the job's CCAIN so that the Online locates the XDM region.
<p>
If <var>XDMSSN</var> is not specified, the Online searches its load library for the CRAM IGCLM244 load module. This module contains the secondary subsystem name (SSN) with which CRAM  was installed. </p></li>
</ol></li>
 
<li>After the M204XDM job has initialized, run the Online job.
<p>
When the Online comes up, its audit trail reports the XDM subsystem to which it is connecting: </p>
<p class="code">AD ///  M204.2157: M204XSVC version = 7.7.0G  10/13/16
AD ///  IGCLM244 7.7.0G  10/13/16
AD ///  SUBSYSTEM NAME = V770 </p></li>
</ol>
 
====Monitoring XDM====
<p>
After CRAM-XDM is installed and the M204XDM job is up and running, you can monitor CRAM-XDM from the console or from a batch job.</p>
   
   
<tr>
<ul>
<td><p>128</p></td>
<li><b>Using console commands</b>
<td><p>Dumps XDM control blocks. </p></td>
<p>
</tr>
To monitor XDM, you can issue a <var>MONITOR</var> command. (Authorized users can also issue console commands from SDSF using the <code>/<i>nn</i> </code> syntax). When the XDM master address space is active, it displays the following reply message on the operator console:</p>
   
   
<tr>
<p class="syntax">*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
<td><p>64 </p></td>
</p>
<td><p>Interprets XDM control blocks. </p></td>
<p>
</tr>
Where:</p>
   
   
<tr>
<ul>
<td><p>2 </p></td>
<li><var class="term">nn</var> is the message number to reply to.</li>
<td><p>Lists XDM Online and user details. </p></td>
</tr>
   
   
<tr>
<li><var class="term">jobname</var> is the end-user-defined jobname running M204XDM.</li>
<td><p>1 </p></td>
</ul>
<td><p>Lists XDM summary information. </p></td>
</tr>
</table>
   
   
<p>  
<p>
If <code>DETAIL</code> is non-zero, the return code can be one of the following values: </p>
The following table lists the available <var>MONITOR</var> commands:</p>
   
   
<table>
<table class="thJustBold">
<tr class="head">
<caption>Available MONITOR commands</caption>
<th><p>Value</p></th>
<tr class="head"><th>Command</th>
<th><p>Meaning</p></th>
<th>Description</th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p> 0 </p></td>
<th>MONITOR<br><i>or</i><br>MONITOR,ONLINES<br><i>or</i><br>ONLINES</th>
<td><p>Completed normally. </p></td>
<td>Lists all Onlines connected to an XDM master; can be abbreviated:
<ul>
<li>M/MO/MON, and so on.</li>
<li>MONITOR,O/ON/ONL, and so on.</li>
<li>O/ON/ONL, and so on.</li>
</ul></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p> 4 </p></td>
<th>MONITOR,USERS<br><i>or</i><br>USERS</th>
<td><p> An error was found in XDM control blocks (this is not necessarily a real error; it can occur if a control block was being modified as M204XMON ran).  </p></td>
<td>Lists all jobs using XDM to connect to any Online; can be abbreviated: 
<ul>
<li>MONITOR,U/US/USE and so on.  </li>
<li>U/US/USE and so on.  </li>
</ul></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p> 8 </p></td>
<th>MONITOR,ONLINE=<i>jobname</i><br><i>or</i><br>ONLINE=<i>jobname</i> </th>
<td><p> Invalid parameter: CCAPRINT failed to open, and so on. </p></td>
<td>Lists all jobs using XDM to connect to the specified Online. </td>
</tr>
</tr>
</table>
</table>
   
   
<p>
<p>
If <code>DETAIL</code> is 0 (not usually used), the return code can be one of the following:  </p>
The output is sent to the z/OS console and CCAPRINT in the M204XDM job. If you want another report, issue another <var>MONITOR</var> command. The new output is also sent to the console and is appended to the existing CCAPRINT.  </p>
<p>
In the following display example, three jobs are using no XDM threads and three jobs are using a total of 12 XDM threads. The <code>CAT11C</code> job is using 4 XDM threads, and so on.</p>
   
   
<table>
<p class="code">M204XDM.313: XDM Master Jobname=CAT141A ACTIVE (Subsystem=CAT1)
<tr class="head">
_M204XDM.314:    Online Jobname=CAT108  Users=0
<th><p>Value</p></th>
_M204XDM.314:    Online Jobname=CAT11C  Users=4
<th><p>Meaning</p></th>
_M204XDM.314:    Online Jobname=CAT11S  Users=2
</tr>
_M204XDM.314:    Online Jobname=CAT112  Users=0
_M204XDM.314:    Online Jobname=CAT109  Users=6
_M204XDM.314:    Online Jobname=CAT102  Users=0
_M204XDM.318: (Totals)  Onlines=6  Users=12
</p>
<br></li>
   
   
<tr>
<li><b>Using a batch job</b>
<td><p> 0 </p></td>
<p>
<td><p> No XDM Onlines are active. </p></td>
To monitor XDM, use a standalone batch job, when: </p>
</tr>
<ul>
   
<li>You might not be authorized to issue console commands. </li>
<tr>
 
<td><p> 2 </p></td>
<li>You do not want voluminous <var>MONITOR</var> command output sent to the JES log of the XDM task, or to the console log. </li>
<td><p> XDM Onlines are active, but none have active users. </p></td>
 
</tr>
<li>You need to get additional information. The batch job provides options for more detailed reporting and you can dump the control blocks for problem diagnosis. </li>
</ul>
   
<p>  
Execute the [[#M204XMON|M204XMON]] report with the following JCL: </p>
<p class="code">//MON    EXEC  PGM=M204XMON,PARM='<i>parameter</i>'
//STEPLIB  DD  DSN=<i>your</i>.LOADLIB,DISP=SHR
//CCAPRINT DD  SYSOUT=* </p>
<p>
The output goes to CCAPRINT. Unless you request otherwise, no output is written to the operator console. </p>  
<p>
The <var class="term">parameter</var> argument string can be in one of the following forms: </p>
   
   
<tr>
<p class="syntax">SSNAME=<span class="term">ssss</span>,ONLINE=<span class="term">oooooooo</span>,DETAIL=<span class="term">nnn</span>,OUTPUT=CONSOLE </p>
<td><p> 3 </p></td>
<p>
<td><p> XDM Onlines are active, and some have active users. </p></td>
or:  </p>
</tr>
   
   
<tr>
<p class="syntax"><span class="term">ssss</span>
<td><p> 4 </p></td>
</p>
<td><p> 0C4 while processing XDM control blocks; retry. </p></td>
</tr>
</table></li>
</ul>


===Debugging XDM===
<p>Where: </p>
<p id="M204XMON">
The M204XMON utility is used to debug CRAM-XDM. You can run M204XMON with the parameters shown in the following JCL example:</p>
   
   
<p class="code">// Job Card...
<ul>
//JOBLIB  DD DSN=<i>Model204Cram</i>.LOADLIB,DISP=SHR
<li><var class="term">ssss</var> is the [[#xdmjob|CRAM z/OS subsystem name]] to report on (required). </li>
//XDMNC  EXEC PGM=M204XMON,PARM='SSNAME=<i>xxxx</i>,DETAIL=255'
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=A
/*
//
</p>
<p>
where <var class="term">xxxx</var> is the secondary subsystem name used by the CRAM-XDM region. </p>
   
   
<p id="SNAPCRAM">
<li><var class="term">oooooooo</var> is the Online name to report on (optional). If not specified, reports on all Onlines using XDM. </li>
The SNAPCRAM utility is the counterpart to M204XMON that is used to debug CRAM SVC. Example JCL follows:</p>
   
   
<p class="code">// Job Card...
<li><var class="term">nnn</var> specifies what to report (optional). If not specified, defaults to 3. </li>
//JOBLIB  DD DSN=<i>Model204Cram</i>.LOADLIB,DISP=SHR
//XDMNC  EXEC PGM=SNAPCRAM
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=A
/*
//
</p>
 
===Shutting down XDM master from the console===
<p>
Ordinarily you must keep the XDM master active: shut it down only prior to an IPL. You can shut it down by operator command. The <var>[[EOJ command|EOJ]]</var> command, which is the normal command used to terminate XDM, checks that all connections have been terminated and does not shut down if XDM Onlines are still active. When the XDM master address space is active, it displays the following reply message on the operator console: </p>
   
   
<p class="syntax"><b></b>*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
<li><code>CONSOLE</code> specifies that the report is sent to both the console and CCAPRINT (otherwise to CCAPRINT only). </li>
</p>
   
   
Where:
<li><code>DETAIL=<i>nnn</i></code> is the sum of the following values:
   
   
<ul>
<table>
<li><var class="term">nn</var> is the message number to reply to.  </li>
<tr class="head">
<li><var class="term">jobname</var> is an end-user defined job. </li>
<th>Value</th>
</ul>
<th>Purpose</th>
</tr>
   
   
=====Usage=====
<tr>
<p>
<td>128</td>
The following shutdown commands are available.</p>
<td>Dumps XDM control blocks. </td>
<p class="note"><b>Note:</b> None of these commands cleans up storage; the connection's closing must do the cleanup.</p>
<table class="thJustBold">
<tr class="head">
<th> Command </th>
<th> Shuts down XDM master... </th>
</tr>
</tr>
   
   
<tr>
<tr>
<th>EOJ </th>
<td>64 </td>
<td>If no Onlines are active.
<td>Interprets XDM control blocks. </td>
<p><var>EOJ</var> is only allowed if all connections are cleanly closed.</p></td>
</tr>
</tr>
   
   
<tr>
<tr>
<th>EOJ,CANCEL</th>
<td>2 </td>
<td>Even if Onlines are active. 
<td>Lists XDM Online and user details. </td>
<p><code>EOJ,CANCEL</code> leaves all connections in their current state. If a connection is properly closed at a later time, it becomes reusable; otherwise, attempting to use it results in an error message that the CRAM channel is already open.</p>
</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th>EOJ,FORCE</th>
<td>1 </td>
<td>Without cleaning up the cross-memory environment.
<td>Lists XDM summary information. </td>
<p><code>EOJ,FORCE</code> terminates XDM and orphans all storage. Any new XDM will allocate new control blocks and never check the old ones. This will normally clear any error messages that the CRAM channel is already open.</p></td>
</tr>
</tr>
</table>
</table>
   
   
<p>
<p>  
Usually you can terminate the M204XDM job via <var>EOJ</var> without using the <var>FORCE</var> option. However, when recycling the CRAM M204XDM job to apply maintenance from Rocket Software, you must follow the instruction in the Early Warning(s). There may be circumstances that require using the <var>FORCE</var> option or an IPL.</p>
If <code>DETAIL</code> is non-zero, the return code can be one of the following values:  </p>
   
   
<blockquote class="warn">
<table>
<p><b>Attention:</b> Use <code>EOJ,CANCEL</code> and <code>EOJ,FORCE</code> commands with extreme caution. Abnormal termination of XDM master might require an IPL in order for Model&nbsp;204 Online jobs to use cross-memory services or to reclaim orphaned CSA storage. </p>
<tr class="head">
<p>
<th>Value</th>
If you issue <code>EOJ,CANCEL</code> or <code>EOJ,FORCE</code> commands, any of the following events are possible:</p>
<th>Meaning</th>
<ul>
</tr>
<li>Active applications abend.</li>
<li>Active CRAM threads abend.</li>
<li><var class="product">Model&nbsp;204</var> Online termination abends.</li>
<li>CICS applications will ASRA.</li>
<li>CICS might abend at shutdown.</li>
</ul>
</blockquote>
 
<p class="note"><b>Note:</b> In certain situations, such as when the CRAM control block chains have become corrupted, even an <code>EOJ,FORCE</code> command might not be sufficient to clear a previous CRAM error when opening or using a channel. In this situation, if a system IPL is not imminent, then it might be possible to use the CRAMCLR utility to resolve the issue. However, this utility should be used with extreme care, and only under the guidance and advice of [[Contacting Rocket Software Technical Support|Rocket Technical Support]].</p>
 
===Working with CRAM===
<p>
If you want, multiple subsystem names (separate IGCLM244s) can be used to isolate CRAM-XDM from the current production CRAM environment.</p>
   
   
<p class="note"><b>Note:</b>
<tr>
CRAM-XDM requires a non-swappable address space, a system LX, and is recommended as non-cancelable.</p>
<td>0 </td>
<td>Completed normally. </td>
</tr>
   
   
====CRAM OPEN processing====
<tr>
<p>
<td>4 </td>
CRAM can operate in two modes: converser and master/user:</p>
<td>An error was found in XDM control blocks (this is not necessarily a real error; it can occur if a control block was being modified as M204XMON ran). </td>
<ul>
</tr>
<li> Converser mode is like a telephone conversation: either side can speak and one waits for the other if there is a conflict. IFAM applications use the converser mode.</li>
   
   
<li> Master/user is like half-duplex conversations: the end-user requests to speak and the <var class="product">Model&nbsp;204</var> Online (master) gives permission. The Online controls the entire conversation by telling the user what to do next. </li>
<tr>
</ul>
<td>8 </td>
<td>Invalid parameter: CCAPRINT failed to open, and so on.</td>
</tr>
</table>
   
   
<p>An Online makes CRAM communication possible by issuing a master <code>CRAM OPEN</code> command, specifying a channel name, a block size, and the number of connections (subchannels) available. The information needed to issue this <code>OPEN</code> is derived from parameters specified on User&nbsp;0's parameter line. Subsequently, <var class="product">Model&nbsp;204</var> applications can issue commands on a particular channel.</p>
====Communicating with multiple regions of Model 204====
<p>
<p>
You can communicate with several regions of <var class="product">Model&nbsp;204</var> concurrently by establishing a distinct CRAM channel name for each region. One IFDIAL remote User Language and several IFSTRT IFAM2 threads can communicate over a particular channel when the channel name is specified in the IFDIAL or IFSTRT call that establishes the connection. You must use one <var>IODEV</var> definition for each terminal.</p>
If <code>DETAIL</code> is 0 (not usually used), the return code can be one of the following:  </p>
   
   
<p>
<table>
CRAM channel names consist of 1 to 8 characters that are specified on the User 0 parameter line. Use the parameters shown in the [[#Default and alternate channel names|Default and alternate channel names]] table or those supplied as a default by <var class="product">Model&nbsp;204</var>.</p>
====CRAM channel names and parameters====
<p>
The following table shows CRAM channel names, parameters, and the calls that establish each type of connection:</p>
<table>
<caption>CRAM channel names and parameters</caption>
<tr class="head">
<tr class="head">
<th><p>IODEV setting</p></th>
<th>Value</th>
<th><p> Parameter</p></th>
<th>Meaning</th>
<th><p>Default name</p></th>
<th><p>Call to establish connection</p></th>
<th><p>For connection to...</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>11 </p></td>
<td>0 </td>
<td><p>CRFSCHNL</p></td>
<td>No XDM Onlines are active. </td>
<td><p>M204FULL </p></td>
<td><p>&nbsp;</p></td>
<td><p>&nbsp;</p></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>23</p></td>
<td>2 </td>
<td><p>IFAMCHNL</p></td>
<td>XDM Onlines are active, but none have active users.</td>
<td><p>IFAMPROD</p></td>
<td><p>IFAM2 IFSTRT</p>
<p>IFAM2 IFSTRTN </p></td>
<td><p>IFAMPROD channel</p>
<p>
Channel named on IFAMCHNL</p></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>29 </p></td>
<td>3 </td>
<td><p>CRIOCHNL </p></td>
<td>XDM Onlines are active, and some have active users.</td>
<td><p>M204PROD </p></td>
<td><p>IFAM2 IFDIAL</p>
<p>IFAM2 IFDIALN </p></td>
<td><p>M204PROD channel</p>
<p>Channel named on CRIOCHNL</p></td>
</tr>
</tr>
</table>
   
   
====Required parameter settings for IODEV=29====
<tr>
<td><p> 4 </p></td>
<td><p> 0C4 while processing XDM control blocks; retry. </p></td>
</tr>
</table></li>
</ul>
</li></ul>
====Debugging XDM====
The <code>M204XMON</code> utility is described above in [[#Debugging CRAM|Debugging CRAM]].
 
====Shutting down XDM master from the console====
<p>
<p>
The following parameter settings are required for IFDIAL protocol IFAM2 line-at-a-time thread (IODEV=29):   </p>
Ordinarily you must keep the XDM master active: shut it down only prior to an IPL. You can shut it down by operator command. The <var>[[EOJ command|EOJ]]</var> command, which is the normal command used to terminate XDM, checks that all connections have been terminated, and it does not shut down if XDM Onlines are still active. A <code>MONITOR,ONLINES</code> command ([[#Monitoring XDM|see above]]) lists on the operator console all address spaces that have connections to XDM. </p>
<p>
When the XDM master address space is active, it displays the following reply message on the operator console: </p>
   
   
<ul>
<p class="syntax"><b></b>*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
<li><var>INCCC</var> can be set to 0 or any setting up to <code>32K-4</code>.</li>
</p>
   
   
<li><var>INMRL</var> must be less than or equal to <code>LIBUFF-4</code>. <var>LIBUFF</var> can be set to any value up to 32K for the IFDIAL expanded communication buffer.</li>
Where:
   
   
<li><var>OUTCCC</var> can be set to 0 or any setting up to <code>32K-4</code>. It must not be larger than <var>OUTMRL</var>.</li>
<ul>
<li><var class="term">nn</var> is the message number to reply to. </li>
<li><var>OUTMRL</var> must be less than or equal to <code>LOBUFF-4</code>. <var>LOBUFF</var> can be set to any value up to 32K for the IFDIAL expanded communication buffer. An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.</li>
<li><var class="term">jobname</var> is an end-user defined job. </li>
<li>First user statement (POLLNO=1) must be set with the largest CRAM buffer size (<var>INMRL</var>, <var>OUTMRL</var>). The <code>CRAM OPEN</code> must be performed with the largest buffer size to be used. </li>
</ul>
</ul>
   
   
======Shutdown commands======
<p>
<p>
For general information about these parameters, see [[#User environment control parameters|User environment control parameters]].</p>
The following shutdown commands are available.</p>
 
<p class="note"><b>Note:</b> None of these commands cleans up storage; the connection's closing must do the cleanup.</p>
===Using CRAM on a z/OS operating system===
   
   
====CRAM storage requirements for z/OS====
<table class="thJustBold">
<p>
<tr class="head">
When a CRAM master opens a channel, space is allocated in the Common Service Area (CSA). You must allocate sufficient CSA space to allow the <var class="product">Model&nbsp;204</var> [[Host Language Interface (HLI)]] to operate.</p>
<th> Command </th>
<th> Shuts down XDM master... </th>
</tr>
   
   
<p>
<tr>
The next three sections give the formula for CSA space and explain buffer and ONLINE space allocation.</p>
<th>EOJ </th>
 
<td>If no Onlines are active.
====Calculating CSA space for HLI====
<p><var>EOJ</var> is only allowed if all connections are cleanly closed.</p></td>
<ul>  
</tr>
<li>CRAM SVC
<p>
The following calculation determines the approximate requirements for each active HLI/<var class="product">Model&nbsp;204</var> region:</p>
   
   
<p class="code">CSA Space = Min(<i>nif</i>,1) * (68 + (<i>nif</i> * (IFAMBS + 100)))
<tr>
+ Min(<i>nul</i>,1) * (68 + (<i>nul</i> * (Max(INMRL,OUTMRL) + 100)))
<th>EOJ,CANCEL</th>
+ Min(<i>nfs</i>,1) * (68 + (<i>nfs</i> * (LOUTPB + 100)))
<td>Even if Onlines are active. 
</p>
<p><code>EOJ,CANCEL</code> leaves all connections in their current state. If a connection is properly closed at a later time, it becomes reusable; otherwise, attempting to use it results in an error message that the CRAM channel is already open.</p>
<p>
</td>
Where:</p>
</tr>
   
   
<ul>
<tr>
<li>Min is the Minimum function.</li>
<th>EOJ,FORCE</th>
<td>Without cleaning up the cross-memory environment.
<p><code>EOJ,FORCE</code> terminates XDM and orphans all storage. Any new XDM will allocate new control blocks and never check the old ones. This will normally clear any error messages that the CRAM channel is already open.</p></td>
</tr>
</table>
   
   
<li>Max is the Maximum function.</li>
<li><var class="term">nif</var> is the number of IODEV=23 users.</li>
<li><var class="term">nul</var> is the number of IODEV=29 users.</li>
<li><var class="term">nfs</var> is the number of IODEV=11 users.</li>
<li>IFAMBS is the IFAM2 block size.
<p>
<p>
IFAMBS must be set between 2 to 5 times the value of <var>LIBUFF</var> or <var>LOBUFF</var>. (Most host language parameters are assumed to be <var>LIBUFF</var> long and to occupy a <var>LIBUFF</var> portion of <var>IFAMBS</var> during processing by the IFAM2 interface.)</p> </li>
Usually you can terminate the M204XDM job via <var>EOJ</var> without using the <var>FORCE</var> option. However, when recycling the CRAM M204XDM job to apply maintenance from Rocket Software, you must follow the instruction in the maintenance documentation. There may be circumstances that require using the <var>FORCE</var> option or an IPL.</p>
   
   
<li><var>LOUTPB</var> is the length of the output page buffer required for full-screen features. </li>
<blockquote class="warn">
</ul></li>
<p><b>Attention:</b> Use <code>EOJ,CANCEL</code> and <code>EOJ,FORCE</code> commands with extreme caution. Abnormal termination of the XDM master might require an IPL in order for Model&nbsp;204 Online jobs to use cross-memory services or to reclaim orphaned CSA storage. </p>
<li>CRAM-XDM
<p>
<p>
The following calculation determines the approximate requirements for each active XDM region:</p>
If you issue <code>EOJ,CANCEL</code> or <code>EOJ,FORCE</code> commands, any of the following events are possible:</p>
<p class="code">CSA Space = 1510 + 28 + (50 * <i>onln</i>) + (30 * <i>chnl</i>) + (60 * <i>cnct</i>) + (18 * <i>asid</i>) + <i>trace</i>
</p>
<p>
Where (the values shown are in hexadecimal):</p>
<ul>
<ul>
<li>1450 is the size of the XMEMCSA module (resident in CSA).</li>
<li>Active applications abend.</li>
<li>Active CRAM threads abend.</li>
<li>28 is the SSACB length.</li>
<li><var class="product">Model&nbsp;204</var> Online termination abends.</li>
<li>CICS applications will ASRA.</li>
<li><var class="term">onln</var> is the SSCB length.</li>
<li>CICS might abend at shutdown.</li>
<li><var class="term">chnl</var> is the IICB length.</li>
<li><var class="term">cnct</var> is the UICB length.</li>
<li><var class="term">asid</var> is the ASID table entry.</li>
<li><var class="term">trace</var> is the trace table (length default is 3K per channel).</li>
</ul>
</ul>
</blockquote>
<p class="note"><b>Note:</b>
 
Using CRAM-XDM, you need not calculate buffer spaces.</p></li>
<p class="note"><b>Note:</b> In certain situations, such as if the CRAM-XDM control block chains are corrupted, even an <code>EOJ,FORCE</code> command might not be sufficient to clear a previous CRAM error when opening or using a channel. In this situation, if a system IPL is not imminent, then it might be possible to use the <code>CRAMCLR</code> utility to resolve the issue. However, this utility should be used with extreme care, and only under the guidance and advice of [[Contacting Rocket Software Technical Support|Rocket Technical Support]].</p>
</ul>
 
===Using CRAM on a z/VSE operating system===
====z/OS CRAM buffer allocation====
<p>
<p>
For IODEV=29, the size of the CRAM buffer is the maximum of (<var>INMRL</var>, <var>OUTMRL</var>) + 4. If neither of these parameters is specified on the User 0 parameter line, the default of 256 bytes applies. </p>
In a z/VSE environment, CRAM lets users from other partitions communicate with <var class="product">Model&nbsp;204</var> Online systems. Two versions of CRAM routines are available with each copy of <var class="product">Model&nbsp;204</var>:</p>
   
   
<table>
<table>
<tr class="head">
<tr class="head">
<th><p>This parameter... </p></th>
<th>Version... </th>
<th><p>Determines the maximum length of data that...</p></th>
<th>Is compatible with...</th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>INMRL </p></td>
<td>Cross-Partition Event Control Blocks (XECB) </td>
<td><p>Can be transferred as input to <var class="product">Model&nbsp;204</var>. </p></td>
<td>Single-address-space mode of z/VSE, only.</td></tr>
</tr>
   
   
<tr>
<tr>
<td><p>OUTMRL </p></td>
<td nowrap>Cross-Partition Communications Services (XPCC) </td>
<td><p>Can be transferred as output from <var class="product">Model&nbsp;204</var>.</p></td>
<td>Both the single-address-space mode and the multiple-address-space mode of z/VSE. </td></tr>
</tr>
</table>
</table>
   
   
<p>
<p>
If an application program uses the extended communication buffer, you can set <var>INMRL</var> and <var>OUTMRL</var> up to 32K to accommodate it.</p>  
System requirements for the XECB and XPCC versions are explained in the following sections.</p>
====Performance====
<p>
<p>
CRAM buffers are allocated as users are activated. The minimum CSA usage, without active users, is 68 bytes per channel and 100 bytes per user as defined by the number of IODEV definitions of the same type. When the first user opens a thread, the associated CRAM buffer, sized by <var>IFAMBS</var>, <var>INMRL</var>, <var>OUTMRL</var>, and <var>LOUTPB</var> parameters, is allocated.</p>
To maximize performance of the CRAM subsystem: </p>
<ol>
<li>Place the CRAM Load Module and both the master and user subtask programs in the System Directory List (SDL). </li>
 
<li>Mark the CRAM Transient as a Move Mode transient in the SDL. </li>
</ol>
<p>
<p>
CRAM buffers are reusable and freed only when <var class="product">Model&nbsp;204</var> terminates.</p>
Neither the load module nor the subtasks are SVA eligible. Any attempt to place these modules in the SVA causes errors.</p>
   
   
====z/OS ONLINE space allocation====
====System requirements (XECB version)====
<p>
<p>
When ONLINE is initialized, the following space is allocated:</p>
The CRAM subsystem uses the Cross-Partition Event Control facilities of the z/VSE operating system. To compute the number of blocks (XECBs) required for the Cross-Partition Event Control:</p>
   
   
<p class="code">CSA Space = Min(<i>nif</i>,1) * (68 + (<i>nif</i> * 100))
<p class="code">number of XECBs = 5 * (C + N)
+ Min(<i>nul</i>,1) * (68 + (<i>nul</i> * 100))
+ Min(<i>nfs</i>,1) * (68 + (<i>nfs</i> * 100))
</p>
</p>
<p>
Where:
In addition, ONLINE allocates space in the <var class="product">Model&nbsp;204</var> address space based on the following formula:</p>
<ul>
<li>C is the number of nonmaster partitions concurrently using the facilities of CRAM.</li>
   
   
<p class="code">GETMAIN space = Min(<i>nif</i>,1) * 568
<li>N is the number of master partitions concurrently using the facilities of CRAM. </li>
+ Min(<i>nul</i>,1) * 568
</ul>
+ Min(<i>nfs</i>,1) * 568
+ 568 bytes allocated by each user program in its own address space.
</p>
   
   
====SNAPCRAM utility for z/OS====
<p>
<p>
SNAPCRAM is a program that prints out the CRAM control blocks in dump format. Sample JCL for running SNAPCRAM is:</p>
These requirements affect the specification of the <code>XECB</code> parameter of the z/VSE Supervisor Generation Macro FOPT for releases of z/VSE prior to 1.3.0. Refer to the IBM DOS/z/VSE System Generation Manual for a further discussion of Cross-Partition Event Control Blocks.</p>
   
   
<p class="code">//SNAPCRAM EXEC PGM=SNAPCRAM
====Partition requirements====
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//        DD DSN=M204.CRAMLIB,DISP=SHR
//CCASNAP DD SYSOUT=A
</p>
<p>
<p>
If CRAM is installed in a separate library, the M204.CRAMLIB concatenation shown above is required.</p>
The entire CRAM subsystem runs in the partition GETVIS area of each partition that uses the facilities of CRAM:</p>
<ul>
<li>Each master partition has a copy of the phase IGCLM244 and the master subtask CRAMZWT. </li>
 
<li>Each nonmaster partition has a copy of the phase IGCLM244 and the nonmaster subtask CRAMSWT. </li>


===Using CRAM on a z/VSE operating system===
<li>If a partition is both a master and a nonmaster, it has only one copy of the phase and one copy of the master and nonmaster subtasks. </li>
</ul>
<blockquote class="note">
<p><b>Note:</b> The storage requirements given do not include buffer storage (one I/O buffer per thread). Buffer sizes are:</p>
<p class="code">MAX (INMRL,OUTMRL)  for IODEV=29
IFAMBS              for IODEV=23
LFSCB              for IODEV=11
</p>
</blockquote>
====Calculating partition requirements====
<p>
Total storage requirements consist of fixed and variable storage. </p>
<p>
<p>
In a z/VSE environment, CRAM lets users from other partitions communicate with <var class="product">Model&nbsp;204</var> Online systems. Two versions of CRAM routines are available with each copy of <var class="product">Model&nbsp;204</var>:</p>
Fixed storage requirements are as follows:</p>
   
   
<table>
<table>
<caption>Fixed storage requirements</caption>
<tr class="head">
<tr class="head">
<th><p>Version... </p></th>
<th>Fixed storage area</th>
<th><p>Is compatible with...</p></th>
<th>XECB version (bytes)</th>
<th>XPCC version (bytes)</th>
</tr>
<tr>
<td>CRAM phase </td>
<td>2560 </td>
<td>3072</td>
</tr>
<tr>
<td>CRAM master subtask</td>
<td>13264 </td>
<td>22144</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>Cross-Partition Event Control Blocks (XECB) </p></td>
<td>CRAM nonmaster </td>
<td><p>Single-address-space mode of z/VSE, only.</p></td>
<td>13264</td>
<td>19840</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td nowrap><p>Cross-Partition Communications Services (XPCC) </p></td>
<td>TOTAL</td>
<td><p>Both the single-address-space mode and the multiple-address-space mode of z/VSE. </p></td>
<td>29088</td>
<td>45056</td>
</tr>
</tr>
</table>
</table>
   
   
<p>
<p>
System requirements for the XECB and XPCC versions are explained in the following sections.</p>
Variable storage requirements, represented schematically, follow: </p>
   
   
====Performance====
<table>
<p>
<caption>Variable storage requirements</caption>
To maximize performance of the CRAM subsystem: </p>
<tr class="head">
<ol>
<th>Variable storage area</th>
<li>Place the CRAM Load Module and both the master and user subtask programs in the System Directory List (SDL). </li>
<th>Bytes</th>
 
</tr>
<li>Mark the CRAM Transient as a Move Mode transient in the SDL. </li>
</ol>
<p>
Neither the load module nor the subtasks are SVA eligible. Any attempt to place these modules in the SVA causes errors.</p>
   
   
====System requirements (XECB version)====
<tr>
<p>
<td>Subtask communications area </td>
The CRAM subsystem uses the Cross-Partition Event Control facilities of the z/VSE operating system. To compute the number of blocks (XECBs) required for the Cross-Partition Event Control:</p>
<td>A</td>
</tr>
   
   
<p class="code">number of XECBs = 5 * (C + N)
<tr>
</p>
<td>Master channel storage</td>
Where:
<td>B</td>
</tr>
   
   
<ul>
<tr>
<li>C is the number of nonmaster partitions concurrently using the facilities of CRAM.</li>
<td>User (nonmaster) channel storage </td>
<td>C</td>
</tr>
   
   
<li>N is the number of master partitions concurrently using the facilities of CRAM. </li>
<tr>
</ul>
<td>TOTAL</td>
<td>A + B + C</td>
</tr>
</table>
   
   
====Sizing the subtask communications area====
<p>
<p>
These requirements affect the specification of the <code>XECB</code> parameter of the z/VSE Supervisor Generation Macro FOPT for releases of z/VSE prior to 1.3.0. Refer to the IBM DOS/z/VSE System Generation Manual for a further discussion of Cross-Partition Event Control Blocks.</p>
One subtask communications area is required for each subtask running in the partition. If one program is both a master and nonmaster CRAM user, then both subtasks are present in the partition. </p>
   
   
====Partition requirements====
<ul>
<li>In the XECB version:
<p>
<p>
The entire CRAM subsystem runs in the partition GETVIS area of each partition that uses the facilities of CRAM:</p>
The size of each communications area (A) is:</p>
<p class="code">A = <i>n</i> * 128
</p>
<p>Where:</p>
   
   
<ul>
<ul>
<li> Each master partition has a copy of the phase IGCLM244 and the master subtask CRAMZWT. </li>
<li><var class="term">n</var> is <code>(652 + (112 * (<i>nparts</i> - 1)))/128</code>, rounded up to the next integer.  
 
<p>
<li> Each nonmaster partition has a copy of the phase IGCLM244 and the nonmaster subtask CRAMSWT. </li>
<var class="term">nparts</var> is the number of partitions in the z/VSE system. Round all totals up to the next higher integer.</p></li>
 
<li> If a partition is both a master and a nonmaster, it has only one copy of the phase and one copy of the master and nonmaster subtasks. </li>
</ul>
</ul>
   
   
<blockquote class="note">
<p>
<p><b>Note:</b> The storage requirements given do not include buffer storage (one I/O buffer per thread). Buffer sizes are:</p>
For example, if <var class="term">nparts</var> in the z/VSE system is 8, the computation is:</p>
   
   
<p class="code">MAX (INMRL,OUTMRL) for IODEV=29
<p class="code">n = (652 + (112 * (8 -1)))/128, rounded up to next integer
IFAMBS              for IODEV=23
n = (11.2) = 12
LFSCB              for IODEV=11
A = 12 * 128 = 1536 = Subtask Communication Area
</p>
</p></li>
</blockquote>
   
   
====Calculating partition requirements====
<li>In the XPCC version:
<p>
<p>
Total storage requirements consist of fixed and variable storage. </p>
The size of each communications area (A) is:</p>
   
   
<p>
<p class="code">A = m * 768
Fixed storage requirements are as follows:</p>
</p>
<p>Where <var class="term">m</var> is the number of subtask communications areas. <var class="term">m</var> has the value of 1 for each subtask. For example:</p>
   
   
<table>
<table>
<caption>Fixed storage requirements</caption>
<tr class="head">
<tr class="head">
<th><p>Fixed storage area</p></th>
<th>If the program is...</th>
<th><p>XECB version (bytes)</p></th>
<th>Value of m is...</th>
<th><p>XPCC version (bytes)</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>CRAM phase </p></td>
<td>CRAM master or a CRAM nonmaster</td>
<td><p>2560 </p></td>
<td>1</td>
<td><p>3072</p></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>CRAM master subtask</p></td>
<td>Both a CRAM master and a CRAM nonmaster</td>
<td><p>13264 </p></td>
<td>2</td>
<td><p>22144</p></td>
</tr>
<tr>
<td><p>CRAM nonmaster </p></td>
<td><p>13264</p></td>
<td><p>19840</p></td>
</tr>
<tr>
<td><p>TOTAL</p></td>
<td><p>29088</p></td>
<td><p>45056</p></td>
</tr>
</tr>
</table>
</table>
</li>
</ul>
   
   
====Sizing channel storage====
<ul>
<li>In the XECB version:
<p>
<p>
Variable storage requirements, represented schematically, follow: </p>
For each master channel that is opened by a program, an Internal Interregional Control Block (IICB) is created. To compute the amount of storage required for each IICB (I):</p>
   
   
<table>
<p class="code">I = <i>i</i> * 128
<caption>Variable storage requirements</caption>
</p>
<tr class="head">
<p>
<th><p>Variable storage area</p></th>
where <var class="term">i</var> is <code>(32 + (40 * number of threads))/128</code>, rounded up to the next integer.
<th><p>Bytes</p></th>
</p>
</tr>
<p>
For example, if the number of master channels being opened is 3, and the channels have 4, 5, and 2 threads, respectively, the computation is:</p>
   
   
<tr>
<p class="code">Channel 1
<td><p>Subtask communications area </p></td>
i = ((32 + (40 * 4))/128) rounded up to next integer
<td><p>A</p></td>
i = rounded up (1.5) = 2
</tr>
I = 2 * 128 = 256
   
   
<tr>
Channel 2
<td><p>Master channel storage</p></td>
i = ((32 + (40 * 5))/128) rounded up to next integer
<td><p>B</p></td>
i = rounded up (1.8) = 2
</tr>
I = 2 * 128 = 256
   
   
<tr>
Channel 3
<td><p>User (nonmaster) channel storage </p></td>
i = ((32 + (40 * 2))/128) rounded up to next integer
<td><p>C</p></td>
i = rounded up (0.8) = 1
</tr>
I = 1 * 128 = 128
</p>
<tr>
<td><p>TOTAL</p></td>
<td><p>A + B + C</p></td>
</tr>
</table>
====Sizing the subtask communications area====
<p>
<p>
One subtask communications area is required for each subtask running in the partition. If one program is both a master and nonmaster CRAM user, then both subtasks are present in the partition. </p>
The sum of the values of I (640 bytes) calculated for each channel is the total channel storage requirement.</p></li>
   
   
<ul>
<li>In the XPCC version:
<li>In the XECB version:
<p>
<p>
The size of each communications area (A) is:</p>
For each channel opened in the master environment, the storage requirement is:</p>
   
   
<p class="code">A = <i>n</i> * 128
<p class="code">B = (p + t + 1) * 128 bytes
</p>
</p>
<p>Where:</p>
<p>where:</p>
   
   
<ul>
<ul>
<li><var class="term">n</var> is <code>(652 + (112 * (<i>nparts</i> - 1)))/128</code>, rounded up to the next integer.  
<li><var class="term">p</var> is <code>(160 + 40 * t)/128</code>, rounded up to the next highest integer. </li>
<p>
<var class="term">nparts</var> is the number of partitions in the z/VSE system. Round all totals up to the next higher integer.</p></li>
<li><var class="term">t</var> is the number of threads in the channel.</li>
</ul>
</ul>
   
   
<p>
<p>
For example, if <var class="term">nparts</var> in the z/VSE system is 8, the computation is:</p>
The storage requirement for each nonmaster thread is 256 bytes. The total storage requirement is computed by:</p>
   
   
<p class="code">n = (652 + (112 * (8 -1)))/128, rounded up to next integer
<p class="code">C = 256 * <i>t</i> bytes
n = (11.2) = 12
A = 12 * 128 = 1536 = Subtask Communication Area
</p></li>
</p></li>
</ul>
   
   
<li>In the XPCC version:
====SNAPCRAM utility for z/VSE====
<p>
<p>
The size of each communications area (A) is:</p>
The following JCL statements are required to execute the SNAPCRAM utility:</p>
   
   
<p class="code">A = m * 768
<p class="code">//JOB SNAPCRAM
//DLBL M204LIB,'M204.PROD.LIBRARY'
//EXTENT SYS<i>nnn</i>,...
//LIBDEF PHASE,SEARCH=M204LIB.V411
//EXEC SNAPCRAM,SIZE=AUTO
/&amp;
</p>
</p>
<p>Where <var class="term">m</var> is the number of subtask communications areas. <var class="term">m</var> has the value of 1 for each subtask. For example:</p>
<p>
SNAPCRAM interacts with the operator in the following way:</p>
   
   
<table>
<ol>
<tr class="head">
<li> As part of its initialization process, the utility asks for a command with an <code>ENTER COMMAND</code> prompt on the console. Enter one of the following SET commands:
<th><p>If the program is...</p></th>
<th><p>Value of m is...</p></th>
</tr>
   
   
<tr>
<ul>
<td><p>CRAM master or a CRAM nonmaster</p></td>
<li>XECB version: <p class="code">SET COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p>
<td><p>1</p></td>
</tr>
<tr>
<td><p>Both a CRAM master and a CRAM nonmaster</p></td>
<td><p>2</p></td>
</tr>
</table>
</li>
</li>
<li>XPCC version: <p class="code">SET NAME=<i>channel</i>,COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p> </li>
</ul>
</ul>
   
   
====Sizing channel storage====
Where:
<ul>  
<li>In the XECB version:
<table>
<tr>
<th>channel</th>
<td>One of the active ONLINE system channel names for which a SNAP dump is requested.</td>
</tr>
<tr>
<th>nnn</th>
<td>Number of dumps requested. The default is 1 dump.</td>
</tr>
<tr>
<th>iii </th>
<td>Time interval between dumps (in seconds). The default is 5 seconds. </td>
</tr>
</table>
<p>
<p>
For each master channel that is opened by a program, an Internal Interregional Control Block (IICB) is created. To compute the amount of storage required for each IICB (I):</p>
<code>NAME</code>, <code>COUNT</code>, and <code>INTERVAL</code> can be abbreviated to <code>N</code>, <code>C</code>, and <code>I</code>.</p>
   
   
<p class="code">I = <i>i</i> * 128
</p>
<p>
<p>
where <var class="term">i</var> is <code>(32 + (40 * number of threads))/128</code>, rounded up to the next integer.
<code>SET</code> is useful for tracing CRAM control blocks when CRAM is not in a soft wait state. </p>
</p>
<p>
<p>
For example, if the number of master channels being opened is 3, and the channels have 4, 5, and 2 threads, respectively, the computation is:</p>
<code>RUN</code> is issued after SET and begins the dump. </p>
   
   
<p class="code">Channel 1
<p>
i = ((32 + (40 * 4))/128) rounded up to next integer
<code>STOP</code> terminates the SNAPCRAM operation. </p></li>
i = rounded up (1.5) = 2
I = 2 * 128 = 256
   
   
Channel 2
<li>After the specified number of dumps has been produced, SNAPCRAM redisplays <code>ENTER COMMAND</code>.
i = ((32 + (40 * 5))/128) rounded up to next integer
i = rounded up (1.8) = 2
I = 2 * 128 = 256
   
   
Channel 3
<p>
i = ((32 + (40 * 2))/128) rounded up to next integer
To interrupt the dump, issue the z/VSE <code>MSG <i>pp</i></code> command, where <var class="term">pp</var> is the SYSLOG ID of the partition in which SNAPCRAM is running. The <code>ENTER COMMAND</code> prompt is displayed after the interruption.</p>
i = rounded up (0.8) = 1
</li>
I = 1 * 128 = 128
</ol>
 
===CRAM IFSTRT IFAM2 (IODEV=23) requirements===
<p>
[[HLI: Job design factors#IFAM2|IFAM2]] is a <var class="product">Model&nbsp;204</var> Host Language Interface (HLI) facility  that supports host language calls to a <var class="product">Model&nbsp;204</var> Online from one or more user-written, host language programs. The host languages supported are COBOL, FORTRAN, PL/I, ASSEMBLER, or C. The user-written programs normally run as separate jobs in other regions or partitions, and they connect through the CRAM-SVC or CRAM-XDM to a Model&nbsp;204 Online for database access. Each user program must be linked with a small interface module (IFIF) to enable communication between the user program and the Model&nbsp;204 Online region.
</p>
</p>
<p>
<p>
The sum of the values of I (640 bytes) calculated for each channel is the total channel storage requirement.</p></li>
Each IFAM2 (IFSTRT) HLI thread is defined by an <code>IODEV=23</code> line in the CCAIN input stream of the Model&nbsp;204 Online.</p>
   
   
<li>In the XPCC version:
=====In a z/OS environment=====
<p>
<ul>
For each channel opened in the master environment, the storage requirement is:</p>
<li> Communication between IFAM2 and user-written host language programs requires CRAM.</li>
 
<p class="code">B = (p + t + 1) * 128 bytes
<li> Support for [[HLI: IFAM2 CICS processing|IFAM2 and CICS]] is provided. Host language applications can run in 31-bit addressing mode.
</p>
</li>
<p>where:</p>
</ul>
   
   
=====In a z/VSE environment=====
<ul>
<ul>
<li><var class="term">p</var> is <code>(160 + 40 * t)/128</code>, rounded up to the next highest integer. </li>
<li> IFAM2 requires CRAM for the transfer of data and commands between the Online configuration in another z/VSE partition and the user program.</li>
<li><var class="term">t</var> is the number of threads in the channel.</li>
</ul>
</ul>
   
   
<p>
<p>
The storage requirement for each nonmaster thread is 256 bytes. The total storage requirement is computed by:</p>
The partition in which IFAM2 application programs are run must have access to a core image library containing the modules IGCLM244 and CRAMSWT.</p>
   
   
<p class="code">C = 256 * <i>t</i> bytes
<ul>
</p></li>
<li> You must initialize the Online program with one IODEV=23 for each concurrent IFAM2 thread in use.</li>
 
<li> For database files accessed by the IFAM2 program, you must provide label information in the JCL that executes the Online program with which the IFAM2 program is communicating. </li>
</ul>
</ul>
   
   
====SNAPCRAM utility====
====Multiple Online copies on a single system====
<p>
<p>
The following JCL statements are required to execute the SNAPCRAM utility:</p>
When running multiple Onlines concurrently, you access a specific Online by defining an alternate channel name for that Online and specifying the name in an IFAM CALL. Concurrently operating Onlines require different names for their CRAM channels. If duplicate channel names are used, the second version's job is terminated with a job step return code of 96. </p>
<p>
The "Default and alternate channel names" table in the [[#Communicating with multiple regions of Model 204|Communicating with multiple regions of Model 204]] section shows the default CRAM channel names and how to establish a connection using an alternate channel name.
</p>
   
   
<p class="code">//JOB SNAPCRAM
====CICS Interface====
//DLBL M204LIB,'M204.PROD.LIBRARY'
For information about CICS and IODEV 23 threads, see [[HLI:  Job requirements#IFAM2 jobs: Running under CICS|IFAM2 jobs: Running under CICS]].
//EXTENT SYS<i>nnn</i>,...
 
//LIBDEF PHASE,SEARCH=M204LIB.V411
===CRAM IFDIAL IFAM2 (IODEV=29) parameters===
//EXEC SNAPCRAM,SIZE=AUTO
/&amp;
</p>
<p>
<p>
SNAPCRAM interacts with the operator in the following way:</p>
The following parameter settings are required for IFDIAL protocol IFAM2 line-at-a-time threads (<code>IODEV=29</code>). For general information about these parameters, see [[#User environment control parameters|User environment control parameters]]. For more information about IFDIAL IFAM2 and CRAM, see [[HLI: Job requirements#IFAM2 jobs|IFAM2 jobs]]. </p>
<ol>
<li> As part of its initialization process, the utility asks for a command with an <code>ENTER COMMAND</code> prompt on the console. Enter one of the following SET commands:
   
   
<ul>
<ul>
<li>XECB version: <p class="code">SET COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p>
<li><var>INCCC</var> can be set to 0 or any setting up to <code>32K-4</code>.</li>
</li>
 
<li>XPCC version: <p class="code">SET NAME=<i>channel</i>,COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p> </li>
</ul>
   
   
Where:
<li><var>INMRL</var> must be less than or equal to <code>LIBUFF-4</code>. <var>LIBUFF</var> can be set to any value up to 32K for the IFDIAL expanded communication buffer.</li>
   
   
<table>
<li><var>OUTCCC</var> can be set to 0 or any setting up to <code>32K-4</code>. It must not be larger than <var>OUTMRL</var>.</li>
<tr>
<th>channel</th>
<td>One of the active ONLINE system channel names for which a SNAP dump is requested.</td>
</tr>
   
   
<tr>
<li><var>OUTMRL</var> must be less than or equal to <code>LOBUFF-4</code>. <var>LOBUFF</var> can be set to any value up to 32K for the IFDIAL expanded communication buffer. An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.</li>
<th>nnn</th>
<td>Number of dumps requested. The default is 1 dump.</td>
</tr>
   
   
<tr>
<li>First user statement (<code>POLLNO=1</code>) must be set with the largest CRAM buffer size (<var>INMRL</var>, <var>OUTMRL</var>). The <code>CRAM OPEN</code> must be performed with the largest buffer size to be used. </li>
<th>iii </th>
</ul>
<td>Time interval between dumps (in seconds). The default is 5 seconds. </td>
 
====CICS Interface====
For information about CICS and IODEV 23 threads, see [[HLI:  Job requirements#IFAM2 jobs: Running under CICS|IFAM2 jobs: Running under CICS]].
 
==SQL server threads (IODEV=19)==
<p>
<var class="product">Model&nbsp;204</var> requires a pool of threads to support server control of Horizon SQL connections. The system manager must define these threads in the CCAIN stream as part of the Online startup configuration.</p>
<table>
<tr class="head">
<th><p>IODEV </p></th>
<th><p>Defines thread for...</p></th>
<th><p>You must define this thread for... </p></th>
</tr>
<tr>
<td><p>19 </p></td>
<td><p><var class="product">Model&nbsp;204</var> SQL Horizon</p></td>
<td><p>All Connect<span class="superstar">&#9733;</span> configurations. </p></td>
</tr>
</tr>
</table>
</table>
   
   
<p>
<p>
<code>NAME</code>, <code>COUNT</code>, and <code>INTERVAL</code> can be abbreviated to <code>N</code>, <code>C</code>, and <code>I</code>.</p>
You have the opportunity to try up to two IODEV 19 threads without additional expense. If you want additional threads, please notify [[Contacting Rocket Software Technical Support|Technical Support]].</p>
   
   
<p>
<p>
<code>SET</code> is useful for tracing CRAM control blocks when CRAM is not in a soft wait state. </p>
For complete information on <var class="product">Model&nbsp;204</var> SQL system management, including SQL catalog and procedure file maintenance, SQL parameters and statistics, and processgroup definitions, see the [[:Category: Model 204 SQL processing|Model 204 SQL processing]] topics.</p>
   
   
===Coding the IODEV=19 line===
<p>
<p>
<code>RUN</code> is issued after SET and begins the dump. </p>
Defining the IODEV=19 thread requires specifying or changing the following parameters. For an example of the specification of an IODEV=19 line, see [[#Example for z/VM|Example for z/VM]]. </p>
<p class="note"><b>Note:</b> Define these as the last IODEV in your CCAIN as some of the parameters could have an affect on other IODEV threads.</p>
   
   
====NOTHREAD====
<p>
<p>
<code>STOP</code> terminates the SNAPCRAM operation. </p></li>
You can insert several IODEV=19 lines in the CCAIN stream. On the first line defining the SQL thread, include the <var>[[NOTHREAD parameter|NOTHREAD]]</var> parameter to indicate the number of SQL threads to be allocated. Set NOTHREAD to the number of concurrent Connect<span class="superstar">&#9733;</span> conversations to be supported. </p>
<li>After the specified number of dumps has been produced, SNAPCRAM redisplays <code>ENTER COMMAND</code>.
   
   
====SQLBUFSZ====
<p>
<p>
To interrupt the dump, issue the z/VSE <code>MSG <i>pp</i></code> command, where <var class="term">pp</var> is the SYSLOG ID of the partition in which SNAPCRAM is running. The <code>ENTER COMMAND</code> prompt is displayed after the interruption.</p>
<var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var> is a required resettable User 0 parameter that corresponds to the size of the <var class="product">Model&nbsp;204</var> SQL Server buffer that assembles incoming SQL messages from a receiving buffer (in CRAM, IUCV, or Horizon). The <var>SQLBUFSZ</var> value defines the maximum length of an incoming SQL message.</p>  
</li>
</ol>
 
==CRAM IFSTRT protocol IFAM2 (IODEV=23) requirements==
<p>
<p>
IFAM2 is a multithread configuration of <var class="product">Model&nbsp;204</var> that supports host language calls to the Host Language Interface (HLI) from one or more user programs. The user programs normally run as separate jobs in other regions or partitions and share a single copy of the database management system software. Each user program must have a small interface module linked in its region to enable communication between the user program and the IFAM2 region through a special interregional supervisor call.</p>
Because the largest incoming SQL message is likely to be a DDL transaction, set <var>SQLBUFSZ</var> large enough to accommodate your largest DDL transaction plus 50 bytes of overhead. You can also monitor the <var class="product">Model&nbsp;204</var> SQLI statistic to determine the size of the largest SQL input request. </p>
<p>
<p>
The concept of a Host Language Interface thread corresponds to that of an Online user for ONLINE. As with an Online user, each Host Language Interface thread is defined by a user's parameter line in the CCAIN input stream.</p>
The recommended initial value for this parameter is 100000. Specify it on the first IODEV=19 line. </p>
   
   
=====In a z/OS environment=====
====INMRL====
<ul>
<p>
<li> Communication between IFAM2 and user-written host language programs requires CRAM.</li>
<var>[[INMRL parameter|INMRL]]</var> is a user parameter that determines the maximum input line length for an I/O device as well as the maximum length of an internal <var class="product">Model&nbsp;204</var> buffer. You must set <var>INMRL</var> to a value greater than or equal to 500 (characters) for z/OS IODEV 19 threads. Specify it on the first IODEV=19 line. </p>
<li> Support for IFAM2 and CICS is provided. Host language applications can run in 31-bit addressing mode.
<p>
</li>
Processing complex SQL statements might require a larger <var>INMRL</var> setting. If the <var>INMRL</var> buffer capacity is exceeded, you get the <var class="product">Model&nbsp;204</var> error message:</p>
</ul>
   
   
=====In a z/VSE environment=====
<p class="code">INVALID STRING ARGUMENT
<ul>
</p>
<li> IFAM2 requires CRAM for the transfer of data and commands between the ONLINE configuration in another z/VSE partition and the user program.</li>
<p>
</ul>
Increase <var>INMRL</var> by 50% and rerun your request.</p>
   
   
====NSUBTKS====
<p>
<p>
The partition in which IFAM2 application programs are run must have access to a core image library containing the modules IGCLM244 and CRAMSWT.</p>
Increase the User 0 <var>[[NSUBTKS parameter|NSUBTKS]]</var> parameter by 3 per open Horizon link for Connect<span class="superstar">&#9733;</span> processing.</p>
   
   
<ul>
====SQLIQBSZ====
<li> You must initialize the ONLINE program with one IODEV=23 for each concurrent IFAM2 thread in use.</li>
<p>
<li> For database files accessed by the IFAM2 program, you must provide label information in the JCL that executes the ONLINE program with which the IFAM2 program is communicating. </li>
The user parameter <var>[[SQLIQBSZ parameter|SQLIQBSZ]]</var> determines the size in bytes of the internal buffer used to compile and evaluate SQL requests. </p>
</ul>
===Multiple Online copies on a single system===
<p>
<p>
When running multiple Onlines concurrently, you access a specific Online by defining an alternate channel name for that Online and specifying the name in an IFAM CALL. Concurrently operating Onlines require different names for their CRAM channels. If duplicate channel names are used, the second version's job is terminated with a job step return code of 96. The [[#Default and alternate channel names|Default and alternate channel names]] table shows the default channel name and how to define an alternate channel name.</p>
The minimum value is 2032; the maximum is 32752. The maximum setting (large enough for a 250-column table with an average column length of 30 bytes) is sufficient for most SQL applications.</p>
   
   
<table>
===Example for z/VM===
<caption>Default and alternate channel names</caption>
<tr class="head">
<th><p>IODEV=</p></th>
<th><p>Access method</p></th>
<th><p>Default channel name</p></th>
<th><p>Defines an alternate channel name with...</p> </th>
</tr>
<tr>
<td><p>11 </p></td>
<td><p>Full-screen</p></td>
<td><p>M204FULL</p></td>
<td><p>CRFSCHNL parameter on the User 0 parameter line.</p></td>
</tr>
<tr>
<td><p>23</p></td>
<td><p>IFSTRT protocol IFAM2 threads</p></td>
<td><p>IFAMPROD </p>
<p>For CICS transactions: M204</p>
<p>&nbsp;</p></td>
<td><p>IFAMCHNL parameter on the User 0 parameter line.</p>
<p>
<p>
To access the <var class="product">Model&nbsp;204</var> version, call IFSTRTN and specify the alternate channel name.</p>
The following example shows the CCAIN data stream for a z/VM job that brings up a <var class="product">Model&nbsp;204</var> Online for SQL processing. This example shows sample settings of some of the CCAIN parameters described earlier in this chapter, the first two IODEV lines for each SQL IODEV, and <var class="product">Model&nbsp;204</var> SQL DEFINE commands.   </p>
<p>
For more information about IFSTRTN, see the <var class="book">Rocket Model 204 Host Language Interface Reference Manual</var>.</p></td>
</tr>
   
   
<tr>
<p class="code">... LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760,
<td><p>29 </p></td>
LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300,
<td>
MINBUF=18,MAXBUF=200,NSUBTKS=15,...
<p>
SERVSIZE=700000,...
IFDIAL protocol IFAM2, line-at-a-time</p></td>
    .
<td><p>M204PROD</p></td>
    .
<td><p>
    .
CRIOCHNL parameter on the User 0 parameter line. </p>
IODEV=49,POLLNO=1,NOTHREAD=4
<p>To access the <var class="product">Model&nbsp;204</var> version, call
IODEV=49,POLLNO=2
IFDIALN and specify the alternate channel name. </p>
IODEV=49,POLLNO=3
IODEV=49,POLLNO=4
<p>
IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, -
For more information about IFDIALN, see the <var class="book">Rocket Model 204 Host Language Interface Reference Manual</var>.</p></td>
LIBUFF=6048,SQLIQBSZ=32752
</tr>
IODEV=19,POLLNO=2
</table>
IODEV=19,POLLNO=3
IODEV=19,POLLNO=4
===TSO Interface===
<b></b>* above IODEV=49 is for RCL connections
<p>
<b></b>* above IODEV=19 is for SQL CONNECT* connections
For the TSO Interface, specify an alternate channel name when the terminal connection is made to <var class="product">Model&nbsp;204</var>:</p>
<b></b>*-------------------------------------------------------* /
<b></b>*  DEFINE CONNECT * SQL AND RCL LINK ETC...            *  /
<ul>
<b></b>*-------------------------------------------------------/
<li>If TSO is installed as a command processor (CP), invoke <var class="product">Model&nbsp;204</var> as follows:
<b></b>**********************************************
   
DEFINE LINK TCPSQL WITH SCOPE=SYSTEM TRANSPORT=TCPSE -
<p class="syntax">M204FS [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=11)
  PROTOCOL=IP LOCALID=ANY INBUFSIZE=4096 CONNECTIONS=8 -
M204TTY [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=29)
  SERVPORT=2132
M204PROD [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=29)
DEFINE PROCESSGROUP ANY192  WITH SCOPE=SYSTEM LINK=TCPSQL -
M204FULL [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=11)
  INLIMIT=8 OUTLIMIT=8 REMOTEID=192.0.0.0  LOGIN=NOTRUST  -
</p>
  GUESTUSER=REJECT  MASK=255.0.0.0
<p>
DEFINE PROCESSGROUP ANY204  WITH SCOPE=SYSTEM LINK=TCPSQL -
<var>M204FULL</var> is the default.</p></li>
  INLIMIT=8 OUTLIMIT=8 REMOTEID=204.0.0.0  LOGIN=NOTRUST  -
   
  GUESTUSER=REJECT MASK=255.0.0.0
<li>If TSO is not installed as a CP, invoke <var class="product">Model&nbsp;204</var> as follows:
DEFINE PROCESS CCARSQL WITH SCOPE = SYSTEM -
   
DATALEN = 32763 FROM = (ANY192, ANY204)
<p class="syntax">[M204FS]
<b></b>********************************************************
CALL '<span class="term">library-name</span>' [(M204TTY)|(M204FULL)|(M204PROD)] '[<span class="term">subsystem</span>:]<span class="term">channel-name</span>'
</p>
</p>
==Horizon (IODEV=27)==
<p>
<p>
Where:</p>
Horizon, the <var class="product">Model&nbsp;204</var> distributed application facility, enables <var class="product">Model&nbsp;204</var> applications to participate in program-to-program processing by communicating through SNA Communications Server with one or more other programs.
The applications communicate over SNA LU 6.2 sessions (with a partner application that can run in the same or in a different computer) in a logical connection called a conversation.
<table>
Support for such conversations is configured primarily by <var class="product">Model&nbsp;204</var> DEFINE commands and is fully described in [[Model 204 intersystem processing]] and other [[:Category: Horizon|Horizon]] wiki topics.</p>
<tr class="head">
<th>
<p>
<p>
Default channel name for...</p>
You have the opportunity to try up to two IODEV 27 threads without additional expense. If you want additional threads, contact Rocket Software.</p>  
</th>
<th>
<p>
<p>
Uses this terminal connection...</p>
Horizon threads are also used for SQL server processing (IODEV=19). For information about IODEV=19, see [[#Coding the IODEV=19 line|Coding the IODEV=19 line]].</p>
</th>
</tr>
   
   
<tr>
===Managing IODEV=27 threads===
<td>
<p>
In CCAIN, the system manager needs to include only IODEV=27 statements. For LU 6.2 sessions, all but the first of these statement lines have no further parameters. The first statement line includes the NOTERM parameter, which indicates the total number of IODEV=27 threads to be in the system. For IODEV=27, you can use the synonym NOTHREAD in place of NOTERM.</p>
<p>
<p>
M204FULL</p>
In a Horizon conversation, an application program either initiates the conversation (client) or is started up by a request for a conversation from a partner application (server). IODEV=27 statements are required for a <var class="product">Model&nbsp;204</var> ONLINE only if it has server applications that can be started up by clients in the network. The number of IODEV=27 lines determines the maximum number of server applications that the ONLINE can allow to run concurrently. This number has no effect on the number of concurrent conversations that client applications on the local system can initiate on other remote systems.</p>  
</td>
<td>
<p>
<p>
M204FS</p>
IODEV=27 threads are thus needed only on one end of a Horizon conversation: the server end. Since the client end is started up by a request from a local user and not by a request from a remote program, the client is part of the local user thread. As such, the client is supported by whatever IODEV statement was used to set up that user thread.</p>
</td>
</tr>
<tr>
<td>
<p>
<p>
M204PROD</p>
Support for the additional SNA Communications Server APPL required with Horizon is configured in DEFINE commands rather than in CCAIN, as explained in [[Horizon network management#Defining the network to SNA Communications Server|Defining the network to SNA Communications Server]].</p>
</td>
 
<td>
==IUCV (IODEV=39, 41, 43)==
<p>
<p>
M204TTY </p>
A <var class="product">Model&nbsp;204</var> Online can be run as multiuser or single-user (batch) operation, or single-user within a user's z/VM virtual machine. [[BATCH204]] is not supported, but can be simulated by executing the ONLINE module in a CMSBATCH machine or in a user-defined virtual machine.</p>
</td>
</tr>
</table></li>
</ul>
===CICS Interface===
<p>
<p>
With the CICS Interface, invoke <var class="product">Model&nbsp;204</var> as follows: </p>
Communication between an individual z/VM user machine and the <var class="product">Model&nbsp;204</var> service machine running in a separate z/VM virtual machine is provided through IUCV. The access path between a CMS terminal user and <var class="product">Model&nbsp;204</var> through IUCV is established by means of a channel that is defined on User 0's parameter line. Each channel name must be unique within the <var class="product">Model&nbsp;204</var> service machine. If no name is specified, defaults are used.</p>
<p>
For example, the following statement connects a user to a <var class="product">Model&nbsp;204</var> service machine:</p>
   
   
<p class="syntax">M204 [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=11)
<p class="code">M204 USER <i>machineid</i> CHAN M204VMFS
L204 [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=29)
</p>
</p>
Where:
   
   
==SQL server threads (IODEV=19)==
<ul>
<li><var class="term">machineid</var> is the name of the service machine and must be specified.</li>
<li> M204VMFS is the channel name. </li>
</ul>
<p>
[[#M204 command (CMS)|M204 command (CMS)]] describes the M204 command in detail.</p>
 
===Parameters for IUCV channel names===
<p>
<p>
<var class="product">Model&nbsp;204</var> requires a pool of threads to support server control of Horizon SQL connections. The system manager must define these threads in the CCAIN stream as part of the Online startup configuration.</p>
The following table lists the parameters used to specify channel names:  </p>
   
   
<table>
<table>
<tr class="head">
<tr class="head">
<th><p>IODEV </p></th>
<th><p>IODEV setting</p></th>
<th><p>Defines thread for...</p></th>
<th><p> Parameter</p></th>
<th><p>You must define this thread for... </p></th>
<th><p>Default name</p></th>
<th><p>You can name an alternate channel on the...</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>19 </p></td>
<td><p>39</p></td>
<td><p><var class="product">Model&nbsp;204</var> SQL Horizon</p></td>
<td><p>VMIOCHNL</p></td>
<td><p>All Connect<span class="superstar">&#9733;</span> configurations. </p></td>
<td><p>M204VMIO</p></td>
<td><p>VMIOCHNL parameter.</p></td>
</tr>
</tr>
</table>
   
   
<tr>
<td>
<p>
<p>
You have the opportunity to try up to two IODEV 19 threads without additional expense. If you want additional threads, please notify [[Contacting Rocket Software Technical Support|Technical Support]].</p>
41 </p>
   
  </td>
<td>
<p>
<p>
For complete information on <var class="product">Model&nbsp;204</var> SQL system management, including SQL catalog and procedure file maintenance, SQL parameters and statistics, and processgroup definitions, see the [[:Category: Model 204 SQL processing|Model 204 SQL processing]] topics.</p>
VMFSCHNL</p>
</td>
===Coding the IODEV=19 line===
<td>
<p>
<p>
Defining the IODEV=19 thread requires specifying or changing the following parameters. For an example of the specification of an IODEV=19 line, see [[#Example for z/VM|Example for z/VM]]. </p>
M204VMFS</p>
   
  </td>
<p class="note"><b>Note:</b> Define these as the last IODEV in your CCAIN as some of the parameters could have an affect on other IODEV threads.</p>
<td>
====NOTHREAD====
<p>
<p>
You can insert several IODEV=19 lines in the CCAIN stream. On the first line defining the SQL thread, include the <var>[[NOTHREAD parameter|NOTHREAD]]</var> parameter to indicate the number of SQL threads to be allocated. Set NOTHREAD to the number of concurrent Connect<span class="superstar">&#9733;</span> conversations to be supported. </p>
VMFSCHNL parameter. Used in partner process communication and in communication with 3270 and 3270-compatible local and remote terminals.</p>
</td>
</tr>
   
   
====SQLBUFSZ====
<tr>
<td>
<p>
<p>
<var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var> is a required resettable User 0 parameter that corresponds to the size of the <var class="product">Model&nbsp;204</var> SQL Server buffer that assembles incoming SQL messages from a receiving buffer (in CRAM, IUCV, or Horizon). The <var>SQLBUFSZ</var> value defines the maximum length of an incoming SQL message.</p>  
43</p>
</td>
<td>
<p>
<p>
Because the largest incoming SQL message is likely to be a DDL transaction, set <var>SQLBUFSZ</var> large enough to accommodate your largest DDL transaction plus 50 bytes of overhead. You can also monitor the <var class="product">Model&nbsp;204</var> SQLI statistic to determine the size of the largest SQL input request. </p>
VMIFCHNL</p>
</td>
<td>
<p>
<p>
The recommended initial value for this parameter is 100000. Specify it on the first IODEV=19 line. </p>
M204VMIF</p>
   
  </td>
====INMRL====
<td>
<p>
<p>
<var>[[INMRL parameter|INMRL]]</var> is a user parameter that determines the maximum input line length for an I/O device as well as the maximum length of an internal <var class="product">Model&nbsp;204</var> buffer. You must set <var>INMRL</var> to a value greater than or equal to 500 (characters) for z/OS IODEV 19 threads. Specify it on the first IODEV=19 line. </p>  
VMIFCHNL parameter.</p>
<p>
</td>
Processing complex SQL statements might require a larger <var>INMRL</var> setting. If the <var>INMRL</var> buffer capacity is exceeded, you get the <var class="product">Model&nbsp;204</var> error message:</p>
</tr>
</table>
   
   
<p class="code">INVALID STRING ARGUMENT
===Programs required for the IUCV CMS Interface===
</p>
<p>
<p>
Increase <var>INMRL</var> by 50% and rerun your request.</p>
The programs required to support the IUCV CMS Interface in communicating with ONLINE configurations operating in a virtual machine are distributed on a CMS format tape. The "CMS files required for the IUCV Interface" table, below, lists the required files. Information about installation is found in the <var class="book">[[Media:M204_InstallzVM_V74.pdf|Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]]</var>.</p>
   
   
====NSUBTKS====
<table>
<p>
<caption>CMS files required for the IUCV Interface</caption>
Increase the User 0 <var>[[NSUBTKS parameter|NSUBTKS]]</var> parameter by 3 per open Horizon link for Connect<span class="superstar">&#9733;</span> processing.</p>
<tr class="head">
<th><p>File name</p></th>
<th><p>File type</p></th>
<th><p>Function  </p></th>
</tr>
   
   
====SQLIQBSZ====
<tr>
<p>
<td><p>M204</p></td>
The user parameter <var>[[SQLIQBSZ parameter|SQLIQBSZ]]</var> determines the size in bytes of the internal buffer used to compile and evaluate SQL requests. </p>
<td><p>EXEC </p></td>
<p>
<td><p>Initiates communication between the user and <var class="product">Model&nbsp;204</var></p></td>
The minimum value is 2032; the maximum is 32752. The maximum setting (large enough for a 250-column table with an average column length of 30 bytes) is sufficient for most SQL applications.</p>
</tr>
   
   
===Example for z/VM===
<tr>
<p>
<td><p>M204</p></td>
The following example shows the CCAIN data stream for a z/VM job that brings up a <var class="product">Model&nbsp;204</var> Online for SQL processing. This example shows sample settings of some of the CCAIN parameters described earlier in this chapter, the first two IODEV lines for each SQL IODEV, and <var class="product">Model&nbsp;204</var> SQL DEFINE commands.  </p>
<td><p>HELPCMS </p></td>
<td><p>Provides HELP information for M204 command syntax</p></td>
</tr>
   
   
<p class="code">... LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760,
<tr>
LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300,
<td><p>M204IFAM</p></td>
MINBUF=18,MAXBUF=200,NSUBTKS=15,...
<td><p>EXEC </p></td>
SERVSIZE=700000,...
<td><p>Aids in establishing an HLI connection to <var class="product">Model&nbsp;204</var> </p></td>
    .
</tr>
    .
   
    .
<tr>
IODEV=49,POLLNO=1,NOTHREAD=4
<td><p>M204IFAM</p></td>
IODEV=49,POLLNO=2
<td><p>TXTLIB </p></td>
IODEV=49,POLLNO=3
<td><p>Specifies the library of object modules that must be included in IFAM2 programs under CMS</p></td>
IODEV=49,POLLNO=4
</tr>
IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, -
LIBUFF=6048,SQLIQBSZ=32752
<tr>
IODEV=19,POLLNO=2
<td><p>M204INFO</p></td>
IODEV=19,POLLNO=3
<td><p>MODULE </p></td>
IODEV=19,POLLNO=4
<td><p>Provides information about the CMS environment</p></td>
<b></b>* above IODEV=49 is for RCL connections
</tr>
<b></b>* above IODEV=19 is for SQL CONNECT* connections
<b></b>*-------------------------------------------------------*  /
<b></b>*  DEFINE CONNECT * SQL AND RCL LINK ETC...            *  /
<b></b>*-------------------------------------------------------*  /
<b></b>**********************************************
DEFINE LINK TCPSQL WITH SCOPE=SYSTEM TRANSPORT=TCPSE -
  PROTOCOL=IP LOCALID=ANY INBUFSIZE=4096 CONNECTIONS=8 -
  SERVPORT=2132
DEFINE PROCESSGROUP ANY192  WITH SCOPE=SYSTEM LINK=TCPSQL -
  INLIMIT=8 OUTLIMIT=8 REMOTEID=192.0.0.0  LOGIN=NOTRUST  -
  GUESTUSER=REJECT MASK=255.0.0.0
DEFINE PROCESSGROUP ANY204  WITH SCOPE=SYSTEM LINK=TCPSQL  -
  INLIMIT=8 OUTLIMIT=8 REMOTEID=204.0.0.0  LOGIN=NOTRUST  -
  GUESTUSER=REJECT  MASK=255.0.0.0
DEFINE PROCESS CCARSQL WITH SCOPE = SYSTEM -
DATALEN = 32763 FROM = (ANY192, ANY204)
<b></b>********************************************************
</p>
 
==Horizon (IODEV=27)==
<p>
Horizon, the <var class="product">Model&nbsp;204</var> distributed application facility, enables <var class="product">Model&nbsp;204</var> applications to participate in program-to-program processing by communicating through SNA Communications Server with one or more other programs.
The applications communicate over SNA LU 6.2 sessions (with a partner application that can run in the same or in a different computer) in a logical connection called a conversation.
Support for such conversations is configured primarily by <var class="product">Model&nbsp;204</var> DEFINE commands and is fully described in [[Model 204 intersystem processing]] and other [[:Category: Horizon|Horizon]] wiki topics.</p>
<p>
You have the opportunity to try up to two IODEV 27 threads without additional expense.  If you want additional threads, contact Rocket Software.</p>  
<p>
Horizon threads are also used for SQL server processing (IODEV=19). For information about IODEV=19, see [[#Coding the IODEV=19 line|Coding the IODEV=19 line]].</p>
   
   
===Managing IODEV=27 threads===
<tr>
<p>
<td><p>M204USR</p></td>
In CCAIN, the system manager needs to include only IODEV=27 statements. For LU 6.2 sessions, all but the first of these statement lines have no further parameters. The first statement line includes the NOTERM parameter, which indicates the total number of IODEV=27 threads to be in the system. For IODEV=27, you can use the synonym NOTHREAD in place of NOTERM.</p>
<td><p>LOADLIB </p></td>
<p>
<td><p>Provides interactive access to <var class="product">Model&nbsp;204</var> and parses the command string, but used for nucleus extension</p></td>
In a Horizon conversation, an application program either initiates the conversation (client) or is started up by a request for a conversation from a partner application (server). IODEV=27 statements are required for a <var class="product">Model&nbsp;204</var> ONLINE only if it has server applications that can be started up by clients in the network. The number of IODEV=27 lines determines the maximum number of server applications that the ONLINE can allow to run concurrently. This number has no effect on the number of concurrent conversations that client applications on the local system can initiate on other remote systems.</p>  
</tr>
<p>
IODEV=27 threads are thus needed only on one end of a Horizon conversation: the server end. Since the client end is started up by a request from a local user and not by a request from a remote program, the client is part of the local user thread. As such, the client is supported by whatever IODEV statement was used to set up that user thread.</p>
<tr>
<p>
<td><p>M204USR</p></td>
Support for the additional SNA Communications Server APPL required with Horizon is configured in DEFINE commands rather than in CCAIN, as explained in [[Horizon network management#Defining the network to SNA Communications Server|Defining the network to SNA Communications Server]].</p>
<td><p>MODULE </p></td>
<td><p>Provides interactive access to <var class="product">Model&nbsp;204</var> and parses the command string</p></td>
</tr>
</table>


==IUCV (IODEV=39, 41, 43)==
===Interactive access (M204USR MODULE)===
<p>
<p>
A <var class="product">Model&nbsp;204</var> Online can be run as multiuser or single-user (batch) operation, or single-user within a user's z/VM virtual machine. BATCH204 is not supported, but can be simulated by executing the ONLINE module in a CMSBATCH machine or in a user-defined virtual machine.</p>
Interactive access to <var class="product">Model&nbsp;204</var> from CMS, which is provided by the M204USR MODULE file, permits a user at a terminal to communicate with <var class="product">Model&nbsp;204</var> executing on another virtual machine under CMS.</p>
<p>
<p>
Communication between an individual z/VM user machine and the <var class="product">Model&nbsp;204</var> service machine running in a separate z/VM virtual machine is provided through IUCV. The access path between a CMS terminal user and <var class="product">Model&nbsp;204</var> through IUCV is established by means of a channel that is defined on User 0's parameter line. Each channel name must be unique within the <var class="product">Model&nbsp;204</var> service machine. If no name is specified, defaults are used.</p>
The M204USR MODULE file executes in the CMS user area in the following manner:</p>
<p>
For example, the following statement connects a user to a <var class="product">Model&nbsp;204</var> service machine:</p>
   
   
<p class="code">M204 USER <i>machineid</i> CHAN M204VMFS
<ol>
</p>
<li> Parses a command string that defines the parameters of a communication interface between CMS and <var class="product">Model&nbsp;204</var>.</li>
Where:
<li> Uses these parameters to establish the connection between the user's virtual machine and <var class="product">Model&nbsp;204</var>.</li>
<li> Accepts data for display and reads input from the terminal for transmission to <var class="product">Model&nbsp;204</var> through IUCV. </li>
</ol>
<p>
M204USR MODULE provides the IUCV interface that allows a CMS user to communicate with a <var class="product">Model&nbsp;204</var> Online running in a CMS service machine. You can run the interface in either the user area, a discontiguous saved segment (DCSS), or a nucleus extension.
The TPROCESS communication facility requires IUCV to be run as a saved segment or a nucleus extension. Saved Segments are discussed in the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var>.</p>
<p>
The M204USR MODULE and a load library (M204USR LOADLIB) for the user-area and nucleus extension versions are built by the M204GEN EXEC. The DCSS version (M204USR) is built by M204XGEN EXEC. Keyword options specified in the distributed M204 EXEC can execute in any of the three nodes. If no options are specified, the default is DCSS.</p>
 
===Line-at-a-time (IODEV=39)===
<p>
The IUCV line mode thread is used to communicate with any terminal supported by z/VM. Determine the buffer size by the value of <code>MAX(INMRL,OUTMRL)-12</code> bytes. (See [[#User environment control parameters|User environment control parameters]] for a summary of user parameters.)  </p>
   
   
<ul>
<ul>
<li><var class="term">machineid</var> is the name of the service machine and must be specified.</li>
<li><var>INMRL</var> must be less than or equal to <var>LIBUFF</var> minus 4. You can set <var>LIBUFF</var> to any value up to 32K for the IFDIAL expanded communication buffer.</li>
<li> M204VMFS is the channel name. </li>
 
<li><var>OUTMRL</var> must be less than or equal to <var>LOBUFF</var>. You can set <var>LOBUFF</var> to any value up to 32K for IFDIAL expanded communication buffer.</li>
</ul>
</ul>
   
   
<p>
<p>
[[#M204 command (CMS)|M204 command (CMS)]] describes the M204 command in detail.</p>
The maximum of (INMRL, OUTMRL) plus 4 determines the size of the CRAM buffer. <var>INMRL</var> determines the maximum length of data that can be transferred for input to <var class="product">Model&nbsp;204</var>. <var>OUTMRL</var> determines the maximum length of data that can be transferred as output from <var class="product">Model&nbsp;204</var>.</p>
<p>
<p>
The following table lists the parameters used to specify channel names:  </p>
An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.</p>
   
   
<table>
<ul>
<caption>Parameters for IUCV channel names</caption>
<li>You can set <var>OUTCCC</var> to 0 or any setting up to <code>32K-4</code>. It must not be larger than <var>OUTMRL</var>.</li>
<tr class="head">
 
<th><p>IODEV setting</p></th>
<li>You can set <var>INCCC</var> to 0 or any setting up to <code>32K-4</code>. </li>
<th><p> Parameter</p></th>
</ul>
<th><p>Default name</p></th>
<th><p>You can name an alternate channel on the...</p></th>
</tr>
   
   
<tr>
===IUCV full-screen (IODEV=41)===
<td><p>39</p></td>
<p>
<td><p>VMIOCHNL</p></td>
The full-screen mode thread is used to communicate with IBM 3270 and compatible local and remote display terminals. This thread is also used in partner process communication. </p>
<td><p>M204VMIO</p></td>
<p>
<td><p>VMIOCHNL parameter.</p></td>
The buffer size is 12 less than the value of the <var>LOUTPB</var> parameter. For full-screen I/O, set <var>LOUTPB</var> to at least 24044.</p>
</tr>
   
   
<tr>
===IFAM2 (IODEV=43)===
<td>
<p>
<p>
41 </p>
In a CMS environment, <var class="product">Model&nbsp;204</var>, when executing in the service virtual machine, communicates with host language programs that run in one or more CMS virtual machines.</p>
</td>
<td>
<p>
VMFSCHNL</p>
</td>
<td>
<p>
M204VMFS</p>
</td>
<td>
<p>
VMFSCHNL parameter. Used in partner process communication and in communication with 3270 and 3270-compatible local and remote terminals.</p>
</td>
</tr>
<tr>
<td>
<p>
43</p>
</td>
<td>
<p>
VMIFCHNL</p>
</td>
<td>
<p>
M204VMIF</p>
</td>
<td>
<p>
VMIFCHNL parameter.</p>
</td>
</tr>
</table>
===Programs required for the IUCV CMS Interface===
<p>
The programs required to support the IUCV CMS Interface in communicating with ONLINE configurations operating in a virtual machine are distributed on a CMS format tape. The "CMS files required for the IUCV Interface" table, below, lists the required files. Information about installation is found in the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var>.</p>
<table>
<caption>CMS files required for the IUCV Interface</caption>
<tr class="head">
<th><p>File name</p></th>
<th><p>File type</p></th>
<th><p>Function  </p></th>
</tr>
<tr>
<td><p>M204</p></td>
<td><p>EXEC </p></td>
<td><p>Initiates communication between the user and <var class="product">Model&nbsp;204</var></p></td>
</tr>
<tr>
<td><p>M204</p></td>
<td><p>HELPCMS </p></td>
<td><p>Provides HELP information for M204 command syntax</p></td>
</tr>
<tr>
<td><p>M204IFAM</p></td>
<td><p>EXEC </p></td>
<td><p>Aids in establishing an HLI connection to <var class="product">Model&nbsp;204</var> </p></td>
</tr>
<tr>
<td><p>M204IFAM</p></td>
<td><p>TXTLIB </p></td>
<td><p>Specifies the library of object modules that must be included in IFAM2 programs under CMS</p></td>
</tr>
   
   
<tr>
<p>
<td><p>M204INFO</p></td>
When using IFAM2:</p>
<td><p>MODULE </p></td>
<td><p>Provides information about the CMS environment</p></td>
</tr>
   
   
<tr>
<ul>
<td><p>M204USR</p></td>
<li> You can use z/VSE macros within IFAM2 programs.</li>
<td><p>LOADLIB </p></td>
<td><p>Provides interactive access to <var class="product">Model&nbsp;204</var> and parses the command string, but used for nucleus extension</p></td>
</tr>
<tr>
<td><p>M204USR</p></td>
<td><p>MODULE </p></td>
<td><p>Provides interactive access to <var class="product">Model&nbsp;204</var> and parses the command string</p></td>
</tr>
</table>


===Interactive access (M204USR MODULE)===
<li> You can compile IFAM2 programs with a z/VSE compiler.</li>
<p>
Interactive access to <var class="product">Model&nbsp;204</var> from CMS, which is provided by the M204USR MODULE file, permits a user at a terminal to communicate with <var class="product">Model&nbsp;204</var> executing on another virtual machine under CMS.</p>
<p>
The M204USR MODULE file executes in the CMS user area in the following manner:</p>
<ol>
<li> Parses a command string that defines the parameters of a communication interface between CMS and <var class="product">Model&nbsp;204</var>.</li>
<li> Uses these parameters to establish the connection between the user's virtual machine and <var class="product">Model&nbsp;204</var>.</li>
<li> Accepts data for display and reads input from the terminal for transmission to <var class="product">Model&nbsp;204</var> through IUCV. </li>
</ol>
<p>
M204USR MODULE provides the IUCV interface that allows a CMS user to communicate with a <var class="product">Model&nbsp;204</var> Online running in a CMS service machine. You can run the interface in either the user area, a discontiguous saved segment (DCSS), or a nucleus extension.
The TPROCESS communication facility requires IUCV to be run as a saved segment or a nucleus extension. Saved Segments are discussed in the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var>.</p>
<p>
The M204USR MODULE and a load library (M204USR LOADLIB) for the user-area and nucleus extension versions are built by the M204GEN EXEC. The DCSS version (M204USR) is built by M204XGEN EXEC. Keyword options specified in the distributed M204 EXEC can execute in any of the three nodes. If no options are specified, the default is DCSS.</p>


===Line-at-a-time (IODEV=39)===
<li> IFAM2 provides multithread access to <var class="product">Model&nbsp;204</var> files from a host language program.</li>
<p>
The IUCV line mode thread is used to communicate with any terminal supported by z/VM. Determine the buffer size by the value of <code>MAX(INMRL,OUTMRL)-12</code> bytes. (See [[#User environment control parameters|User environment control parameters]] for a summary of user parameters.)  </p>
<ul>
<li><var>INMRL</var> must be less than or equal to <var>LIBUFF</var> minus 4. You can set <var>LIBUFF</var> to any value up to 32K for the IFDIAL expanded communication buffer.</li>


<li><var>OUTMRL</var> must be less than or equal to <var>LOBUFF</var>. You can set <var>LOBUFF</var> to any value up to 32K for IFDIAL expanded communication buffer.</li>
<li> You define the <var class="product">Model&nbsp;204</var> files accessed by the host language programs to the service machine just as you define other database files. Define application program files (if any) in the user's CMS virtual machine.</li>
</ul>
</ul>
   
   
<p>
<p>
The maximum of (INMRL, OUTMRL) plus 4 determines the size of the CRAM buffer. <var>INMRL</var> determines the maximum length of data that can be transferred for input to <var class="product">Model&nbsp;204</var>. <var>OUTMRL</var> determines the maximum length of data that can be transferred as output from <var class="product">Model&nbsp;204</var>.</p>
IUCV is not supported in the VAE mode of z/VSE operating systems.</p>
<p>
An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.</p>
<ul>
<li>You can set <var>OUTCCC</var> to 0 or any setting up to <code>32K-4</code>. It must not be larger than <var>OUTMRL</var>.</li>


<li>You can set <var>INCCC</var> to 0 or any setting up to <code>32K-4</code>. </li>
</ul>
===IUCV full-screen (IODEV=41)===
<p>
The full-screen mode thread is used to communicate with IBM 3270 and compatible local and remote display terminals. This thread is also used in partner process communication. </p>
<p>
The buffer size is 12 less than the value of the <var>LOUTPB</var> parameter. For full-screen I/O, set <var>LOUTPB</var> to at least 24044.</p>
===IFAM2 (IODEV=43)===
<p>
In a CMS environment, <var class="product">Model&nbsp;204</var>, when executing in the service virtual machine, communicates with host language programs that run in one or more CMS virtual machines.</p>
<p>
When using IFAM2:</p>
<ul>
<li> You can use z/VSE macros within IFAM2 programs.</li>
<li> You can compile IFAM2 programs with a z/VSE compiler.</li>
<li> IFAM2 provides multithread access to <var class="product">Model&nbsp;204</var> files from a host language program.</li>
<li> You define the <var class="product">Model&nbsp;204</var> files accessed by the host language programs to the service machine just as you define other database files. Define application program files (if any) in the user's CMS virtual machine.</li>
</ul>
<p>
IUCV is not supported in the VAE mode of z/VSE operating systems.</p>
==RCL thread (IODEV=49)==
==RCL thread (IODEV=49)==
<p>
<p>
Line 2,115: Line 2,073:
The <var class="term">options</var> format is: </p>
The <var class="term">options</var> format is: </p>
<p class="syntax">[LINE | DISPLAY | DCSS | NUCEXT | UAREA] [USERID <span class="term">userid</span>]
<p class="syntax">[LINE | DISPLAY | DCSS | NUCEXT | UAREA] [USERID <span class="term">userid</span>]
[CHANNEL <span class="term">channel</span>] [LOGIN | NOLOGIN] [DISCONN <span class="term">string</span>]
[<b>CHAN</b>NEL <span class="term">channel</span>] [<b>LOG</b>IN | <b>NOLO</b>GIN] [<b>DISC</b>ONN <span class="term">string</span>]
[SUBSET <span class="term">string</span>] [CMD <span class="term">filename</span>] [ONLINE | IFDIAL]
[<b>SUBS</b>ET <span class="term">string</span>] [CMD <span class="term">filename</span>] [ONLINE | IFDIAL]
</p>
</p>
   
   
Line 2,239: Line 2,197:
</ul>
</ul>
   
   
====Bypassing password prompts====
====<b id="cmsNoPasswd"></b>Bypassing password prompts====
<p>
<p>
Use the <var>LOGCTL</var> command with the <var>NP</var> option to bypass password prompts:</p>
Use the <var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL]]</var> command with the <var>NP</var> option to bypass password prompts:</p>
   
   
<p class="code">LOGCTL NP CMS
<p class="code">LOGCTL NP CMS
Line 2,254: Line 2,212:
   
   
<ul>
<ul>
<li> A <code>LOGCTL NP CMS</code> command must be issued.</li>
<li> A <code>LOGCTL NP CMS</code> command must have been issued.  The command applies to <i>all</i> CCASTAT users.</li>


<li> The user ID on the <var>LOGIN</var> or <var>LOGON</var> command must equal the CMS user ID of the CMS virtual machine on which the login originated.
<li> The user ID on any subsequent <var>LOGIN</var> or <var>LOGON</var> command must equal the CMS user ID of the CMS virtual machine from which the login originated.
<p>
<p>
If the default user ID is not identical to the CMS user ID, <var class="product">Model&nbsp;204</var> then prompts for a password, and continues login processing.</p></li>
If that user ID is not identical to the CMS user ID, <var class="product">Model&nbsp;204</var> then prompts for a password, and continues login processing.</p></li>


<li> User ID must be located in the password table.
<li> The user ID used in the LOGIN command must be located in the password table.
<p>
<p>
If the user ID is not in the password table, <var class="product">Model&nbsp;204</var> prompts for a password and then rejects the login command.    </p></li>
If the user ID is not in the password table, <var class="product">Model&nbsp;204</var> prompts for a password and then rejects the login command.    </p></li>
</ul>
</ul>
<b>NOTE:</B> Any LOGIN command <i>without</i> a user ID, will successfully logon as the CMS user ID of the user who issued the LOGIN command, assuming the CMS user ID is found in CCASTAT.  Also, no password prompt will be issued.


==CMS service machine console (ALTIODEV=45, 47)==
==CMS service machine console (ALTIODEV=45, 47)==

Latest revision as of 22:50, 14 March 2019

Overview

This topic summarizes the access methods and device types compatible with Model 204 and explains special considerations relating to operating systems and Model 204 configurations. For detailed information about device types, see the Terminal processing and support topics.

The most common parameters used to control a user's environment are summarized at the end of this page. For a view of the full range of individual user parameters, see List of Model 204 parameters.

Setting user parameters

Specifications controlling the environment of each Online user are entered in the CCAIN input stream on user parameter lines following User 0's runtime specifications. Each user line defines the input/output access method and device (IODEV parameter), followed by appropriate control parameters.

Basic rules

The following rules apply:

  • Define each user to Model 204 on a separate parameter line following User 0's parameter line.
  • Number of user parameter lines must be one less than the value specified for the number of users (NUSERS - 1).
  • You must define terminals of the same type together.
  • Any user parameters set on User 0's parameter line take effect for current users unless they are specifically reset.
  • Initial setting of a parameter on one line remains in effect until a second parameter is read that explicitly resets the first. If no parameter needs to be set (because all previous parameter settings are applicable), you can use a statement with a single asterisk.
  • Terminal interface is initialized if one or more IODEV statements of the same type are encountered in CCAIN.

Access methods and device types

Each Online user is defined to Model 204 on a separate parameter line that first defines the user's device type and access method (IODEV parameter) and then specifies other parameters as required. The IODEV definition provides a value that is used in the context of a table lookup to obtain current routines that handle that particular device or access method.

Access methods

Model 204 supports the following access methods:

Access method Acronym
Basic Sequential Access Method BSAM
Cross-Region Access Method CRAM
Inter-User Communication Vehicle IUCV
Remote Command Line RCL
Virtual Telecommunications Access Method SNA Communications Server (formerly VTAM)

The "z/OS and z/VSE device type codes" and "z/VM input/output device type codes" tables in the following section list each access method with its associated IODEV setting and required system (User 0) and user parameters. Further details for each IODEV setting are provided in the individual sections that make up most of the rest of this page.

Device types (IODEV settings)

The following table lists z/OS and z/VSE input/output device types with required parameters:

z/OS and z/VSE device type codes
IODEV value Access method/device type Essential parameters
1 CCAIN/CCAPRINT (User 0 only) (none)
3 BSAM INPUT
OUTPUT
7 SNA Communications Server 3270 (full screen) LOUTPB
MODEL
NOTERM
NOUTBUF
NSUBTKS
TERMBUF
TERMOPT
VTAMNAME
11 CRAM thread (full screen), supports:
  • TSO
  • CICS
  • Program Communication facilities
CRFSCHNL
LOUTPB
MODEL
NOTERM
POLLNO
XDMSSN
19 Horizon SQL thread INMRL
NOTHREAD
NSUBTKS
SQLBUFSZ
23 CRAM, Host Language IFAM2 thread IFAMCHNL
XDMSSN
27 Horizon NOTERM
29 CRAM, SOUL thread (line-at-a-time) z/OS and z/VSE, supports:
  • CICS
  • TSO
CRIOCHNL
INCCC
INMRL
NOTERM
OUTCCC
OUTMRL
POLLNO
XDMSSN
37 SNA Communications Server 3767 and NTO (line-at-a-time) INCCC
INMRL
NOTERM
NSUBTKS
OUTCCC
OUTLPP
OUTMRL
TERMID
TERMOPT
VTAMNTO
49 Remote Command Line (RCL) NOTHREAD
POLLNO

The following table lists z/VM/CMS settings for the ALTIODEV as well as the IODEV parameters:

z/VM input/output device type codes
IODEV value Access method/device type Essential parameters
3 BSAM INPUT
OUTPUT
7 SNA Communications Server 3270 (full screen) LOUTPB
MODEL
NOTERM
NOUTBUF
NSUBTKS
TERMBUF
TERMID
TERMOPT
VTAMNAME
19 Horizon SQL thread INMRL
NOTHREAD
NSUBTKS
SQLBUFSZ
39 IUCV SOUL thread (line-at-a-time) INCCC
INMRL
NOTERM
OUTCCC
OUTMRL
POLLNO
TERMID
VMIOCHNL
41 IUCV 3270 thread (full screen), supports Program Communication facilities LOUTPB
NOTERM
POLLNO, TERMID
VMFSCHNL
43 IUCV IFAM2 thread NOTERM
POLLNO
TERMID
VMIFCHNL
ALTIODEV=45 Single-user line mode thread (Service machine console)  
ALTIODEV=47 Single-user full-screen mode thread (Service machine console)  
49 Remote Command Line (RCL) NOTHREAD
POLLNO

The following sections provide details about each IODEV setting.

Note: z/VM/CMS system managers, take note of the IUCV section, which explains IODEV settings 41 and 43 and also discusses Model 204 command options.

BSAM (IODEV=3)

IODEV=3 manages sequential input and output from BSAM. You can configure unattended terminal simulations with IODEV=3, because BSAM assigns buffer allocation, blocking and unblocking, and scheduling I/O services to the user. IODEV=3 uses the same internal routines that handle User 0 statements.

Effective use of IODEV=3 requires consideration of the beginning and end of processing. When using IODEV=3, Model 204 commands and requests are read from the sequential data set. Command processing begins as soon as IODEV=3 initialization is complete and continues until end-of-file is reached. At this point, the thread cannot be reactivated and processing ends.

Commands and SOUL requests are read line-at-a-time from the input. Results of commands and print statements are issued to the output data set.

Uses of IODEV=3

IODEV=3 performs the following functions:

Function Explanation
Stress test Emulates full-screen or line-by-line users as if the input and output were coming from terminals or TP access methods.
Job scheduler Schedules jobs to be done after a specified wait, at a specific time, or repeated at specified time intervals.
Triggers Monitors conditions in the DBMS and invokes appropriate action when certain conditions are detected.

Trigger example

The following SOUL program illustrates how to use IODEV=3 as a trigger to monitor the DBMS. After the example, details about data set definitions and buffer allocation are presented.

//I0301I DD * LOGON system-manager-id password *SLEEP 60 required to complete nucleus initialization before the start of thread execution DEFINE DATASET TXFILE WITH SCOPE=SYSTEM SEQUENTIAL SAM - RECFM=VB LRECL=137 BLKSIZE=1600 OPEN DAILY BEGIN IMAGE TXT TEXT.LINE IS STRING LEN UNKNOWN END IMAGE FD: FD RECTYPE=CONTROL END FIND FR FD IF GO='STOP' THEN STOP ELSEIF GO='PROCESS' THEN %GO='GO' ELSE %GO='PAUSE' END IF END FOR RELEASE RECORDS IN FD IF %GO NE 'GO' THEN PAUSE 60 JUMP TO FD END IF O2: OPEN DATASET TXFILE FOR INPUT R1: PREPARE IMAGE TXT READ IMAGE TXT FROM TXFILE IF $STATUS=1 THEN JUMP TO FD2 ELSEIF $STATUS=GT1 THEN PRINT $ERRMSG STOP END IF IDENTIFY %TXT:TEXT.LINE LEN %TXT@READLEN PRINT %TXT@TEXT.LINE JUMP TO R1 FD2: CLOSE DATASET TXFILE FD1: FDR RECTYPE=CONTROL END FIND FR FD1 CHANGE GO TO 'PAUSE' END FOR CMMTRL JUMP TO FD END LOGOUT /* //I03010 DD SYSOUT=A . . . //

Input or output data set definitions

Each user defined as an IODEV=3 thread must have separate input and output data sets defined. Define input and output data sets using the INPUT=ddname and OUTPUT=ddname parameters on each IODEV=3 statement.

The IODEV statement must define INPUT and OUTPUT (summarized in User environment control parameters). The definitions must coincide with the input and output filenames (the DTF names) in the JCL.

Examples of data set definitions follow for z/VSE, z/OS, and z/VM environments.

z/VSE JCL example

The following JCL defines input and output data sets in a z/VSE environment:

// DLBL I0301I,'dataset name' // EXTENT SYSnnn,balance of extent data // ASSGN SYSnnn,cuu // DLBL I0301O,'dataset name' // EXTENT SYSnnn,balance of extent data // ASSGN SYSnnn,cuu ** The CCAIN definitions remain the same ** IODEV=3,INPUT=I0301I,OUTPUT=I0301O

z/OS JCL examples

The following examples show how to define input and output data sets for IODEV=3 in a z/OS environment. Input and output DD statement names are first defined as files in the JCL and then referenced on the IODEV=3 INPUT and OUTPUT parameters.

The first example uses user-defined names that are coded on the IODEV=3 statement:

//I0301I DD DSN=dataset name,DISP=SHR //I0301O DD SYSOUT=A //I0302I DD * LOGON system-manager-or-system-administrator-id password *SLEEP 60 ---- used to control the start of thread execution INCLUDE procname //I0302O DD DSN=dataset name,DISP=SHR . . . //CCAIN DD * . . . IODEV=3,INPUT=I0301I,OUTPUT=I0301O IODEV=3,INPUT=I0302I,OUTPUT=I0302O

z/VM FILEDEF example

The following FILEDEFs define input and output data sets in a z/VM/CMS environment:

FILEDEF I0301I DISK TEST IN A FILEDEF I0301O DISK TEST OUT A

If input is read from the virtual card reader, use:

FILEDEF I0301I READER

If output is sent to the virtual reader of another machine through the virtual punch, use:

CP SPOOL PUN some-user FILEDEF I0301O PUNCH

Buffer allocation

Each IODEV=3 requires allocation of a set of buffers. Buffer allocation is based upon the INMRL value for input and OUTMRL for output, unless DCB information is specified in the JCL. By default, INMRL is 80 bytes and OUTMRL is 132 bytes. (See User environment control parameters for parameter summaries.)

If DCB information is specified, the buffer allocated is based upon the stated BLKSIZE parameter. DCB information overrides INMRL or OUTMRL values.

If INMRL or OUTMRL is set on an IODEV line above the first IODEV=3, or if they are set in User 0 definitions, the INMRL and OUTMRL values define the values for IODEV=3.

The following example sets buffers of 256 bytes for both input and output:

IODEV=29,POLLNO=1,INMRL=256,OUTMRL=256 IODEV=3,INPUT=I0301I,OUTPUT=I0301O

Dynamic allocation and DFSMS/HSM

Model 204 verifies that DFSMS/HSM is active before attempting to recall a migrated data set. If DFSMS/HSM is not active and a data set is migrated, the ALLOCATE (or DEFINE) command fails.

Model 204 also detects archived data sets (volser=ARCHIV is used by non-IBM data management products). Archived data sets must be recalled before the Model 204 Online step begins. An attempt to dynamically allocate an archived data set fails.

If a dynamic allocation attempt fails in either of these circumstances, the following messages appear:

M204.2501: CHECK FOR DFHSM ACTIVE, RETURN CODE = %C, REASON CODE = %C M204.2502: DFHSM RECALL ERROR, DSNAME = %C, RETURN CODE = %C, REASON CODE = %C

The restrictions on archived data sets do not apply to BATCH204 jobs.

To do these checks, Model 204 uses a special data set name that must not be defined in the z/OS catalog. The special data set is:

DSNAME='MODEL204.DUMMY.DATASET.THAT.DOES.NOT.EXIST'

SNA Communications Server terminal support (IODEV=7, 37)

The SNA Communications Server terminals that can log on directly to Model 204 are:

IODEV SNA Communications Server terminals
IODEV=7 IBM 3270s and other 3270-type terminals
IODEV=37 IBM 3767s and line-at-a-time terminals supported by means of the IBM Network Terminal Option (2741s, teletypes, and teletype-compatibles).

Note: The IODEV=37 setting is no longer supported as of Model 204 version 7.6.

SNA Communications Server is a fully functional component of Model 204, linked into the Model 204 Online load module. Verify that other terminals compatible with SNA Communications Server operation are fully compatible with Model 204 before using them.

Model 204 supports full-screen SNA Communications Server terminals that do not use the standard 3270 data stream by supplying a mechanism for writing exit routines to perform data conversion. The rules for such routines are provided in Rules governing data conversion exit routines.

SNA Communications Server terminals are supported in z/OS, z/VSE, and CMS environments. For direct SNA Communications Server terminal support in a CMS environment, the optional CMS/SNA Communications Server Interface feature must be installed. Only full-screen terminals (IODEV=7) are supported by the CMS/SNA Communications Server Interface, which is described in CMS/SNA Communications Server Interface for full-screen terminals.

SNA Communications Server network definition requirements

For direct SNA Communications Server terminal support by Model 204, you must define Model 204 as an SNA Communications Server application program. Each IODEV type (IODEV=7, IODEV=37) requires an APPL statement in the SYS1.VTAMLST library (z/OS) or in a file with a VTAMLST filetype (CMS). The 1- to 8- character APPL names are used as the values for the VTAMNAME (full-screen) and VTAMNTO (line-at-a-time) parameters within the User 0 CCAIN lines.

For example, the following VBUILD and APPL statements in the VTAMLST data set define Model 204 as an SNA Communications Server application node with major node name M204 and minor node name M204PROD:

M204 VBUILD TYPE=APPL M204PROD APPL

In this case, the M204PROD APPL statement label must correspond to the value of the VTAMNAME parameter. If the APPL statement has an appended ACBNAME=altname specification, altname becomes the required VTAMNAME value, although Rocket recommends that you do not use ACBNAME.

Appending AUTH=(PASS) to the APPL statement is required if your site uses the SNA Communications Server Transfer Control facility.

Model 204 has no further requirements regarding the APPL statements or other network definition statements. For example, network concerns alone determine the setting of logmode table entries.

Note: Model 204 supports both definite response and exception response protocols on messages outbound to the terminal. Requests for SNA definite responses to messages coming inbound from the terminal are not supported. For an exception response protocol on outbound messages, include the '02' value in the TERMOPT parameter setting on each IODEV=7 statement that refers to the terminal.

IP address using TN3270 connection to VTAM session: IPADDR

TN3270 connections via Telnet can be made to a Model 204 job with IODEV=7 connections defined in the job. For such a connection it may be desirable to know the IP address of that user's VTAM session. This information is now available in the IPADDR parameter. You can retrieve the IP address using the:

  • VIEW command

    VIEW IPADDR

  • SOUL $View function

    %ipaddr=$view('IPADDR')

CCAIN requirements

The following CCAIN parameters are relevant to IODEV=7 terminals:

Systemwide parameters Per-user parameters
LOUTPB IODEV
NOUTBUF MODEL
TERMBUF TERMOPT
VTAMNAME TERMID
NSUBTKS IPADDR
NOTERM  

The following CCAIN parameters are relevant to IODEV=37 terminals:

Systemwide parameters Per-user parameters
VTAMNTO IODEV
NSUBTKS INMRL
NOTERM INCC
  OUTMRL
  OUTCC
  OUTLPP
  TERMOPT
  TERMID

IODEV=7 terminals under CMS require an additional system parameter, VTGCSSRV (see the next section for details).

All CCAIN parameters relevant to each IODEV type are listed in z/OS and z/VSE device type codes and z/VM input/output device type codes.

CMS/SNA Communications Server Interface for full-screen terminals

Model 204 under CMS implements its own SNA communications requests using the CMS/SNA Communications Server Interface:

  • All SNA terminals logged on to Model 204 are driven directly by the ONLINE, as in a z/OS or z/VSE environment. The ONLINE then becomes an SNA application program, and an APPL statement is required for Model 204 in the network's VTAMLST files.

    For a simple example, see SNA Communications Server network definition requirements, above.

  • An additional system CCAIN parameter, VTGCSSRV, is required. The CMS/SNA Communications Server Interface, although using the same SNA terminal handler software module as in a z/OS environment (VT75), employs further software, which runs under z/VM's Group Control System (GCS). GCS is a virtual machine supervisor that supports a native VM SNA network. ACF/VTAM, for example, runs in a GCS virtual machine on z/VM.

    See Preparing the GCS server component for details about setting up the GCS server.

  • Using the CMS/SNA Communications Server Interface for terminal support means that users are logged on to the ONLINE machine through CMS/SNA Communications Server Interface services. A virtual machine is not required for each user.

The CMS/SNA Communications Server Interface is an optional feature. To use the Model 204 distributed application facility, Horizon, under CMS, however, the CMS/SNA Communications Server Interface must be installed. For further information about Horizon, see the section Managing IODEV=27 threads.

  • IODEV=37 terminals are not supported by the CMS/SNA Communications Server Interface.
  • IODEV=41 support for full-screen terminals under CMS remains available whether or not the CMS/SNA Communications Server Interface is installed.

Preparing the GCS server component

The GCS server component contains the following elements:

GCS service machine directory entry See Defining the GCS directory entry.
M204VMVT LOADLIB This file contains the program that runs the VT204 command. The VT204 command controls the CMS/VTAM Interface GCS service machine.
PROFILE GCS GCS service machine uses this profile to start the VT204 command automatically at IPL time.

Defining the GCS directory entry

You need to define the Group Control System (GCS) service machine directory entry only if you will be using the CMS/SNA Communications Server Interface or the Horizon interface.

The following sample shows a z/VM directory entry for the CMS/VTAM Interface service machine. Items in italics, for example, password, should conform to your installation configuration parameters and standards. Enter items not in italics exactly as they are shown:

USER M204VMVT password 5M 6M G ACCOUNT account distcode OPTION MIH ECMODE MIH MAXCONN nnn MACHINE mode * Allow any virtual machine to use server: IUCV ALLOW MSGLIMIT 255 IPL GCS PARM AUTOLOG CONSOLE 009 3270 * For z/OS add: NAMESAVE GCS SPOOL 00C 2540 READER * SPOOL 00D 2540 PUNCH A SPOOL 00E 1403 A * Provide links so that IPL CMS is possible: LINK MAINT 190 190 RR LINK MAINT 19D 19D RR LINK MAINT 19E 19E RR * LINK to disk with PROFILE and M204VMVT LOADLIB: LINK MAINT204 193 191 RR

Notes:

  • OPTION statement

    The OPTION MAXCONN nnn statement specifies how many concurrent IUCV paths this virtual machine can open. The CMS and VTAM interfaces use one IUCV path per opened VTAM access control block (ACB). Set the MAXCONN number high enough to accommodate all ACBs that are opened at once. Usually this is at least two per ONLINE virtual machine: one for terminal handling (IODEV=7), and one for each link the system manager defines for the Online. Use a number somewhat higher than you currently need to avoid changing this directory entry each time a new ACB is added.

  • LINK statements

    The 191 disk of the GCS service machine is read-only. Link to the MAINT204 193 disk where the M204VMVT LOADLIB and sample PROFILE GCS are installed.

  • IUCV ALLOW service machine

    The sample directory entry authorizes any virtual machine in the system to connect to an IUCV ALLOW service machine. You can restrict connections to specifically authorized virtual machines by omitting IUCV ALLOW and using IUCV user ID statements instead. Be sure to add the MSGLIMIT 255 operand. For more information about the IUCV statement and other options, refer to the appropriate IBM documentation.

  • VTAM GCS group

    The z/VM system programmer must allocate a slot in the CMS/SNA Communications Server's GCS group for this service machine. This machine should not be in the authorization list; it is intended to run entirely in problem state.

CRAM (IODEV=11, 23, 29)

The Cross-Region Access Method (CRAM) is an interregional facility that lets applications access Model 204. The access is defined by device type codes and channel names in User 0's CCAIN stream.

  • For IFAM applications, communication handled by CRAM is a two-way conversation.
  • For non-IFAM applications, communication handled by CRAM involves one program as the master and the other as a user. The master is always the Model 204 service program, which can communicate with multiple users over the same channel. After a connection is established, the user thread can issue requests, as required, for the application.

Facilities requiring CRAM

Remote User Language (IODEV=11, IODEV=29), IFDIAL protocol IFAM2 (IODEV=29), and IFSTRT protocol IFAM2 (IODEV=23) threads require the use of CRAM. Terminals are considered remote User Language threads when either CICS or TSO is used.

The products and interfaces that require CRAM installation are displayed by IODEV value in the following table:

Facilities IODEV
Full-screen support for:
  • CICS
  • TSO

11

Host Language IFAM2/IFSTART 23
Line-at-a-time User Language thread for:
  • BATCH2
  • CICS
  • IFAM2/IFDIAL
  • TSO
29

Using CRAM on a z/OS operating system

Two CRAM options

On z/OS sites, Model 204 supports two CRAM options: CRAM-SVC and CRAM-XDM (Cross-Memory Data Mover). CRAM-XDM is the default, and CRAM-SVC is deprecated as of Model 204 version 7.5.

z/VSE sites support only the CRAM-SVC option, and z/VM sites support neither.

You can run both CRAM options on the same z/OS machine. A Model 204 Online, however, can operate only one CRAM option at a time.

  • CRAM-SVC

    CRAM-SVC is CRAM functionality accomplished with SVC calls. 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.

    Although earlier CRAM-SVC installations continue to work for both z/OS and z/VSE sites, it is deprecated as of version 7.5 of Model 204 and no installation instructions are offered.

  • CRAM-XDM

    CRAM-XDM uses z/OS cross memory services to move pages from one address space to another in one instruction. All data moves are done using access registers. CRAM-XDM 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 separately, before the Online jobs that might use that XDM.

    The XDM address space must be defined as non-swappable, and it uses a system Linkage Index (LX). It is recommended that you define the address space as non-cancellable, in which case it will always recover from an abend.

For additional background information about CRAM and its constituent modules, see Cross-memory facilities CRAM and M204XSVC.

CRAM-XDM performance versus CRAM-SVC

If you use CRAM-XDM, the default CRAM option as of version 7.5 of Model 204, you can expect the following performance enhancements compared to CRAM-SVC:

CRAM-XDM enhancement

Result

CRAM buffers are no longer obtained from CSA.

Substantial decrease in CRAM CSA storage requirements.

All data moves are from the user buffer directly into the Model 204 user area.

Significant decrease in the number of data moves.

CRAM waits under cross-memory services are invisible.

No ECBS are added to the scheduler chain, which reduces the length of the Model 204 wait chain, thus reducing the evident load on the Online scheduling process.

ALET capacity is increased.

XDM allows the full use of ALETs (Access List Entry Token) up to the IBM limit of 512. This lets you support more concurrent connections between multiple Onlines and multiple XDM clients connecting to those Onlines (CICS tasks and batch IFAM tasks).

For example: With XDM prior to version 7.5, a single CICS region that communicates to three Online regions needs three ALETs, one for each Online. With XDM version 7.5 and higher, a CICS region may use the same ALET to talk to multiple Onlines (and similarly, each Online uses a single, separate ALET to talk to one or more CICS regions). So for three CICS regions to communicate with three Online regions under 7.5 and higher, a total of six ALETs is needed (versus nine ALETs under XDM version 7.4).

You might decide not to use CRAM-XDM at your site because:

  • Your site does not allow non-swappable, APF-authorized tasks in your environment.
  • CRAM performance is a non-issue.
  • CSA storage limitations are a non-issue.

The importance of non-swappability

Defining the XDM address space as non-swappable (described below in Activating CRAM-XDM) is required. Defining the Model 204 address space as non-swappable (described further in Performance monitoring and tuning) is not required but is strongly recommended.

If an address space is swappable, performance degrades due to the necessity of resuming an SRB and the z/OS scheduling delays that entails. The performance penalty when running a multi-user Online as swappable is extremely high in terms of user response times.

A non-swappable address space requires no SRBs and associated z/OS scheduling delays. The fastest environment therefore involves:

  • Non-swappable application
  • Non-swappable Online
  • CRAM-XDM

Invoking a CRAM option

If CRAM threads are defined in an Online's CCAIN input, the CRAM option that is invoked is determined by the setting of the XMEMOPT parameter in CCAIN:

  • X'80' bit included: initializes CRAM-XDM environment
  • X'80' bit not included: initializes CRAM-SVC environment

CRAM-XDM Onlines are compatible with the CRAM-SVC option; both can be used on the same z/OS subsystem. However, a given address space can use only one method. All channels within the Online address space use either the CRAM-XDM option or the CRAM-SVC option, but not both.

CRAM OPEN processing

CRAM can operate in two modes: converser and master/user:

  • Converser mode is like a telephone conversation: either side can speak, and one waits for the other if there is a conflict. IFAM applications use the converser mode.
  • Master/user is like a half-duplex conversation: the end-user requests to speak, and the Model 204 Online (master) gives permission. The Online controls the entire conversation by telling the user what to do next.

Internally, an Online makes CRAM communication possible by issuing a master CRAM OPEN command, specifying a channel name, a block size, and the number of connections (subchannels) available. The information needed to issue this OPEN is derived from parameters (which must include an IODEV set to 11, 23, or 29) specified on User 0's parameter line. Subsequently, Model 204 applications can issue IFAM calls on a particular channel.

CRAM storage requirements

When a CRAM master opens a channel, space is allocated in the Common Service Area (CSA). You must allocate sufficient CSA space to allow the Model 204 Host Language Interface (HLI) to provide support for IODEV 11, 23, or 29 threads.

  • CRAM CSA space for HLI
    • CRAM-XDM

      The following Model 204 7.7 calculation determines the approximate requirements for each active XDM region:

      CSA Space = 1888 + 30 + (60 * onln) + (50 * chnl) + (60 * cnct) + (20 * asid) + trace

      Where (the values shown are in hexadecimal):

      • 1888 is the size of the XMEMCSA module (resident in CSA).
      • 30 is the SSACB length.
      • onln is the SSCB length.
      • chnl is the IICB length.
      • cnct is the UICB length.
      • asid is the ASID table entry.
      • trace is the trace table (length default is 3K per channel).

    • CRAM-SVC

      The amount of CSA space necessary for CRAM-SVC is equal to the amount of virtual storage shown in the calculation in the following subsection.

  • Virtual storage

    The following calculation determines the approximate virtual storage requirements for each Model 204 Online that has IODEV 11, 23, or 29 threads defined.

    Note: This same amount of space is also required in CSA if CRAM-SVC is used.

    Virtual storage requirement = Min(nif,1) * (68 + (nif * (IFAMBS + 100))) + Min(nul,1) * (68 + (nul * (Max(INMRL,OUTMRL) + 100))) + Min(nfs,1) * (68 + (nfs * (LOUTPB + 100)))

    Where:

    • Min is the Minimum function.
    • Max is the Maximum function.
    • nif is the number of IODEV=23 users.
    • nul is the number of IODEV=29 users.
    • nfs is the number of IODEV=11 users.
    • The IFAMBS parameter sets the IFAM2 block size.

      IFAMBS must be set between 2 to 5 times the value of the LIBUFF or LOBUFF parameter. (Most host language parameters are assumed to be LIBUFF long and to occupy a LIBUFF portion of IFAMBS during processing by the IFAM2 interface.)

    • LOUTPB is the length of the output page buffer required for full-screen features.

CRAM buffer allocation

Note: The CRAM buffer sizing discussed below applies only if CRAM-SVC is being used. CRAM-XDM does not use these buffers.

For IODEV=29, the size of the CRAM buffer is the maximum of (INMRL, OUTMRL) + 4. If neither of these parameters is specified on the User 0 parameter line, the default of 256 bytes applies. If an application program uses the extended communication buffer, you can set INMRL and OUTMRL up to 32K to accommodate it.

For IODEV=23, the size of the CRAM buffer is IFAMBS which defaults to 2048. Its maximum is 32,688.

For IODEV=11, the size of the CRAM buffer is LOUTPB, which default to 0. Its maximum is 32,767.

CRAM buffers are allocated as users are activated, or, in the case of IODEV=11 (LOUTPB), during initialization. The minimum CSA usage, without active users, is 68 bytes per channel and 100 bytes per user as defined by the number of IODEV definitions of the same type. When the first user opens a thread (IODEV=23 or IODEV=29), the associated CRAM buffer, sized by IFAMBS or max(INMRL, OUTMRL)+4, is allocated.

CRAM buffers are reusable, and they are freed only when Model 204 terminates.

Communicating with multiple regions of Model 204: channel names

You can communicate with several regions of Model 204 concurrently by establishing a distinct CRAM channel name for each region. One IFDIAL remote User Language thread and several IFSTRT IFAM2 threads can communicate over a particular channel when the channel name is specified in the IFDIAL or IFSTRT call that establishes the connection. You must use one IODEV definition for each terminal.

CRAM channel names (as many as eight characters) are specified on the User 0 parameter line. The following table shows the default CRAM channel names and how to establish a connection using an alternate channel name.

Default and alternate channel names

IODEV

Access method

Default channel name

To define an alternate channel name...

11

Full-screen

M204FULL

Specify a CRFSCHNL parameter value on the User 0 parameter line.

23

IFSTRT protocol IFAM2 threads

IFAMPROD

 

Specify an IFAMCHNL parameter value on the User 0 parameter line.

To access the Online, call IFSTRTN and specify the alternate channel name. IFSTRT accesses only the default channel.

29

IFDIAL protocol IFAM2, line-at-a-time

M204PROD

Specify a CRIOCHNL parameter value on the User 0 parameter line.

To access the Online, call IFDIALN and specify the alternate channel name. IFDIAL accesses only the default channel.

Debugging CRAM

The debugging utility for CRAM-XDM is M204XMON, and the debugging utility for CRAM-SVC is SNAPCRAM. A SNAPCRAM utility also debugs CRAM under z/VSE.

M204XMON

The M204XMON utility is used to debug CRAM-XDM. You can run M204XMON with the parameters shown in the following JCL example:

// Job Card... //JOBLIB DD DSN=Model204Cram.LOADLIB,DISP=SHR //XDMNC EXEC PGM=M204XMON,PARM='SSNAME=xxxx,DETAIL=255' //SYSPRINT DD SYSOUT=A //CCAPRINT DD SYSOUT=A /* //

where xxxx is the secondary subsystem name used by the CRAM-XDM region.

SNAPCRAM

The SNAPCRAM utility is used to debug CRAM-SVC under z/OS. SNAPCRAM prints out the CRAM control blocks in dump format. Sample JCL for running SNAPCRAM is:

// Job Card... //SNAPCRAM EXEC PGM=SNAPCRAM //STEPLIB DD DSN=M204.LOADLIB,DISP=SHR // DD DSN=M204.CRAMLIB,DISP=SHR //CCASNAP DD SYSOUT=A /*

If CRAM is installed in a separate library, the M204.CRAMLIB concatenation shown above is required.

Managing CRAM-XDM

Care with CRAM-XDM LXs

As mentioned earlier, CRAM-XDM uses a system LX. A system LX is intended for a long-running task and must be used carefully because it is a limited system resource.

Because only one Subsystem Access Control Block (SSACB) is established per z/OS image, XDM always reuses the same system LX, even if forced down. A new address space is always used, because a system LX always makes the address space non-reusable. (However, XDM must be started and left active for the life of the IPL.)

Since the address space that uses a system LX is not reusable, the following z/OS warning message is issued if you EOJ the XDM job:

IEF352I ADDRESS SPACE UNAVAILABLE

Bouncing XDM jobs frequently could exhaust the supply of address spaces and require an IPL.

Activating CRAM-XDM

To implement a new version of CRAM-XDM, take the following steps:

  1. Install CRAM-XDM.

    See the Model 204 installation on z/OS instructions for CRAM. That CRAM section also includes ways to configure versions of CRAM and Model 204 that are not the same. For example, you might want to wait to install CRAM-XDM until after you install and test Model 204 with an existing production version of CRAM. Or you might be making the recommended transition from CRAM-SVC to CRAM-XDM.

  2. Bring down the Online(s) with which you want to test this new CRAM version.
  3. Start CRAM-XDM:
    1. Make sure the XDM address space is non-swappable.

      A systems programmer must include a PPT (Program Properties Table) entry in SYS1.PARMLIB(SCHDxx) for the M204XDM module. Specify NOSWAP (non-swappable); and specifying NOCANCEL (non-cancelable) is recommended.

      Attention: If you make CRAM-XDM cancelable, and the operator cancels Model 204 XDM, CSA storage is orphaned. To reclaim the orphaned storage, you must IPL z/OS.

    2. Submit an M204XDM job like the following before bringing up any Onlines, substituting with values appropriate to your site. The job assumes the default installation of CRAM-XDM in its own (CRAMLIB) load library.

      //XDMNC EXEC PGM=M204XDM,PARM='ssn',TIME=NOLIMIT //STEPLIB DD DSN=M204V76.CRAM.LOADLIB,DISP=SHR //SYSPRINT DD SYSOUT=A //CCAPRINT DD SYSOUT=X //

      Where:

      • ssn is the name of the z/OS secondary subsystem that points to the XDM control blocks to use. It is a maximum of four characters. The default SSN was specified as the value of CRMSSN in the CRAM installation JCL, which links the IGCLM244 load module and provides it with the subsystem name.
      • TIME=NOLIMIT is required to initialize M204XDM.

      Notes:

      • If you do not submit the M204XDM job prior to bringing up an Online that specifies an XMEMOPT value that includes the X'80' bit, the Online cannot initialize.
      • You must submit the M204XDM job every time you IPL z/OS.
  4. Prepare the job to bring up the Online:
    1. Set the appropriate CCAIN parameters, especially IODEV, XMEMOPT (including the X'80' bit), and XDMSSN, bring up the Online(s) with which you want to test this new CRAM version.

      Note: No XMEMSVC parameter setting for XDM is required in CCAIN. The M204XSVC object module, which is linked by default into the CRAM load library, is not installed as an SVC as may have been the case in earlier versions. An INCLUDE for the M204XSVC module is also added to the Online link-edit job by default as of version 7.5.

    2. Concatenate the CRAM load library to the Online job, or use the XDMSSN parameter in the job's CCAIN so that the Online locates the XDM region.

      If XDMSSN is not specified, the Online searches its load library for the CRAM IGCLM244 load module. This module contains the secondary subsystem name (SSN) with which CRAM was installed.

  5. After the M204XDM job has initialized, run the Online job.

    When the Online comes up, its audit trail reports the XDM subsystem to which it is connecting:

    AD /// M204.2157: M204XSVC version = 7.7.0G 10/13/16 AD /// IGCLM244 7.7.0G 10/13/16 AD /// SUBSYSTEM NAME = V770

Monitoring XDM

After CRAM-XDM is installed and the M204XDM job is up and running, you can monitor CRAM-XDM from the console or from a batch job.

  • Using console commands

    To monitor XDM, you can issue a MONITOR command. (Authorized users can also issue console commands from SDSF using the /nn syntax). When the XDM master address space is active, it displays the following reply message on the operator console:

    *nn M204XDM.100: jobname AWAITS COMMAND

    Where:

    • nn is the message number to reply to.
    • jobname is the end-user-defined jobname running M204XDM.

    The following table lists the available MONITOR commands:

    Available MONITOR commands
    Command Description
    MONITOR
    or
    MONITOR,ONLINES
    or
    ONLINES
    Lists all Onlines connected to an XDM master; can be abbreviated:
    • M/MO/MON, and so on.
    • MONITOR,O/ON/ONL, and so on.
    • O/ON/ONL, and so on.
    MONITOR,USERS
    or
    USERS
    Lists all jobs using XDM to connect to any Online; can be abbreviated:
    • MONITOR,U/US/USE and so on.
    • U/US/USE and so on.
    MONITOR,ONLINE=jobname
    or
    ONLINE=jobname
    Lists all jobs using XDM to connect to the specified Online.

    The output is sent to the z/OS console and CCAPRINT in the M204XDM job. If you want another report, issue another MONITOR command. The new output is also sent to the console and is appended to the existing CCAPRINT.

    In the following display example, three jobs are using no XDM threads and three jobs are using a total of 12 XDM threads. The CAT11C job is using 4 XDM threads, and so on.

    M204XDM.313: XDM Master Jobname=CAT141A ACTIVE (Subsystem=CAT1) _M204XDM.314: Online Jobname=CAT108 Users=0 _M204XDM.314: Online Jobname=CAT11C Users=4 _M204XDM.314: Online Jobname=CAT11S Users=2 _M204XDM.314: Online Jobname=CAT112 Users=0 _M204XDM.314: Online Jobname=CAT109 Users=6 _M204XDM.314: Online Jobname=CAT102 Users=0 _M204XDM.318: (Totals) Onlines=6 Users=12


  • Using a batch job

    To monitor XDM, use a standalone batch job, when:

    • You might not be authorized to issue console commands.
    • You do not want voluminous MONITOR command output sent to the JES log of the XDM task, or to the console log.
    • You need to get additional information. The batch job provides options for more detailed reporting and you can dump the control blocks for problem diagnosis.

    Execute the M204XMON report with the following JCL:

    //MON EXEC PGM=M204XMON,PARM='parameter' //STEPLIB DD DSN=your.LOADLIB,DISP=SHR //CCAPRINT DD SYSOUT=*

    The output goes to CCAPRINT. Unless you request otherwise, no output is written to the operator console.

    The parameter argument string can be in one of the following forms:

    SSNAME=ssss,ONLINE=oooooooo,DETAIL=nnn,OUTPUT=CONSOLE

    or:

    ssss

    Where:

    • ssss is the CRAM z/OS subsystem name to report on (required).
    • oooooooo is the Online name to report on (optional). If not specified, reports on all Onlines using XDM.
    • nnn specifies what to report (optional). If not specified, defaults to 3.
    • CONSOLE specifies that the report is sent to both the console and CCAPRINT (otherwise to CCAPRINT only).
    • DETAIL=nnn is the sum of the following values:
      Value Purpose
      128 Dumps XDM control blocks.
      64 Interprets XDM control blocks.
      2 Lists XDM Online and user details.
      1 Lists XDM summary information.

      If DETAIL is non-zero, the return code can be one of the following values:

      Value Meaning
      0 Completed normally.
      4 An error was found in XDM control blocks (this is not necessarily a real error; it can occur if a control block was being modified as M204XMON ran).
      8 Invalid parameter: CCAPRINT failed to open, and so on.

      If DETAIL is 0 (not usually used), the return code can be one of the following:

      Value Meaning
      0 No XDM Onlines are active.
      2 XDM Onlines are active, but none have active users.
      3 XDM Onlines are active, and some have active users.

      4

      0C4 while processing XDM control blocks; retry.

Debugging XDM

The M204XMON utility is described above in Debugging CRAM.

Shutting down XDM master from the console

Ordinarily you must keep the XDM master active: shut it down only prior to an IPL. You can shut it down by operator command. The EOJ command, which is the normal command used to terminate XDM, checks that all connections have been terminated, and it does not shut down if XDM Onlines are still active. A MONITOR,ONLINES command (see above) lists on the operator console all address spaces that have connections to XDM.

When the XDM master address space is active, it displays the following reply message on the operator console:

*nn M204XDM.100: jobname AWAITS COMMAND

Where:

  • nn is the message number to reply to.
  • jobname is an end-user defined job.
Shutdown commands

The following shutdown commands are available.

Note: None of these commands cleans up storage; the connection's closing must do the cleanup.

Command Shuts down XDM master...
EOJ If no Onlines are active.

EOJ is only allowed if all connections are cleanly closed.

EOJ,CANCEL Even if Onlines are active.

EOJ,CANCEL leaves all connections in their current state. If a connection is properly closed at a later time, it becomes reusable; otherwise, attempting to use it results in an error message that the CRAM channel is already open.

EOJ,FORCE Without cleaning up the cross-memory environment.

EOJ,FORCE terminates XDM and orphans all storage. Any new XDM will allocate new control blocks and never check the old ones. This will normally clear any error messages that the CRAM channel is already open.

Usually you can terminate the M204XDM job via EOJ without using the FORCE option. However, when recycling the CRAM M204XDM job to apply maintenance from Rocket Software, you must follow the instruction in the maintenance documentation. There may be circumstances that require using the FORCE option or an IPL.

Attention: Use EOJ,CANCEL and EOJ,FORCE commands with extreme caution. Abnormal termination of the XDM master might require an IPL in order for Model 204 Online jobs to use cross-memory services or to reclaim orphaned CSA storage.

If you issue EOJ,CANCEL or EOJ,FORCE commands, any of the following events are possible:

  • Active applications abend.
  • Active CRAM threads abend.
  • Model 204 Online termination abends.
  • CICS applications will ASRA.
  • CICS might abend at shutdown.

Note: In certain situations, such as if the CRAM-XDM control block chains are corrupted, even an EOJ,FORCE command might not be sufficient to clear a previous CRAM error when opening or using a channel. In this situation, if a system IPL is not imminent, then it might be possible to use the CRAMCLR utility to resolve the issue. However, this utility should be used with extreme care, and only under the guidance and advice of Rocket Technical Support.

Using CRAM on a z/VSE operating system

In a z/VSE environment, CRAM lets users from other partitions communicate with Model 204 Online systems. Two versions of CRAM routines are available with each copy of Model 204:

Version... Is compatible with...
Cross-Partition Event Control Blocks (XECB) Single-address-space mode of z/VSE, only.
Cross-Partition Communications Services (XPCC) Both the single-address-space mode and the multiple-address-space mode of z/VSE.

System requirements for the XECB and XPCC versions are explained in the following sections.

Performance

To maximize performance of the CRAM subsystem:

  1. Place the CRAM Load Module and both the master and user subtask programs in the System Directory List (SDL).
  2. Mark the CRAM Transient as a Move Mode transient in the SDL.

Neither the load module nor the subtasks are SVA eligible. Any attempt to place these modules in the SVA causes errors.

System requirements (XECB version)

The CRAM subsystem uses the Cross-Partition Event Control facilities of the z/VSE operating system. To compute the number of blocks (XECBs) required for the Cross-Partition Event Control:

number of XECBs = 5 * (C + N)

Where:

  • C is the number of nonmaster partitions concurrently using the facilities of CRAM.
  • N is the number of master partitions concurrently using the facilities of CRAM.

These requirements affect the specification of the XECB parameter of the z/VSE Supervisor Generation Macro FOPT for releases of z/VSE prior to 1.3.0. Refer to the IBM DOS/z/VSE System Generation Manual for a further discussion of Cross-Partition Event Control Blocks.

Partition requirements

The entire CRAM subsystem runs in the partition GETVIS area of each partition that uses the facilities of CRAM:

  • Each master partition has a copy of the phase IGCLM244 and the master subtask CRAMZWT.
  • Each nonmaster partition has a copy of the phase IGCLM244 and the nonmaster subtask CRAMSWT.
  • If a partition is both a master and a nonmaster, it has only one copy of the phase and one copy of the master and nonmaster subtasks.

Note: The storage requirements given do not include buffer storage (one I/O buffer per thread). Buffer sizes are:

MAX (INMRL,OUTMRL) for IODEV=29 IFAMBS for IODEV=23 LFSCB for IODEV=11

Calculating partition requirements

Total storage requirements consist of fixed and variable storage.

Fixed storage requirements are as follows:

Fixed storage requirements
Fixed storage area XECB version (bytes) XPCC version (bytes)
CRAM phase 2560 3072
CRAM master subtask 13264 22144
CRAM nonmaster 13264 19840
TOTAL 29088 45056

Variable storage requirements, represented schematically, follow:

Variable storage requirements
Variable storage area Bytes
Subtask communications area A
Master channel storage B
User (nonmaster) channel storage C
TOTAL A + B + C

Sizing the subtask communications area

One subtask communications area is required for each subtask running in the partition. If one program is both a master and nonmaster CRAM user, then both subtasks are present in the partition.

  • In the XECB version:

    The size of each communications area (A) is:

    A = n * 128

    Where:

    • n is (652 + (112 * (nparts - 1)))/128, rounded up to the next integer.

      nparts is the number of partitions in the z/VSE system. Round all totals up to the next higher integer.

    For example, if nparts in the z/VSE system is 8, the computation is:

    n = (652 + (112 * (8 -1)))/128, rounded up to next integer n = (11.2) = 12 A = 12 * 128 = 1536 = Subtask Communication Area

  • In the XPCC version:

    The size of each communications area (A) is:

    A = m * 768

    Where m is the number of subtask communications areas. m has the value of 1 for each subtask. For example:

    If the program is... Value of m is...
    CRAM master or a CRAM nonmaster 1
    Both a CRAM master and a CRAM nonmaster 2

Sizing channel storage

  • In the XECB version:

    For each master channel that is opened by a program, an Internal Interregional Control Block (IICB) is created. To compute the amount of storage required for each IICB (I):

    I = i * 128

    where i is (32 + (40 * number of threads))/128, rounded up to the next integer.

    For example, if the number of master channels being opened is 3, and the channels have 4, 5, and 2 threads, respectively, the computation is:

    Channel 1 i = ((32 + (40 * 4))/128) rounded up to next integer i = rounded up (1.5) = 2 I = 2 * 128 = 256 Channel 2 i = ((32 + (40 * 5))/128) rounded up to next integer i = rounded up (1.8) = 2 I = 2 * 128 = 256 Channel 3 i = ((32 + (40 * 2))/128) rounded up to next integer i = rounded up (0.8) = 1 I = 1 * 128 = 128

    The sum of the values of I (640 bytes) calculated for each channel is the total channel storage requirement.

  • In the XPCC version:

    For each channel opened in the master environment, the storage requirement is:

    B = (p + t + 1) * 128 bytes

    where:

    • p is (160 + 40 * t)/128, rounded up to the next highest integer.
    • t is the number of threads in the channel.

    The storage requirement for each nonmaster thread is 256 bytes. The total storage requirement is computed by:

    C = 256 * t bytes

SNAPCRAM utility for z/VSE

The following JCL statements are required to execute the SNAPCRAM utility:

//JOB SNAPCRAM //DLBL M204LIB,'M204.PROD.LIBRARY' //EXTENT SYSnnn,... //LIBDEF PHASE,SEARCH=M204LIB.V411 //EXEC SNAPCRAM,SIZE=AUTO /&

SNAPCRAM interacts with the operator in the following way:

  1. As part of its initialization process, the utility asks for a command with an ENTER COMMAND prompt on the console. Enter one of the following SET commands:
    • XECB version:

      SET COUNT=nnn,INTERVAL=iii

    • XPCC version:

      SET NAME=channel,COUNT=nnn,INTERVAL=iii

    Where:

    channel One of the active ONLINE system channel names for which a SNAP dump is requested.
    nnn Number of dumps requested. The default is 1 dump.
    iii Time interval between dumps (in seconds). The default is 5 seconds.

    NAME, COUNT, and INTERVAL can be abbreviated to N, C, and I.

    SET is useful for tracing CRAM control blocks when CRAM is not in a soft wait state.

    RUN is issued after SET and begins the dump.

    STOP terminates the SNAPCRAM operation.

  2. After the specified number of dumps has been produced, SNAPCRAM redisplays ENTER COMMAND.

    To interrupt the dump, issue the z/VSE MSG pp command, where pp is the SYSLOG ID of the partition in which SNAPCRAM is running. The ENTER COMMAND prompt is displayed after the interruption.

CRAM IFSTRT IFAM2 (IODEV=23) requirements

IFAM2 is a Model 204 Host Language Interface (HLI) facility that supports host language calls to a Model 204 Online from one or more user-written, host language programs. The host languages supported are COBOL, FORTRAN, PL/I, ASSEMBLER, or C. The user-written programs normally run as separate jobs in other regions or partitions, and they connect through the CRAM-SVC or CRAM-XDM to a Model 204 Online for database access. Each user program must be linked with a small interface module (IFIF) to enable communication between the user program and the Model 204 Online region.

Each IFAM2 (IFSTRT) HLI thread is defined by an IODEV=23 line in the CCAIN input stream of the Model 204 Online.

In a z/OS environment
  • Communication between IFAM2 and user-written host language programs requires CRAM.
  • Support for IFAM2 and CICS is provided. Host language applications can run in 31-bit addressing mode.
In a z/VSE environment
  • IFAM2 requires CRAM for the transfer of data and commands between the Online configuration in another z/VSE partition and the user program.

The partition in which IFAM2 application programs are run must have access to a core image library containing the modules IGCLM244 and CRAMSWT.

  • You must initialize the Online program with one IODEV=23 for each concurrent IFAM2 thread in use.
  • For database files accessed by the IFAM2 program, you must provide label information in the JCL that executes the Online program with which the IFAM2 program is communicating.

Multiple Online copies on a single system

When running multiple Onlines concurrently, you access a specific Online by defining an alternate channel name for that Online and specifying the name in an IFAM CALL. Concurrently operating Onlines require different names for their CRAM channels. If duplicate channel names are used, the second version's job is terminated with a job step return code of 96.

The "Default and alternate channel names" table in the Communicating with multiple regions of Model 204 section shows the default CRAM channel names and how to establish a connection using an alternate channel name.

CICS Interface

For information about CICS and IODEV 23 threads, see IFAM2 jobs: Running under CICS.

CRAM IFDIAL IFAM2 (IODEV=29) parameters

The following parameter settings are required for IFDIAL protocol IFAM2 line-at-a-time threads (IODEV=29). For general information about these parameters, see User environment control parameters. For more information about IFDIAL IFAM2 and CRAM, see IFAM2 jobs.

  • INCCC can be set to 0 or any setting up to 32K-4.
  • INMRL must be less than or equal to LIBUFF-4. LIBUFF can be set to any value up to 32K for the IFDIAL expanded communication buffer.
  • OUTCCC can be set to 0 or any setting up to 32K-4. It must not be larger than OUTMRL.
  • OUTMRL must be less than or equal to LOBUFF-4. LOBUFF can be set to any value up to 32K for the IFDIAL expanded communication buffer. An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.
  • First user statement (POLLNO=1) must be set with the largest CRAM buffer size (INMRL, OUTMRL). The CRAM OPEN must be performed with the largest buffer size to be used.

CICS Interface

For information about CICS and IODEV 23 threads, see IFAM2 jobs: Running under CICS.

SQL server threads (IODEV=19)

Model 204 requires a pool of threads to support server control of Horizon SQL connections. The system manager must define these threads in the CCAIN stream as part of the Online startup configuration.

IODEV

Defines thread for...

You must define this thread for...

19

Model 204 SQL Horizon

All Connect configurations.

You have the opportunity to try up to two IODEV 19 threads without additional expense. If you want additional threads, please notify Technical Support.

For complete information on Model 204 SQL system management, including SQL catalog and procedure file maintenance, SQL parameters and statistics, and processgroup definitions, see the Model 204 SQL processing topics.

Coding the IODEV=19 line

Defining the IODEV=19 thread requires specifying or changing the following parameters. For an example of the specification of an IODEV=19 line, see Example for z/VM.

Note: Define these as the last IODEV in your CCAIN as some of the parameters could have an affect on other IODEV threads.

NOTHREAD

You can insert several IODEV=19 lines in the CCAIN stream. On the first line defining the SQL thread, include the NOTHREAD parameter to indicate the number of SQL threads to be allocated. Set NOTHREAD to the number of concurrent Connect conversations to be supported.

SQLBUFSZ

SQLBUFSZ is a required resettable User 0 parameter that corresponds to the size of the Model 204 SQL Server buffer that assembles incoming SQL messages from a receiving buffer (in CRAM, IUCV, or Horizon). The SQLBUFSZ value defines the maximum length of an incoming SQL message.

Because the largest incoming SQL message is likely to be a DDL transaction, set SQLBUFSZ large enough to accommodate your largest DDL transaction plus 50 bytes of overhead. You can also monitor the Model 204 SQLI statistic to determine the size of the largest SQL input request.

The recommended initial value for this parameter is 100000. Specify it on the first IODEV=19 line.

INMRL

INMRL is a user parameter that determines the maximum input line length for an I/O device as well as the maximum length of an internal Model 204 buffer. You must set INMRL to a value greater than or equal to 500 (characters) for z/OS IODEV 19 threads. Specify it on the first IODEV=19 line.

Processing complex SQL statements might require a larger INMRL setting. If the INMRL buffer capacity is exceeded, you get the Model 204 error message:

INVALID STRING ARGUMENT

Increase INMRL by 50% and rerun your request.

NSUBTKS

Increase the User 0 NSUBTKS parameter by 3 per open Horizon link for Connect processing.

SQLIQBSZ

The user parameter SQLIQBSZ determines the size in bytes of the internal buffer used to compile and evaluate SQL requests.

The minimum value is 2032; the maximum is 32752. The maximum setting (large enough for a 250-column table with an average column length of 30 bytes) is sufficient for most SQL applications.

Example for z/VM

The following example shows the CCAIN data stream for a z/VM job that brings up a Model 204 Online for SQL processing. This example shows sample settings of some of the CCAIN parameters described earlier in this chapter, the first two IODEV lines for each SQL IODEV, and Model 204 SQL DEFINE commands.

... LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760, LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300, MINBUF=18,MAXBUF=200,NSUBTKS=15,... SERVSIZE=700000,... . . . IODEV=49,POLLNO=1,NOTHREAD=4 IODEV=49,POLLNO=2 IODEV=49,POLLNO=3 IODEV=49,POLLNO=4 IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, - LIBUFF=6048,SQLIQBSZ=32752 IODEV=19,POLLNO=2 IODEV=19,POLLNO=3 IODEV=19,POLLNO=4 * above IODEV=49 is for RCL connections * above IODEV=19 is for SQL CONNECT* connections *-------------------------------------------------------* / * DEFINE CONNECT * SQL AND RCL LINK ETC... * / *-------------------------------------------------------* / ********************************************** DEFINE LINK TCPSQL WITH SCOPE=SYSTEM TRANSPORT=TCPSE - PROTOCOL=IP LOCALID=ANY INBUFSIZE=4096 CONNECTIONS=8 - SERVPORT=2132 DEFINE PROCESSGROUP ANY192 WITH SCOPE=SYSTEM LINK=TCPSQL - INLIMIT=8 OUTLIMIT=8 REMOTEID=192.0.0.0 LOGIN=NOTRUST - GUESTUSER=REJECT MASK=255.0.0.0 DEFINE PROCESSGROUP ANY204 WITH SCOPE=SYSTEM LINK=TCPSQL - INLIMIT=8 OUTLIMIT=8 REMOTEID=204.0.0.0 LOGIN=NOTRUST - GUESTUSER=REJECT MASK=255.0.0.0 DEFINE PROCESS CCARSQL WITH SCOPE = SYSTEM - DATALEN = 32763 FROM = (ANY192, ANY204) ********************************************************

Horizon (IODEV=27)

Horizon, the Model 204 distributed application facility, enables Model 204 applications to participate in program-to-program processing by communicating through SNA Communications Server with one or more other programs. The applications communicate over SNA LU 6.2 sessions (with a partner application that can run in the same or in a different computer) in a logical connection called a conversation. Support for such conversations is configured primarily by Model 204 DEFINE commands and is fully described in Model 204 intersystem processing and other Horizon wiki topics.

You have the opportunity to try up to two IODEV 27 threads without additional expense. If you want additional threads, contact Rocket Software.

Horizon threads are also used for SQL server processing (IODEV=19). For information about IODEV=19, see Coding the IODEV=19 line.

Managing IODEV=27 threads

In CCAIN, the system manager needs to include only IODEV=27 statements. For LU 6.2 sessions, all but the first of these statement lines have no further parameters. The first statement line includes the NOTERM parameter, which indicates the total number of IODEV=27 threads to be in the system. For IODEV=27, you can use the synonym NOTHREAD in place of NOTERM.

In a Horizon conversation, an application program either initiates the conversation (client) or is started up by a request for a conversation from a partner application (server). IODEV=27 statements are required for a Model 204 ONLINE only if it has server applications that can be started up by clients in the network. The number of IODEV=27 lines determines the maximum number of server applications that the ONLINE can allow to run concurrently. This number has no effect on the number of concurrent conversations that client applications on the local system can initiate on other remote systems.

IODEV=27 threads are thus needed only on one end of a Horizon conversation: the server end. Since the client end is started up by a request from a local user and not by a request from a remote program, the client is part of the local user thread. As such, the client is supported by whatever IODEV statement was used to set up that user thread.

Support for the additional SNA Communications Server APPL required with Horizon is configured in DEFINE commands rather than in CCAIN, as explained in Defining the network to SNA Communications Server.

IUCV (IODEV=39, 41, 43)

A Model 204 Online can be run as multiuser or single-user (batch) operation, or single-user within a user's z/VM virtual machine. BATCH204 is not supported, but can be simulated by executing the ONLINE module in a CMSBATCH machine or in a user-defined virtual machine.

Communication between an individual z/VM user machine and the Model 204 service machine running in a separate z/VM virtual machine is provided through IUCV. The access path between a CMS terminal user and Model 204 through IUCV is established by means of a channel that is defined on User 0's parameter line. Each channel name must be unique within the Model 204 service machine. If no name is specified, defaults are used.

For example, the following statement connects a user to a Model 204 service machine:

M204 USER machineid CHAN M204VMFS

Where:

  • machineid is the name of the service machine and must be specified.
  • M204VMFS is the channel name.

M204 command (CMS) describes the M204 command in detail.

Parameters for IUCV channel names

The following table lists the parameters used to specify channel names:

IODEV setting

Parameter

Default name

You can name an alternate channel on the...

39

VMIOCHNL

M204VMIO

VMIOCHNL parameter.

41

VMFSCHNL

M204VMFS

VMFSCHNL parameter. Used in partner process communication and in communication with 3270 and 3270-compatible local and remote terminals.

43

VMIFCHNL

M204VMIF

VMIFCHNL parameter.

Programs required for the IUCV CMS Interface

The programs required to support the IUCV CMS Interface in communicating with ONLINE configurations operating in a virtual machine are distributed on a CMS format tape. The "CMS files required for the IUCV Interface" table, below, lists the required files. Information about installation is found in the Rocket Model 204 Installation Guide for IBM z/VM, version 7.4.

CMS files required for the IUCV Interface

File name

File type

Function

M204

EXEC

Initiates communication between the user and Model 204

M204

HELPCMS

Provides HELP information for M204 command syntax

M204IFAM

EXEC

Aids in establishing an HLI connection to Model 204

M204IFAM

TXTLIB

Specifies the library of object modules that must be included in IFAM2 programs under CMS

M204INFO

MODULE

Provides information about the CMS environment

M204USR

LOADLIB

Provides interactive access to Model 204 and parses the command string, but used for nucleus extension

M204USR

MODULE

Provides interactive access to Model 204 and parses the command string

Interactive access (M204USR MODULE)

Interactive access to Model 204 from CMS, which is provided by the M204USR MODULE file, permits a user at a terminal to communicate with Model 204 executing on another virtual machine under CMS.

The M204USR MODULE file executes in the CMS user area in the following manner:

  1. Parses a command string that defines the parameters of a communication interface between CMS and Model 204.
  2. Uses these parameters to establish the connection between the user's virtual machine and Model 204.
  3. Accepts data for display and reads input from the terminal for transmission to Model 204 through IUCV.

M204USR MODULE provides the IUCV interface that allows a CMS user to communicate with a Model 204 Online running in a CMS service machine. You can run the interface in either the user area, a discontiguous saved segment (DCSS), or a nucleus extension. The TPROCESS communication facility requires IUCV to be run as a saved segment or a nucleus extension. Saved Segments are discussed in the Rocket Model 204 Installation Guide for IBM z/VM, version 7.4.

The M204USR MODULE and a load library (M204USR LOADLIB) for the user-area and nucleus extension versions are built by the M204GEN EXEC. The DCSS version (M204USR) is built by M204XGEN EXEC. Keyword options specified in the distributed M204 EXEC can execute in any of the three nodes. If no options are specified, the default is DCSS.

Line-at-a-time (IODEV=39)

The IUCV line mode thread is used to communicate with any terminal supported by z/VM. Determine the buffer size by the value of MAX(INMRL,OUTMRL)-12 bytes. (See User environment control parameters for a summary of user parameters.)

  • INMRL must be less than or equal to LIBUFF minus 4. You can set LIBUFF to any value up to 32K for the IFDIAL expanded communication buffer.
  • OUTMRL must be less than or equal to LOBUFF. You can set LOBUFF to any value up to 32K for IFDIAL expanded communication buffer.

The maximum of (INMRL, OUTMRL) plus 4 determines the size of the CRAM buffer. INMRL determines the maximum length of data that can be transferred for input to Model 204. OUTMRL determines the maximum length of data that can be transferred as output from Model 204.

An optional length parameter on the IFDIAL, IFWRITE, or IFREAD calls can be the standard default lengths for both input and output or an override of either default.

  • You can set OUTCCC to 0 or any setting up to 32K-4. It must not be larger than OUTMRL.
  • You can set INCCC to 0 or any setting up to 32K-4.

IUCV full-screen (IODEV=41)

The full-screen mode thread is used to communicate with IBM 3270 and compatible local and remote display terminals. This thread is also used in partner process communication.

The buffer size is 12 less than the value of the LOUTPB parameter. For full-screen I/O, set LOUTPB to at least 24044.

IFAM2 (IODEV=43)

In a CMS environment, Model 204, when executing in the service virtual machine, communicates with host language programs that run in one or more CMS virtual machines.

When using IFAM2:

  • You can use z/VSE macros within IFAM2 programs.
  • You can compile IFAM2 programs with a z/VSE compiler.
  • IFAM2 provides multithread access to Model 204 files from a host language program.
  • You define the Model 204 files accessed by the host language programs to the service machine just as you define other database files. Define application program files (if any) in the user's CMS virtual machine.

IUCV is not supported in the VAE mode of z/VSE operating systems.

RCL thread (IODEV=49)

Model 204 requires a pool of Horizon threads to support server control of RCL connections. The system manager must define these threads in the CCAIN stream as part of the Online startup configuration.

IODEV=49 defines a Model 204 Remote Command Line (RCL) Horizon thread. The communication software calls a server module, which recognizes the command data coming to an IODEV=49 input thread and passes it to the routine that processes all Model 204 commands. Each RCL thread requires an IODEV=49 statement in the CCAIN stream.

Using an IODEV=49 thread, all output generated on the mainframe Model 204 server by the executing commands is formatted as if it were retrieved from an SQL table composed of a single column of varying character data. Thus, the client application can retrieve the data using SQLFetch commands.

The following example defines two IODEV=49 threads:

IODEV=49, POLLNO=1, NOTHREAD=2 IODEV=49, POLLNO=2

You have the opportunity to try up to two IODEV 49 threads without additional expense. If you want additional threads, please notify Technical Support.

Setting the NOTHREAD parameter

You can insert a number of IODEV=49 lines in the CCAIN stream. On the first line defining the RCL thread, include the NOTHREAD parameter to indicate the number of RCL threads to be allocated. Set NOTHREAD to the number of supported concurrent Connect RCL connections. The maximum must equal the number of concurrent Connect users specified in your purchase agreement for the product.

M204 command (CMS)

The M204 command establishes a connection with the Model 204 database management system, which allows logon and use of Model 204.

M204 syntax

The general form of the M204 command is:

M204 [options]

The options format is:

[LINE | DISPLAY | DCSS | NUCEXT | UAREA] [USERID userid] [CHANNEL channel] [LOGIN | NOLOGIN] [DISCONN string] [SUBSET string] [CMD filename] [ONLINE | IFDIAL]

Where:

  • LINE specifies a line mode connection. LINE is the default for all terminals except 3270 display terminals.
  • DISPLAY (abbreviated as DISP) specifies a full-screen mode display. DISPLAY is the default for 3270 terminals.

    If DISPLAY is selected as the default and the CHANNEL parameter is not specified, an unsuccessful attempt to obtain a connection causes an automatic attempt to connect in LINE mode.

  • DCSS causes the EXEC to load the saved segment version of the Model 204 IUCV Interface program (M204USR). This is the default.
  • NUCEXT causes the EXEC to load the Model 204 IUCV Interface program as a nucleus extension.
  • UAREA causes the EXEC to run the Model 204 IUCV Interface program by running a module in the user area.
  • USERID (abbreviated as USER) specifies the user identifier of the virtual machine in which the Model 204 database management system is executing.

    An installation-dependent default value is provided for the USERID parameter if it is not specified explicitly. If the parameter value is specified as an asterisk (*), Model 204 is invoked in single-user mode on the user's virtual machine.

  • CHANNEL (abbreviated as CHAN) specifies the Model 204 channel connection. Installation-dependent defaults are provided for LINE and DISPLAY mode connections if an explicit CHANNEL parameter value is not specified.

    The CHANNEL option is ignored if Model 204 is invoked in single-user mode.

  • LOGIN (abbreviated as LOG) specifies an automatically generated initial LOGIN command. The LOGIN option is ignored if Model 204 is invoked in single-user mode.
  • NOLOGIN (abbreviated as NOLO) specifies no automatically generated initial LOGIN command. The NOLOGIN option is ignored if Model 204 is invoked in single-user mode.
  • DISCONN (abbreviated as DISC) string specifies the character string recognized as the Model 204 disconnect sequence.

    DISCONN causes transmission of a DISCONNECT command to Model 204 if the designated disconnect string is identified as the only input data on the screen. DISCONN is ignored if Model 204 is invoked in single-user mode.

  • SUBSET (abbreviated as SUBS) string specifies the character string recognized as the CMS SUBSET escape sequence.

    SUBSET causes CMS SUBSET to be entered if the designated escape sequence is identified as the only input data on the screen. SUBSET is ignored if Model 204 is invoked in single-user mode.

  • CMD filename specifies the CMS file used to supply input data for Model204. (See Command File facility, which follows.)

    Records in the file are read one at a time and used as input in response to requests from Model 204. If the end of the file is reached before the connection with Model 204 is broken, subsequent input is requested from the terminal.

  • ONLINE specifies, for single user invocation (USER *), a normal Online connection type. A default setup EXEC named SINGLUSR EXEC is assumed. ONLINE is the default connection type.
  • IFDIAL specifies, for single-user invocation (USER *), to run an IFDIAL connection type. A default setup EXEC named SINGDIAL EXEC is assumed.

Command File facility

The initial entry to a Model 204 application from CMS can be preprogrammed by using the CMD option of the M204 command to specify a file of commands as the initial source of input to Model 204 from CMS. The command file can include applications that combine the use of Model 204 with other CMS-based facilities.

Only a single command file can be used to provide input at the beginning of a Model 204 session. The following limitations apply:

  • Only the first field can be filled in on a full-screen panel.
  • Program function and other interrupt keys cannot be signaled. Pressing the Enter key is simulated for each line.
  • Conditional execution of commands, interpretation of screen contents, or determination of the effects of input are not provided.

A command file is implemented by defining the file with the keyword CMD, followed by a 1- to 8-character file name. The command file can reside on any accessed disk in the CMS user's virtual machine. A file type of M204CMND is required for the file specified in the CMD option.

For example, the following statement causes CMS to read the file name with a file type of M204CMND and pass the file contents to Model 204:

M204 USER userid CMD filename

The following statements are typical of a command file:

LOGIN OPEN TEST DICTIONARY

Where:

  • Login password prompts are bypassed.
  • OPEN TEST does not require a password.
  • DICTIONARY is the application automatically presented to the user.

Command file processing

The command file can be defined as either fixed or variable format with a record length of up to 256 characters. Variable format is recommended.

If a full-screen thread is used, each line of the file is treated as a single full-screen data stream. Each line is presented to Model 204 as if the Enter key were pressed immediately after the data.

If a line-mode thread is used, each line acts as the response to a terminal read request from Model 204. Each line is presented to Model 204 as if the Return key were pressed immediately after the data.

Automatic logon

To avoid including Model 204 passwords in the command file and compromising the security of the Model 204 system, the use of the automatic logon feature for IUCV threads is recommended:

  • Automatic logon can be made the default for IUCV threads by modifying the default section of the distribution tape version of M204 EXEC from &LOGIN to &LOGIN=LOGIN.
  • Automatically generated login defaults to the CMS user ID invoking the M204 EXEC when no other account is specified. Entering the login with a new ID overrides the default user ID.
  • Account name default in the initial login command can be overridden if the M204 EXEC is invoked without automatically generating the initial login command (see below) and the LOGIN or LOGON command is issued with the user ID.
  • If the SYSOPT parameter is not set to require logins, Model 204 grants superuser privileges even though the login failed.
  • Automatic logon cannot be generated for a single-user version of Model 204. However, the following CCAIN input stream provides a substitute:

    PAGESZ=6184,NUSERS=1,NSERVS=1 LOGIN

    The M204 EXEC default automatic login can be overridden with:

    M204 USERID userid CHANNEL channel NOLOGIN

    The M204 EXEC default manual login can be overridden with:

    M204 USERID userid CHANNEL channel LOGIN

Bypassing password prompts

Use the LOGCTL command with the NP option to bypass password prompts:

LOGCTL NP CMS

LOGCTL NP CMS remains in effect until the command is reversed with:

LOGCTL P CMS

To bypass password prompts, the following conditions are required:

  • A LOGCTL NP CMS command must have been issued. The command applies to all CCASTAT users.
  • The user ID on any subsequent LOGIN or LOGON command must equal the CMS user ID of the CMS virtual machine from which the login originated.

    If that user ID is not identical to the CMS user ID, Model 204 then prompts for a password, and continues login processing.

  • The user ID used in the LOGIN command must be located in the password table.

    If the user ID is not in the password table, Model 204 prompts for a password and then rejects the login command.

NOTE: Any LOGIN command without a user ID, will successfully logon as the CMS user ID of the user who issued the LOGIN command, assuming the CMS user ID is found in CCASTAT. Also, no password prompt will be issued.

CMS service machine console (ALTIODEV=45, 47)

ALTIODEV, applicable only to CMS single-user mode, is the IODEV number for continuing User 0's input. After end-of-file is reached in the User 0 file, the input for User 0 is directed to the specified device.

Setting the ALTIODEV parameter

To set the ALTIODEV parameter, place it on the program stack in the single-user EXEC rather than defining it in the CCAIN file. All other FILEDEF and CCAIN parameters are the same as those for multiple-user execution, except that no other users are defined and no IODEVs are coded.

Executing in single-user mode

To execute in single-user mode:

  1. Customize the single-user EXEC and single-user CCAIN (see CMS CCAIN file).
  2. Enter:

    M204 USERID *

User environment control parameters

The following table lists parameters that you can set for individual users, either on User 0's parameter line or on the user's parameter line. Not all parameters can be reset.

For additional information about each parameter, see:

User environment control parameters

Parameter

Specifies...

AUTOSYS

Automatic application subsystem invoked upon login. The default is a null string.

CAUDIT

Type of auditing of input lines for the production of CI, CS, or CP journal lines. The default is 0.

EDIT

Controls the type of editing performed on input lines. The default is 0.

FSATTN

Key interpreted as an attention key of 3270 full-screen terminals. The default is PA1 (X'6C').

FSTTMOPT

Full-screen terminal options. The default is 0.

HDRCTL

Page header formatting. The default is 0.

HTLEN

Maximum length of a SOUL header or trailer. The default is 132.

INCCC

Input continuation character column. When data is input, any nonblank character appearing in column number INCCC indicates that input is continued on the following line.

The value of MODEL (see below) determines the default value of INCCC.

A hyphen can be used to continue long input lines within SOUL requests and some commands.

INMRL

Maximum input line length.

The value of MODEL determines the default value of INMRL.

The recommended value for SQL processing is at least 500.

INPUT

Name of the input file on a device type (BSAM, or teletype) receiving input. The INPUT name must match the names specified on FILEDEF or JCL DD statements.

IODEV

Input/output device type.

LAUDIT

Logical input line audit. The default is 1.

LCPDLST

Dynamically allocated space for the C pattern-matcher. The default is 2176. For SQL processing, use the default.

LECHO

Echoing of user input; set it to 0 for Online users. The default is 1, which copies every line from the input device to the output device. For Online users (unlike User 0) these devices are the same.

LFSCB

Length of the full-screen buffer. The default is 8 (as of version 7.7).
(In version 7.6 or earlier, the default is 0.)

LFTBL

Length of the file group table (FTBL). The default is 1000. Adjustment to the FTBL size can be made with the UTABLE command while files are open, including when the user is in a subsystem.

LGTBL

Length of the global variable table (GTBL). The default is 288, which is required for a subsystem.

LIBUFF

Length of the input buffer used for input lines from CCAIN or from a user's terminal. LIBUFF must be three bytes longer than the longest line or record read into it. Longer lines are rejected with an error message. The default is 250.

If an input line is continued with a nonblank character in column INCCC, the number of characters in the input line (the original line and all continuations, not including the continuation characters) is limited to the value of LIBUFF.

The value of LIBUFF is usually much higher for IFAM threads than for terminal users.

For SQL processing, the recommended value is 10000.

LITBL

Length of the dummy string and $Read response table (ITBL). The default is 8 (as of version 7.7).
(In version 7.6 or earlier, the default is 0.)

LNTBL

Number of 12-byte entries in NTBL. The default is 50.

LOBUFF

Length of the output buffer used for output lines to CCAAUDIT, CCAJRNL, CCAPRINT, a user's terminal, or a directed output (USE) data set. The value of LOBUFF must be greater than or equal to the value of OUTMRL. The recommended value for SQL processing is 5000. The default is 256.

LOGONENQ

Use of a unique user ID for logon to a single ONLINE system from specific terminals. LOGONENQ cannot be reset. The default is 0. All nonunique user ID terminals must be listed before unique user ID terminals. Specification of LOGONENQ on an IODEV specification affects all subsequent IODEV definitions.

LOUTPB

Length of the output page buffer for 3270 and 3275 display stations. The minimum is determined by the value of MODEL.

A nonzero value, not greater than the page size, must be specified for terminals supporting active backpaging or full screen usage. 3000 is recommended for full screen use. IODEV=11, used with the pseudo conversational interface, requires a value slightly larger than the screen size. Model 5 terminals may require over 3000. 2130 is suggested for other uses.

LPDLST

Length of the user pushdown list. The default is 2600. The recommended initial value for SQL processing is 32K.

LQTBL

Number of 16-byte entries in QTBL. The default is 400. LQTBL may need to be increased approximately 1% for SOUL requests to accommodate quad sum expansion.

LSTBL

Length of the character string table (STBL). The default is 600.

LTTBL

Number of 4-byte entries in the translation table (TTBL). The default is 50. For SQL processing, the recommended initial value is 2000.

LVTBL

Number of 32-byte entries in the compiler variable table (VTBL). The default is 50.

LVLTRC

Level of SOUL INCLUDE statements reached when the given input stream is processed. Used as a diagnostic tool. The default is 0 (off).

LXTBL

Length of the security information table (XTBL). The default is 1000. Adjustment to the XTBL size can be made with the UTABLE command while files are open, including when the user is in a subsystem.

MAXHDR

Maximum number of output page header lines that can be defined within a single SOUL request. The default is 5.

MAXTRL

Maximum number of output page trailer lines that can be defined within a single SOUL request. The default is 5.

MODEL

3270 terminal model number. Establishes an appropriate screen size by setting values for:

  • INCCC
  • INMRL
  • OUTCCC
  • OUTLPP
  • OUTMRL

The default is 2.

NBKPG

Maximum number of output backpages that can be retrieved and displayed with the backpage command. The default is 0.

NORQS

Maximum number of temporary procedures saved for each user. The default is 5.

NOTERM

Number of terminals defined with the IODEV parameter as a group on user parameter lines. The default is 0. NOTERM is used in conjunction with CMS POLLNO terminals or remote User Language threads. NOTERM must be specified on the first parameter line of the sequence (the POLLNO=1 line). There are no physical lines and only one logical line for SNA Communications Server terminals and remote User Language threads.

NOUTBUF

Number of full-screen output buffers allocated and used by the Model 204 SNA Communications Server 3270 Interface.

NSUBTKS

Maximum number of pseudo subtasks that can be generated during a run. Specification of the number of subtasks applies to SNA Communications Server.

OUTCCC

Size of an output line. The default is 132 unless the MODEL parameter has been set. In that case, MODEL determines OUTCCC's default. OUTCCC is normally set to the same value as OUTMRL. A value greater than OUTMRL causes long output lines to be truncated at OUTMRL characters. If an output line is longer than OUTMRL, it is broken into sections containing up to OUTCCC-1 characters on each line.

OUTLPP

Number of lines per page, including input, output, page headers, and trailers. The default is 56 unless the MODEL parameter is set. In that case, MODEL determines the default. If OUTLPP is 0, output comes in a steady stream with no headers or trailers.

OUTMRL

Maximum output line length. The default is 132 unless the MODEL parameter is set. Lines are shorter than OUTCCC if OUTCCC is greater than 0 and less than or equal to OUTMRL. In that case, MODEL determines OUTMRL's default.

OUTPUT

Name of the output file on a device type (BSAM, or teletype) receiving output. The OUTPUT name must match the names specified on FILEDEFs or JCL DD statements.

POLLNO

Relative position of terminals in the Online user queue. Arrange POLLNO values consecutively from 1 to the highest number. The default is 0.

PRIORITY

User's priority class. Settings are LOW, STANDARD, and HIGH. Priority decisions are made on the basis of internal priority settings and ranges. (See the discussion of the PRIORITY parameter and command in Priority scheduling.) The default is STANDARD.

RETRVKEY

PF key used to retrieve a previous terminal input line. 280 bytes of spare core are required for each user that has a defined retrieve key. The default is 0.

SERVNSA

(server non-swappable areas) A bit setting indicating the tables that you want to allocate in above the bar storage.

SERVNSSZ

(server non-swappable size) The amount of space in bytes required for the above the bar server tables per user. SERVNSSZ is a user 0 parameter applicable to all users.

SQLBUFSZ

Size of the Model 204 SQL Server buffer that assembles incoming SQL messages from a Horizon, CRAM SQL, or IUCV SQL buffer. The recommended size is 100000.

SQLIQBSZ

SQL internal query buffer size. The recommended size is 32752.

TERMBUF

Number of terminal SNA Communications Server input/output buffers allocated. The default is 1.

TERMID

Logical terminal name associating a user ID with a particular terminal or thread for an entire run. TERMID is applicable only to threads connected through an SNA Communications Server Interface. The default is blanks.

TERMOPT

Terminal option setting. Valid settings depend on the type of terminal and access method used. The default is 0. Traffic across an SNA Communications Server (3270) network is reduced by a setting of 2 (no definite response).

TIMEOUT

At initialization, the number of seconds a thread can remain inactive before the terminal user is logged out and files closed. The maximum value is 32767. The default is 0. If the SYSOPT parameter is set for disconnection on logout, Model 204 disconnects the terminal if the teleprocessing interface supports automatic disconnect.

Set TIMEOUT to the default of 0 for CRAM threads associated with IODEV=11, because these CRAM threads are restarted but not freed after a time-out.