Defining the user environment (CCAIN): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(22 intermediate revisions by 4 users not shown)
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 125: Line 125:
<td>23</td>
<td>23</td>
<td>CRAM, [[IFAM|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 />INCCC<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 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 513: Line 524:
   
   
<tr>
<tr>
<td>NSUBTSKS</td>
<td>NSUBTKS</td>
<td>IPADDR</td>
<td>IPADDR</td>
</tr>
</tr>
Line 537: Line 548:
   
   
<tr>
<tr>
<td>NSUBTSKS </td>
<td>NSUBTKS </td>
<td>INMRL</td>
<td>INMRL</td>
</tr>
</tr>
Line 678: Line 689:
==<b id="cram112329"></b>CRAM (IODEV=11, 23, 29)==
==<b id="cram112329"></b>CRAM (IODEV=11, 23, 29)==
<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 [[#Multiple Online copies on a single system|Multiple Online copies on a single system]].)</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>
Line 729: Line 740:
</table>
</table>
   
   
===Two CRAM options===
===Using CRAM on a z/OS operating system===
====Two CRAM options====
<p>
<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). 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>
Line 739: Line 752:
   
   
<ul>
<ul>
<li>CRAM SVC
<li>CRAM-SVC
<p>
<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>
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>
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>
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>
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 from <i>and before</i> the jobs of Onlines that might use that XDM. </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>
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></li>
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>
</ul>
</ul>
<p>
====CRAM-XDM performance versus CRAM SVC====
For additional background information about CRAM and its constituent modules, see [[Cross-memory facilities CRAM and M204XSVC]]. </p>
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:
 
====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 781: 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>
Line 798: Line 813:
<p>
<p>
Defining the XDM address space as non-swappable (described below in [[#Activating CRAM-XDM|Activating CRAM-XDM]]) is required.  
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 is not required but is <i>strongly recommended</i>. </p>
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>
<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>
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>
Line 819: Line 834:
<li>X'80' bit included: initializes CRAM-XDM environment </li>
<li>X'80' bit included: initializes CRAM-XDM environment </li>


<li>X'80' bit <i>not</i> included: initializes CRAM SVC environment
<li>X'80' bit <i>not</i> included: initializes CRAM-SVC environment
</ul>
</ul>
<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 [[#Communicating with multiple regions of Model 204|channels]] within the Online address space can use either the CRAM-XDM option or the CRAM SVC option, but not both.</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>


===Activating CRAM-XDM===
====CRAM OPEN processing====
<p>
<p>
To implement CRAM-XDM after you have installed and tested <var class="product">Model&nbsp;204</var>, take the following steps: </p>
CRAM can operate in two modes: converser and master/user:</p>
<ul>
<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>
   
   
<ol>
<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>
<li>[[Model 204 installation on IBM z/OS#CRAM|Install CRAM-XDM]].</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>Bring down the Online(s) with which you want to test this new CRAM version. </li>
====CRAM storage requirements====
<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>


<li>Start CRAM-XDM:
<ul>
<ol type="a">
<li><b>CRAM CSA space for HLI</b>
<li>Make sure the XDM address space is non-swappable.
<ul>  
<li>CRAM-XDM
<p>
<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>
The following Model&nbsp;204 7.7 calculation determines the approximate requirements for each active XDM region:</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 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.
<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>
</p>
<p>
Where (the values shown are in hexadecimal):</p>
   
   
<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>
<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>1888 is the size of the XMEMCSA module (resident in CSA).</li>
 
<li><code>TIME=NOLIMIT</code> is required to initialize M204XDM. </li>
<li>30 is the SSACB length.</li>
</ul>
<blockquote class="note">
<li><var class="term">onln</var> is the SSCB length.</li>
<b>Notes:</b>  
<ul>
<li><var class="term">chnl</var> is the IICB length.</li>
<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><var class="term">cnct</var> is the UICB length.</li>
<li>You must submit the M204XDM job every time you IPL z/OS. </li>
</ul></blockquote></li>
<li><var class="term">asid</var> is the ASID table entry.</li>
</ol>
   
   
<li>Prepare the job to bring up the Online:
<li><var class="term">trace</var> is the trace table (length default is 3K per channel).</li>
<ol type="a">
</ul><br></li>
<li>Set the 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.
 
<p id="204xsvc" 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 <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.
<li>CRAM-SVC
<p>
<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>
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>
</ol></li>
</ul></li>


<li>Run the Online job.
<li><b>Virtual storage</b>
<p>
<p>
When the Online comes up, its audit trail reports the XDM subsystem to which it is connecting: </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="code">AD ///  M204.2157: M204XSVC version = 7.7.0G  10/13/16
<p class="note"><b>Note:</b> This same amount of space is also required in CSA if CRAM-SVC is used. </p>
AD ///  IGCLM244 7.7.0G  10/13/16
   
AD ///  SUBSYSTEM NAME = V770 </p></li>
<p class="code">Virtual storage requirement = Min(<i>nif</i>,1) * (68 + (<i>nif</i> * (IFAMBS + 100)))
</ol>
+ Min(<i>nul</i>,1) * (68 + (<i>nul</i> * (Max(INMRL,OUTMRL) + 100)))
 
+ Min(<i>nfs</i>,1) * (68 + (<i>nfs</i> * (LOUTPB + 100)))
===Managing CRAM-XDM===
</p>
 
====Care with CRAM-XDM LXs====
<p>
<p>
As [[#Two CRAM options|mentioned earlier]], CRAM-XDM uses a system LX.
Where:</p>
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>
 
====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>
   
   
<ul>
<ul>
<li><b>Using console commands</b>
<li><code>Min</code> is the Minimum function.</li>
<p>
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>
<li><code>Max</code> is the Maximum function.</li>
   
   
<p class="syntax">*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
<li><var class="term">nif</var> is the number of <code>IODEV=23</code> users.</li>
</p>
<p>
Where:</p>
   
   
<ul>
<li><var class="term">nul</var> is the number of <code>IODEV=29</code> users.</li>
<li><var class="term">nn</var> is the message number to reply to.</li>
   
   
<li><var class="term">jobname</var> is the end-user-defined jobname running M204XDM.</li>
<li><var class="term">nfs</var> is the number of <code>IODEV=11</code> users.</li>
</ul>
   
   
<li>The <var>IFAMBS</var> parameter sets the IFAM2 block size.
<p>
<p>
The following table lists the available <var>MONITOR</var> commands:</p>
<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>
   
   
<table class="thJustBold">
<li><var>LOUTPB</var> is the length of the output page buffer required for full-screen features. </li>
<caption>Available MONITOR commands</caption>
</ul></li>
<tr class="head"><th>Command</th>
</ul>
<th>Description</th>
 
</tr>
====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>
<tr>
<p>
<th>MONITOR<br><i>or</i><br>MONITOR,ONLINES<br><i>or</i><br>ONLINES</th>
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.
<td>Lists all Onlines connected to an XDM master; can be abbreviated:
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>
<ul>
<p>
<li>M/MO/MON, and so on.</li>
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>
<li>MONITOR,O/ON/ONL, and so on.</li>
<p>
<li>O/ON/ONL, and so on.</li>
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>
</ul></td>
<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>
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>
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>
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.</p>
<table>
<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>To define an alternate channel name...</p> </th>
</tr>
</tr>
   
   
<tr>
<tr>
<th>MONITOR,USERS<br><i>or</i><br>USERS</th>
<td><p>11 </p></td>
<td>Lists all jobs using XDM to connect to any Online; can be abbreviated: 
<td><p>Full-screen</p></td>
<ul>
<td><p>M204FULL</p>
<li>MONITOR,U/US/USE and so on.  </li>
</td>
<li>U/US/USE and so on. </li>
<td><p>Specify a <var>CRFSCHNL</var> parameter value on the User 0 parameter line.</p></td>
</ul></td>
</tr>
</tr>
   
   
<tr>
<tr>
<th>MONITOR,ONLINE=<i>jobname</i><br><i>or</i><br>ONLINE=<i>jobname</i> </th>
<td><p>23</p></td>
<td>Lists all jobs using XDM to connect to the specified Online. </td>
<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>
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>
<tr>
<td><p>29</p></td>
<td>
<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>
</tr>
</table>
</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="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>
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>
where <var class="term">xxxx</var> is the [[#xdmjob|secondary subsystem name]] used by the CRAM-XDM region.  </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>
=====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>
   
   
<p class="code">M204XDM.313: XDM Master Jobname=CAT141A ACTIVE (Subsystem=CAT1)
<p class="code">// Job Card...
_M204XDM.314:    Online Jobname=CAT108  Users=0
//SNAPCRAM EXEC PGM=SNAPCRAM
_M204XDM.314:    Online Jobname=CAT11C  Users=4
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
_M204XDM.314:    Online Jobname=CAT11S  Users=2
//        DD DSN=M204.CRAMLIB,DISP=SHR
_M204XDM.314:    Online Jobname=CAT112  Users=0
//CCASNAP DD SYSOUT=A
_M204XDM.314:    Online Jobname=CAT109  Users=6
/*
_M204XDM.314:    Online Jobname=CAT102  Users=0
_M204XDM.318: (Totals)  Onlines=6  Users=12
</p>
</p>
<br></li>
<li><b>Using a batch job</b>
<p>
<p>
To monitor XDM, use a standalone batch job, when: </p>
If CRAM is installed in a separate library, the M204.CRAMLIB concatenation shown above is required.</p>
<ul>
<li>You might not be authorized to issue console commands. </li>


<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>
===Managing CRAM-XDM===


<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>
====Care with CRAM-XDM LXs====
</ul>
<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>  
<p>  
Execute the [[#M204XMON|M204XMON]] report with the following JCL: </p>
Bouncing XDM jobs frequently could exhaust the supply of address spaces and require an IPL. </p>
 
<p class="code">//MON    EXEC  PGM=M204XMON,PARM='<i>parameter</i>'
====Activating CRAM-XDM====
//STEPLIB  DD  DSN=<i>your</i>.LOADLIB,DISP=SHR
//CCAPRINT DD  SYSOUT=* </p>
<p>
<p>
The output goes to CCAPRINT. Unless you request otherwise, no output is written to the operator console. </p>  
To implement a new version of CRAM-XDM, take the following steps: </p>
<ol>
<li>Install CRAM-XDM.
<p>
<p>
The <var class="term">parameter</var> argument string can be in one of the following forms: </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>
   
   
<p class="syntax">SSNAME=<span class="term">ssss</span>,ONLINE=<span class="term">oooooooo</span>,DETAIL=<span class="term">nnn</span>,OUTPUT=CONSOLE </p>
<li>Bring down the Online(s) with which you want to test this new CRAM version. </li>
<p>
 
or: </p>
<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 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.
   
   
<p class="syntax"><span class="term">ssss</span>
<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>
<p>Where: </p>
<p>Where: </p>
<ul>
<ul>
<li><var class="term">ssss</var> is the [[#xdmjob|CRAM z/OS subsystem name]] to report on (required). </li>
<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><var class="term">oooooooo</var> is the Online name to report on (optional). If not specified, reports on all Onlines using XDM. </li>
<li><code>TIME=NOLIMIT</code> is required to initialize M204XDM. </li>
</ul>
<li><var class="term">nnn</var> specifies what to report (optional). If not specified, defaults to 3. </li>
<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>
   
   
<li><code>CONSOLE</code> specifies that the report is sent to both the console and CCAPRINT (otherwise to CCAPRINT only). </li>
<li>Prepare the job to bring up the Online:
<ol type="a">
<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.
 
<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>
   
   
<li><code>DETAIL=<i>nnn</i></code> is the sum of the following values:
<ul>
   
<li><b>Using console commands</b>
<table>
<p>
<tr class="head">
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>
<th><p>Value</p></th>
   
<th><p>Purpose</p></th>
<p class="syntax">*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
</tr>
</p>
<p>
Where:</p>
<ul>
<li><var class="term">nn</var> is the message number to reply to.</li>
   
   
<tr>
<li><var class="term">jobname</var> is the end-user-defined jobname running M204XDM.</li>
<td><p>128</p></td>
</ul>
<td><p>Dumps XDM control blocks. </p></td>
</tr>
   
   
<tr>
<p>
<td><p>64 </p></td>
The following table lists the available <var>MONITOR</var> commands:</p>
<td><p>Interprets XDM control blocks. </p></td>
</tr>
   
   
<tr>
<table class="thJustBold">
<td><p>2 </p></td>
<caption>Available MONITOR commands</caption>
<td><p>Lists XDM Online and user details. </p></td>
<tr class="head"><th>Command</th>
<th>Description</th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>1 </p></td>
<th>MONITOR<br><i>or</i><br>MONITOR,ONLINES<br><i>or</i><br>ONLINES</th>
<td><p>Lists XDM summary information. </p></td>
<td>Lists all Onlines connected to an XDM master; can be abbreviated:
</tr>
<ul>
</table>
<li>M/MO/MON, and so on.</li>
<li>MONITOR,O/ON/ONL, and so on.</li>
<p>  
<li>O/ON/ONL, and so on.</li>
If <code>DETAIL</code> is non-zero, the return code can be one of the following values:  </p>
</ul></td>
<table>
<tr class="head">
<th><p>Value</p></th>
<th><p>Meaning</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p> 0 </p></td>
<th>MONITOR,USERS<br><i>or</i><br>USERS</th>
<td><p>Completed normally. </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> 4 </p></td>
<th>MONITOR,ONLINE=<i>jobname</i><br><i>or</i><br>ONLINE=<i>jobname</i> </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 the specified Online. </td>
</tr>
<tr>
<td><p> 8 </p></td>
<td><p> Invalid parameter: CCAPRINT failed to open, and so on. </p></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>
 
<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>
 
<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>
   
   
<tr>
<p>  
<td><p> 2 </p></td>
Execute the [[#M204XMON|M204XMON]] report with the following JCL: </p>
<td><p> XDM Onlines are active, but none have active users. </p></td>
</tr>
   
   
<tr>
<p class="code">//MON    EXEC PGM=M204XMON,PARM='<i>parameter</i>'
<td><p> 3 </p></td>
//STEPLIB  DD DSN=<i>your</i>.LOADLIB,DISP=SHR
<td><p> XDM Onlines are active, and some have active users. </p></td>
//CCAPRINT DD SYSOUT=* </p>
</tr>
   
<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====
<p id="M204XMON">
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="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>
The output goes to CCAPRINT. Unless you request otherwise, no output is written to the operator console. </p>  
<p>
<p>
The [[#Debugging CRAM SVC|SNAPCRAM utility]] is the counterpart to M204XMON that is used to debug CRAM SVC under z/OS. There is also a [[#SNAPCRAM utility for z/VSE|SNAPCRAM for z/VSE]]. </p>
The <var class="term">parameter</var> argument string can be in one of the following forms: </p>
   
   
====Shutting down XDM master from the console====
<p class="syntax">SSNAME=<span class="term">ssss</span>,ONLINE=<span class="term">oooooooo</span>,DETAIL=<span class="term">nnn</span>,OUTPUT=CONSOLE </p>
<p>
<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>
or: </p>
<p>
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
<p class="syntax"><span class="term">ssss</span>
</p>
</p>
<p>Where: </p>
<ul>
<li><var class="term">ssss</var> is the [[#xdmjob|CRAM z/OS subsystem name]] to report on (required). </li>
   
   
Where:
<li><var class="term">oooooooo</var> is the Online name to report on (optional). If not specified, reports on all Onlines using XDM. </li>
<li><var class="term">nnn</var> specifies what to report (optional). If not specified, defaults to 3. </li>
   
   
<ul>
<li><code>CONSOLE</code> specifies that the report is sent to both the console and CCAPRINT (otherwise to CCAPRINT only). </li>
<li><var class="term">nn</var> is the message number to reply to.  </li>
<li><var class="term">jobname</var> is an end-user defined job. </li>
</ul>
   
   
======Shutdown commands======
<li><code>DETAIL=<i>nnn</i></code> is the sum of the following values:
<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>
   
   
<table class="thJustBold">
<table>
<tr class="head">
<tr class="head">
<th> Command </th>
<th>Value</th>
<th> Shuts down XDM master... </th>
<th>Purpose</th>
</tr>
</tr>
   
   
<tr>
<tr>
<th>EOJ </th>
<td>128</td>
<td>If no Onlines are active.
<td>Dumps 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>64 </td>
<td>Even if Onlines are active.   
<td>Interprets XDM control blocks. </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>
</tr>
</td>
<tr>
<td>2 </td>
<td>Lists XDM Online and user details. </td>
</tr>
<tr>
<td>1 </td>
<td>Lists XDM summary information. </td>
</tr>
</table>
   
<p>  
If <code>DETAIL</code> is non-zero, the return code can be one of the following values:  </p>
<table>
<tr class="head">
<th>Value</th>
<th>Meaning</th>
</tr>
<tr>
<td>0 </td>
<td>Completed normally. </td>
</tr>
<tr>
<td>4 </td>
<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>
</tr>
</tr>
   
   
<tr>
<tr>
<th>EOJ,FORCE</th>
<td>8 </td>
<td>Without cleaning up the cross-memory environment.
<td>Invalid parameter: CCAPRINT failed to open, and so on.</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 maintenance documentation. There may be circumstances that require using the <var>FORCE</var> option or an IPL.</p>
If <code>DETAIL</code> is 0 (not usually used), the return code can be one of the following:  </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 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>
<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>
<tr>
<li><var class="product">Model&nbsp;204</var> Online termination abends.</li>
<td>0 </td>
<li>CICS applications will ASRA.</li>
<td>No XDM Onlines are active. </td>
<li>CICS might abend at shutdown.</li>
</tr>
<tr>
<td>2 </td>
<td>XDM Onlines are active, but none have active users.</td>
</tr>
<tr>
<td>3 </td>
<td>XDM Onlines are active, and some have active users.</td>
</tr>
<tr>
<td><p> 4 </p></td>
<td><p> 0C4 while processing XDM control blocks; retry. </p></td>
</tr>
</table></li>
</ul>
</ul>
</blockquote>
</li></ul>
====Debugging XDM====
The <code>M204XMON</code> utility is described above in [[#Debugging CRAM|Debugging CRAM]].


<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>
====Shutting down XDM master from the console====
 
===Using CRAM on a z/OS operating system===
<p>
<p>
As you make the recommended transition from CRAM SVC to CRAM-XDM, you can continue to run your production Onlines using CRAM SVC and at the
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>
same time begin testing the next release with CRAM-XDM. You can do this using the z/OS secondary subsystem names (SSN) facility: </p>
<ol>
<li>In the CRAM-XDM installation job ([[Model 204 CRAM link job stream for IBM z/OS|LKCRAMJ]] in RKOBJLIB) which creates module IGCLM244, specify as the <code>CRMSSN</code> parameter value a CRAM SSN you select in coordination with your systems programmers. 
<p>
<p>
You probably want to select an SSN corresponding to the new release, say <code>V770</code>. This value must also be defined by the systems programmers in SYS1.PARMLIB(IEFSSNxx). </p></li>
When the XDM master address space is active, it displays the following reply message on the operator console: </p>
 
<li>Bring up the M204XDM job (required for CRAM-XDM). That job will initialize with an SSN value of <code>V770</code>. </li>
<p class="syntax"><b></b>*<span class="term">nn</span> M204XDM.100: <span class="term">jobname</span> AWAITS COMMAND
 
</p>
<li>After the M204XDM job has initialized, bring up the Online.  
<p>
Where:
The Online will use the same IGCLM244 module as the M204XDM job, and it will also initialize with an SSN value of <code>V770</code>. </p>
<p>
Since the CRAM-XDM modules reside in a separate load library, an Online that requires a CRAM connection (<var>IODEV</var> 11, 23, or 29) must be brought up with the CRAMLIB load library as a concatenated STEPLIB (or such that the Online is able to load the CRAM IGCLM244 module). </p></li>
</ol>
   
   
====CRAM OPEN processing====
<p>
CRAM can operate in two modes: converser and master/user:</p>
<ul>
<ul>
<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><var class="term">nn</var> is the message number to reply to. </li>
<li><var class="term">jobname</var> is an end-user defined job. </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>
</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>
   
   
====Communicating with multiple regions of Model 204====
======Shutdown commands======
<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 thread and several IFSTRT 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>
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>
   
   
<p>
<table class="thJustBold">
CRAM channel names (as many as eight characters) are specified on the User 0 parameter line.  
<tr class="head">
The "Default and alternate channel names" table in the [[#Multiple Online copies on a single system|Multiple Online copies on a single system]] section shows the default CRAM channel names and how to establish a connection using an alternate channel name.</p>
<th> Command </th>
<th> Shuts down XDM master... </th>
</tr>
<tr>
<th>EOJ </th>
<td>If no Onlines are active.
<p><var>EOJ</var> is only allowed if all connections are cleanly closed.</p></td>
</tr>
<tr>
<th>EOJ,CANCEL</th>
<td>Even if Onlines are active.
<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>
<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>
   
   
====<b id="SNAPCRAM"></b>CRAM debugging====
The debugging utility for CRAM-XDM is [[#Debugging XDM|M204XMON]], and the SNAPCRAM utility is used to debug CRAM SVC. A SNAPCRAM utility also debugs [[#SNAPCRAM utility for z/VSE|CRAM under z/VSE]].
<p>
<p>
SNAPCRAM prints out the CRAM control blocks in dump format. Sample JCL for running SNAPCRAM is:</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 maintenance documentation. There may be circumstances that require using the <var>FORCE</var> option or an IPL.</p>
   
   
<p class="code">// Job Card...
<blockquote class="warn">
//SNAPCRAM EXEC PGM=SNAPCRAM
<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>
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
//        DD DSN=M204.CRAMLIB,DISP=SHR
//CCASNAP DD  SYSOUT=A
//SYSPRINT DD  SYSOUT=A
//CCAPRINT DD  SYSOUT=A
/*
//</p>
<p>
<p>
If CRAM is installed in a separate library, the M204.CRAMLIB concatenation shown above is required.</p>
If you issue <code>EOJ,CANCEL</code> or <code>EOJ,FORCE</code> commands, any of the following events are possible:</p>
<ul>
<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 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>


====Required parameter settings for IODEV=29====
===Using CRAM on a z/VSE operating system===
<p>
<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]].  </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>
   
   
<ul>
<table>
<li><var>INCCC</var> can be set to 0 or any setting up to <code>32K-4</code>.</li>
<tr class="head">
<th>Version... </th>
<th>Is compatible with...</th>
</tr>
   
   
<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>
<tr>
<td>Cross-Partition Event Control Blocks (XECB) </td>
<td>Single-address-space mode of z/VSE, only.</td></tr>
   
   
<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>
<td nowrap>Cross-Partition Communications Services (XPCC) </td>
<td>Both the single-address-space mode and the multiple-address-space mode of z/VSE. </td></tr>
</table>
   
   
<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>
<p>
System requirements for the XECB and XPCC versions are explained in the following sections.</p>
   
   
<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>
====Performance====
</ul>
<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>


====CRAM storage requirements====
<li>Mark the CRAM Transient as a Move Mode transient in the SDL. </li>
</ol>
<p>
<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>
Neither the load module nor the subtasks are SVA eligible. Any attempt to place these modules in the SVA causes errors.</p>
 
<ul>
====System requirements (XECB version)====
<li><b>CRAM CSA space for HLI</b>
<ul>
<li>CRAM-XDM
<p>
<p>
The following Model&nbsp;204 7.7 calculation determines the approximate requirements for each active XDM region:</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 = 1888 + 30 + (60 * <i>onln</i>) + (50 * <i>chnl</i>) + (60 * <i>cnct</i>) + (20 * <i>asid</i>) + <i>trace</i>
<p class="code">number of XECBs = 5 * (C + N)
</p>
</p>
<p>
Where:
Where (the values shown are in hexadecimal):</p>
   
   
<ul>
<ul>
<li>1888 is the size of the XMEMCSA module (resident in CSA).</li>
<li>C is the number of nonmaster partitions concurrently using the facilities of CRAM.</li>
   
   
<li>30 is the SSACB length.</li>
<li>N is the number of master partitions concurrently using the facilities of CRAM. </li>
</ul>
   
   
<li><var class="term">onln</var> is the SSCB length.</li>
<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>
   
   
<li><var class="term">chnl</var> is the IICB length.</li>
====Partition requirements====
<p>
The entire CRAM subsystem runs in the partition GETVIS area of each partition that uses the facilities of CRAM:</p>
   
   
<li><var class="term">cnct</var> is the UICB length.</li>
<ul>
<li>Each master partition has a copy of the phase IGCLM244 and the master subtask CRAMZWT. </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><br></li>


<li>CRAM SVC
<li>Each nonmaster partition has a copy of the phase IGCLM244 and the nonmaster subtask CRAMSWT. </li>
<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><b>Virtual storage</b>
<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>
<p>
</ul>
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>
<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">Virtual storage requirement = Min(<i>nif</i>,1) * (68 + (<i>nif</i> * (IFAMBS + 100)))
<p class="code">MAX (INMRL,OUTMRL) for IODEV=29
+ Min(<i>nul</i>,1) * (68 + (<i>nul</i> * (Max(INMRL,OUTMRL) + 100)))
IFAMBS              for IODEV=23
+ Min(<i>nfs</i>,1) * (68 + (<i>nfs</i> * (LOUTPB + 100)))
LFSCB              for IODEV=11
</p>
</p>
</blockquote>
====Calculating partition requirements====
<p>
<p>
Where:</p>
Total storage requirements consist of fixed and variable storage. </p>
<p>
Fixed storage requirements are as follows:</p>
   
   
<ul>
<table>
<li>Min is the Minimum function.</li>
<caption>Fixed storage requirements</caption>
<tr class="head">
<th>Fixed storage area</th>
<th>XECB version (bytes)</th>
<th>XPCC version (bytes)</th>
</tr>
   
   
<li>Max is the Maximum function.</li>
<tr>
<td>CRAM phase </td>
<td>2560 </td>
<td>3072</td>
</tr>
   
   
<li><var class="term">nif</var> is the number of <code>IODEV=23</code> users.</li>
<tr>
<td>CRAM master subtask</td>
<td>13264 </td>
<td>22144</td>
</tr>
   
   
<li><var class="term">nul</var> is the number of <code>IODEV=29</code> users.</li>
<tr>
<td>CRAM nonmaster </td>
<td>13264</td>
<td>19840</td>
</tr>
   
   
<li><var class="term">nfs</var> is the number of <code>IODEV=11</code> users.</li>
<tr>
<td>TOTAL</td>
<td>29088</td>
<td>45056</td>
</tr>
</table>
   
   
<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>
Variable storage requirements, represented schematically, follow: </p>
   
   
<li><var>LOUTPB</var> is the length of the output page buffer required for full-screen features. </li>
<table>
</ul></li>
<caption>Variable storage requirements</caption>
</ul>
<tr class="head">
 
<th>Variable storage area</th>
====CRAM buffer allocation====
<th>Bytes</th>
<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>  
</tr>
<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.
<tr>
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>  
<td>Subtask communications area </td>
<p>
<td>A</td>
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>
</tr>
<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>
CRAM buffers are reusable, and they are freed only when <var class="product">Model&nbsp;204</var> terminates.</p>
 
===Using CRAM on a z/VSE operating system===
<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>
<tr>
<tr class="head">
<td>Master channel storage</td>
<th><p>Version... </p></th>
<td>B</td>
<th><p>Is compatible with...</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>Cross-Partition Event Control Blocks (XECB) </p></td>
<td>User (nonmaster) channel storage </td>
<td><p>Single-address-space mode of z/VSE, only.</p></td>
<td>C</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>A + B + C</td>
</tr>
</tr>
</table>
</table>
   
   
====Sizing the subtask communications area====
<p>
<p>
System requirements for the XECB and XPCC versions are explained in the following sections.</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>
   
   
====Performance====
<ul>
<li>In the XECB version:
<p>
<p>
To maximize performance of the CRAM subsystem: </p>
The size of each communications area (A) is:</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>
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)====
<p class="code">A = <i>n</i> * 128
<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">number of XECBs = 5 * (C + N)
</p>
</p>
Where:
<p>Where:</p>
   
   
<ul>
<ul>
<li>C is the number of nonmaster partitions concurrently using the facilities of CRAM.</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>N is the number of master partitions concurrently using the facilities of CRAM. </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>
</ul>
</ul>
   
   
<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>
For example, if <var class="term">nparts</var> in the z/VSE system is 8, the computation is:</p>
   
   
====Partition requirements====
<p class="code">n = (652 + (112 * (8 -1)))/128, rounded up to next integer
n = (11.2) = 12
A = 12 * 128 = 1536 = Subtask Communication Area
</p></li>
<li>In the XPCC 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>
   
   
<ul>
<p class="code">A = m * 768
<li> Each master partition has a copy of the phase IGCLM244 and the master subtask CRAMZWT. </li>
</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>
<li> Each nonmaster partition has a copy of the phase IGCLM244 and the nonmaster subtask CRAMSWT. </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>
   
   
<blockquote class="note">
<table>
<p><b>Note:</b> The storage requirements given do not include buffer storage (one I/O buffer per thread). Buffer sizes are:</p>
<tr class="head">
<th>If the program is...</th>
<th>Value of m is...</th>
</tr>
   
   
<p class="code">MAX (INMRL,OUTMRL)  for IODEV=29
<tr>
IFAMBS              for IODEV=23
<td>CRAM master or a CRAM nonmaster</td>
LFSCB              for IODEV=11
<td>1</td>
</p>
</tr>
</blockquote>
====Calculating partition requirements====
<p>
Total storage requirements consist of fixed and variable storage. </p>
<p>
Fixed storage requirements are as follows:</p>
<table>
<caption>Fixed storage requirements</caption>
<tr class="head">
<th><p>Fixed storage area</p></th>
<th><p>XECB version (bytes)</p></th>
<th><p>XPCC version (bytes)</p></th>
</tr>
<tr>
<td><p>CRAM phase </p></td>
<td><p>2560 </p></td>
<td><p>3072</p></td>
</tr>
<tr>
<td><p>CRAM master subtask</p></td>
<td><p>13264 </p></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>
<tr>
<td><p>TOTAL</p></td>
<td>Both a CRAM master and a CRAM nonmaster</td>
<td><p>29088</p></td>
<td>2</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>
<p>
The sum of the values of I (640 bytes) calculated for each channel is the total channel storage requirement.</p></li>
   
   
<tr>
<li>In the XPCC version:
<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>
For each channel opened in the master environment, the storage requirement is:</p>
   
   
<ul>
<p class="code">B = (p + t + 1) * 128 bytes
<li>In the XECB version:
<p>
The size of each communications area (A) is:</p>
<p class="code">A = <i>n</i> * 128
</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>
<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>
<li>XECB version: <p class="code">SET COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p>
</li>
 
<li>XPCC version: <p class="code">SET NAME=<i>channel</i>,COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p> </li>
</ul>
Where:
   
   
<table>
<table>
<tr class="head">
<tr>
<th><p>If the program is...</p></th>
<th>channel</th>
<th><p>Value of m is...</p></th>
<td>One of the active ONLINE system channel names for which a SNAP dump is requested.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>CRAM master or a CRAM nonmaster</p></td>
<th>nnn</th>
<td><p>1</p></td>
<td>Number of dumps requested. The default is 1 dump.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>Both a CRAM master and a CRAM nonmaster</p></td>
<th>iii </th>
<td><p>2</p></td>
<td>Time interval between dumps (in seconds). The default is 5 seconds. </td>
</tr>
</tr>
</table>
</table>
</li>
</ul>
   
   
====Sizing channel storage====
<ul>
<li>In the XECB version:
<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 for z/VSE====
====Multiple Online copies on a single system====
<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>
<p>
The following JCL statements are required to execute the SNAPCRAM utility:</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>
<ul>
<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:
<li><var>INCCC</var> can be set to 0 or any setting up to <code>32K-4</code>.</li>
   
   
<ul>
<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>
<li>XECB version: <p class="code">SET COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p>
</li>
<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>
<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>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>
</ul>
 
====CICS Interface====
For information about CICS and IODEV 23 threads, see [[HLI:  Job requirements#IFAM2 jobs: Running under CICS|IFAM2 jobs: Running under CICS]].


<li>XPCC version: <p class="code">SET NAME=<i>channel</i>,COUNT=<i>nnn</i>,INTERVAL=<i>iii</i> </p> </li>
==SQL server threads (IODEV=19)==
</ul>
<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>
Where:
   
   
<table>
<table>
<tr>
<tr class="head">
<th>channel</th>
<th><p>IODEV </p></th>
<td>One of the active ONLINE system channel names for which a SNAP dump is requested.</td>
<th><p>Defines thread for...</p></th>
<th><p>You must define this thread for... </p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<th>nnn</th>
<td><p>19 </p></td>
<td>Number of dumps requested. The default is 1 dump.</td>
<td><p><var class="product">Model&nbsp;204</var> SQL Horizon</p></td>
</tr>
<td><p>All Connect<span class="superstar">&#9733;</span> configurations. </p></td>
<tr>
<th>iii </th>
<td>Time interval between dumps (in seconds). The default is 5 seconds. </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>
[[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.
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>
<p>
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>
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>  
 
<p>
<li> Support for [[HLI: IFAM2 CICS processing|IFAM2 and CICS]] is provided. Host language applications can run in 31-bit addressing mode.
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>
</li>
</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>
 
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>
<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>
<p>
</ul>
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>
   
   
====Multiple Online copies on a single system====
===Example for z/VM===
<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. </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>
The following table shows the default channel name and how to define an alternate channel name:</p>
   
   
<table>
<p class="code">... LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760,
<caption>Default and alternate channel names</caption>
LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300,
<tr class="head">
MINBUF=18,MAXBUF=200,NSUBTKS=15,...
<th><p>IODEV</p></th>
SERVSIZE=700000,...
<th><p>Access method</p></th>
    .
<th><p>Default channel name</p></th>
    .
<th><p>To define an alternate channel name...</p> </th>
    .
</tr>
IODEV=49,POLLNO=1,NOTHREAD=4
IODEV=49,POLLNO=2
<tr>
IODEV=49,POLLNO=3
<td><p>11 </p></td>
IODEV=49,POLLNO=4
<td><p>Full-screen</p></td>
IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, -
<td><p>M204FULL</p>
LIBUFF=6048,SQLIQBSZ=32752
</td>
IODEV=19,POLLNO=2
<td><p>Specify a <var>CRFSCHNL</var> parameter value on the User 0 parameter line.</p></td>
IODEV=19,POLLNO=3
</tr>
IODEV=19,POLLNO=4
<b></b>* above IODEV=49 is for RCL connections
<tr>
<b></b>* above IODEV=19 is for SQL CONNECT* connections
<td><p>23</p></td>
<b></b>*-------------------------------------------------------*  /
<td><p>IFSTRT protocol IFAM2 threads</p></td>
<b></b>*  DEFINE CONNECT * SQL AND RCL LINK ETC...             *  /
<td><p>IFAMPROD </p>
<b></b>*-------------------------------------------------------* /
<p>&nbsp;</p></td>
<b></b>**********************************************
<td><p>Specify an <var>IFAMCHNL</var> parameter value on the User 0 parameter line.</p>
DEFINE LINK TCPSQL WITH SCOPE=SYSTEM TRANSPORT=TCPSE -
<p>
  PROTOCOL=IP LOCALID=ANY INBUFSIZE=4096 CONNECTIONS=8 -
To access the Online, call <var>[[IFSTRTN (IFAM2) (HLI function)|IFSTRTN]]</var> and specify the alternate channel name. <var>[[IFSTRT (IFAM2/IFAM4) (HLI function)|IFSTRT]]</var> accesses only the default channel.</p> </td></tr>
  SERVPORT=2132
   
DEFINE PROCESSGROUP ANY192  WITH SCOPE=SYSTEM LINK=TCPSQL -
<tr>
  INLIMIT=8 OUTLIMIT=8 REMOTEID=192.0.0.0  LOGIN=NOTRUST  -
<td><p>29</p></td>
  GUESTUSER=REJECT  MASK=255.0.0.0
<td>
DEFINE PROCESSGROUP ANY204  WITH SCOPE=SYSTEM LINK=TCPSQL  -
<p>
  INLIMIT=8 OUTLIMIT=8 REMOTEID=204.0.0.0  LOGIN=NOTRUST  -
IFDIAL protocol IFAM2, line-at-a-time</p></td>
  GUESTUSER=REJECT  MASK=255.0.0.0
<td><p>M204PROD</p></td>
DEFINE PROCESS CCARSQL WITH SCOPE = SYSTEM -
<td><p>
DATALEN = 32763 FROM = (ANY192, ANY204)
<var>Specify a CRIOCHNL</var> parameter value on the User 0 parameter line. </p>
<b></b>********************************************************
<p>To access the Online, call
</p>
<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>


====CICS Interface====
==Horizon (IODEV=27)==
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>
<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>
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">
<p>
<th><p>IODEV </p></th>
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><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>
</table>
<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>
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===
<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>
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>
===Coding the IODEV=19 line===
<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>
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>  
<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>
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>
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>
====SQLBUFSZ====
<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>
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>
 
==IUCV (IODEV=39, 41, 43)==
<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>
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>
<p>
<p>
The recommended initial value for this parameter is 100000. Specify it on the first IODEV=19 line. </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>
====INMRL====
<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>
For example, the following statement connects a user to a <var class="product">Model&nbsp;204</var> service machine:</p>
<p>
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>
   
   
<p class="code">INVALID STRING ARGUMENT
<p class="code">M204 USER <i>machineid</i> CHAN M204VMFS
</p>
</p>
<p>
Where:
Increase <var>INMRL</var> by 50% and rerun your request.</p>
   
   
====NSUBTKS====
<ul>
<p>
<li><var class="term">machineid</var> is the name of the service machine and must be specified.</li>
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>
<li> M204VMFS is the channel name. </li>
</ul>
   
   
====SQLIQBSZ====
<p>
<p>
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>
[[#M204 command (CMS)|M204 command (CMS)]] describes the M204 command in detail.</p>
 
===Parameters for IUCV channel names===
<p>
<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>
The following table lists the parameters used to specify channel names:  </p>
<table>
<tr class="head">
<th><p>IODEV setting</p></th>
<th><p> Parameter</p></th>
<th><p>Default name</p></th>
<th><p>You can name an alternate channel on the...</p></th>
</tr>
   
   
===Example for z/VM===
<tr>
<p>
<td><p>39</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>VMIOCHNL</p></td>
<td><p>M204VMIO</p></td>
<td><p>VMIOCHNL parameter.</p></td>
</tr>
   
   
<p class="code">... LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760,
<tr>
LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300,
<td>
MINBUF=18,MAXBUF=200,NSUBTKS=15,...
<p>
SERVSIZE=700000,...
41 </p>
    .
</td>
    .
<td>
    .
<p>
IODEV=49,POLLNO=1,NOTHREAD=4
VMFSCHNL</p>
IODEV=49,POLLNO=2
  </td>
IODEV=49,POLLNO=3
<td>
IODEV=49,POLLNO=4
<p>
IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, -
M204VMFS</p>
LIBUFF=6048,SQLIQBSZ=32752
</td>
IODEV=19,POLLNO=2
<td>
IODEV=19,POLLNO=3
<p>
IODEV=19,POLLNO=4
VMFSCHNL parameter. Used in partner process communication and in communication with 3270 and 3270-compatible local and remote terminals.</p>
<b></b>* above IODEV=49 is for RCL connections
  </td>
<b></b>* above IODEV=19 is for SQL CONNECT* connections
</tr>
<b></b>*-------------------------------------------------------* /
   
<b></b>*  DEFINE CONNECT * SQL AND RCL LINK ETC...            *  /
<tr>
<b></b>*-------------------------------------------------------*  /
<td>
<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>
<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.
43</p>
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.
</td>
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>
<td>
<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>  
VMIFCHNL</p>
  </td>
<td>
<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>
M204VMIF</p>
</td>
<td>
<p>
VMIFCHNL parameter.</p>
</td>
</tr>
</table>
   
   
===Managing IODEV=27 threads===
===Programs required for the IUCV CMS Interface===
<p>
<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>
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>
<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>
<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>
<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>
 
==IUCV (IODEV=39, 41, 43)==
<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>
<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="code">M204 USER <i>machineid</i> CHAN M204VMFS
<table>
</p>
<caption>CMS files required for the IUCV Interface</caption>
Where:
<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>
<p>
The following table lists the parameters used to specify channel names:  </p>
<table>
<caption>Parameters for IUCV channel names</caption>
<tr class="head">
<tr class="head">
<th><p>IODEV setting</p></th>
<th><p>File name</p></th>
<th><p> Parameter</p></th>
<th><p>File type</p></th>
<th><p>Default name</p></th>
<th><p>Function  </p></th>
<th><p>You can name an alternate channel on the...</p></th>
</tr>
</tr>
   
   
<tr>
<tr>
<td><p>39</p></td>
<td><p>M204</p></td>
<td><p>VMIOCHNL</p></td>
<td><p>EXEC </p></td>
<td><p>M204VMIO</p></td>
<td><p>Initiates communication between the user and <var class="product">Model&nbsp;204</var></p></td>
<td><p>VMIOCHNL parameter.</p></td>
</tr>
</tr>
   
   
<tr>
<tr>
<td>
<td><p>M204</p></td>
<p>
<td><p>HELPCMS </p></td>
41 </p>
<td><p>Provides HELP information for M204 command syntax</p></td>
</td>
</tr>
<td>
   
<p>
<tr>
VMFSCHNL</p>
<td><p>M204IFAM</p></td>
  </td>
<td><p>EXEC </p></td>
<td>
<td><p>Aids in establishing an HLI connection to <var class="product">Model&nbsp;204</var> </p></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>
   
   
<tr>
<tr>
<td>
<td><p>M204IFAM</p></td>
<p>
<td><p>TXTLIB </p></td>
43</p>
<td><p>Specifies the library of object modules that must be included in IFAM2 programs under CMS</p></td>
</td>
<td>
<p>
VMIFCHNL</p>
</td>
<td>
<p>
M204VMIF</p>
</td>
<td>
<p>
VMIFCHNL parameter.</p>
</td>
</tr>
</tr>
</table>
   
   
===Programs required for the IUCV CMS Interface===
<tr>
<p>
<td><p>M204INFO</p></td>
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>
<td><p>MODULE </p></td>
<td><p>Provides information about the CMS environment</p></td>
<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>
   
   
<tr>
<tr>
<td><p>M204</p></td>
<td><p>M204USR</p></td>
<td><p>EXEC </p></td>
<td><p>LOADLIB </p></td>
<td><p>Initiates communication between the user and <var class="product">Model&nbsp;204</var></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>
   
   
<tr>
<tr>
<td><p>M204</p></td>
<td><p>M204USR</p></td>
<td><p>HELPCMS </p></td>
<td><p>MODULE </p></td>
<td><p>Provides HELP information for M204 command syntax</p></td>
<td><p>Provides interactive access to <var class="product">Model&nbsp;204</var> and parses the command string</p></td>
</tr>
</tr>
</table>
===Interactive access (M204USR MODULE)===
<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>
   
   
<tr>
<ol>
<td><p>M204IFAM</p></td>
<li> Parses a command string that defines the parameters of a communication interface between CMS and <var class="product">Model&nbsp;204</var>.</li>
<td><p>EXEC </p></td>
<li> Uses these parameters to establish the connection between the user's virtual machine and <var class="product">Model&nbsp;204</var>.</li>
<td><p>Aids in establishing an HLI connection to <var class="product">Model&nbsp;204</var> </p></td>
<li> Accepts data for display and reads input from the terminal for transmission to <var class="product">Model&nbsp;204</var> through IUCV. </li>
</tr>
</ol>
   
   
<tr>
<p>
<td><p>M204IFAM</p></td>
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.
<td><p>TXTLIB </p></td>
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>
<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>
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>
<td><p>MODULE </p></td>
<td><p>Provides information about the CMS environment</p></td>
</tr>
<tr>
<td><p>M204USR</p></td>
<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)===
===Line-at-a-time (IODEV=39)===
<p>
<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>
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>
<p>
The M204USR MODULE file executes in the CMS user area in the following manner:</p>
   
   
<ol>
<ul>
<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><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> 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>
<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>
</ol>
</ul>
   
   
<p>
<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 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>
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>
<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>
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>
 
===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>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>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><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 can set <var>INCCC</var> to 0 or any setting up to <code>32K-4</code>. </li>
</ul>
</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>
<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>
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>
<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>
When using IFAM2:</p>
   
   
<ul>
<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 use z/VSE macros within IFAM2 programs.</li>
 
 
<li>You can set <var>INCCC</var> to 0 or any setting up to <code>32K-4</code>. </li>
<li> You can compile IFAM2 programs with a z/VSE compiler.</li>
</ul>
 
<li> IFAM2 provides multithread access to <var class="product">Model&nbsp;204</var> files from a host language program.</li>
===IUCV full-screen (IODEV=41)===
 
<p>
<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>
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>
</ul>
<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>
<p>
IUCV is not supported in the VAE mode of z/VSE operating systems.</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,195: Line 2,197:
</ul>
</ul>
   
   
====Bypassing password prompts====
====<b id="cmsNoPasswd"></b>Bypassing password prompts====
<p>
<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>
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>
Line 2,210: 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.