Defining the user environment (CCAIN)

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. (See Multiple Online copies on a single system.)

• 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

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/VM and z/VSE sites support only the CRAM SVC option.

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 from and before the jobs of Onlines 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.

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

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 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 can use either the CRAM-XDM option or the CRAM SVC option, but not both.

Activating CRAM-XDM

To implement CRAM-XDM after you have installed and tested Model 204, take the following steps:

1. Install 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 //

      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. LKCRAMJ links the IGCLM244 load module and provides it with the subsystem name.

      TIME=NOLIMIT is required to initialize M204XDM.

      Notes:

      • Submit the M204XDM job prior to bringing up any Online. Otherwise, if M204XDM is unavailable and an Online CCAIN specifies an XMEMOPT value that includes the X'80' bit, the Online cannot initialize.
      • You must submit this job every time you IPL z/OS.

4. After setting the appropriate CCAIN parameters, especially IODEV and XMEMOPT, bring up the Online(s) with which you want to test this new CRAM version. For XMEMOPT, make sure you include the X'80' bit.

   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.

   To locate CRAM, 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.

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.

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

The SNAPCRAM utility is the counterpart to M204XMON that is used to debug CRAM SVC under z/OS. There is also a SNAPCRAM for z/VSE.

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/OS operating system

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 same time begin testing the next release with CRAM-XDM. You can do this using the z/OS secondary subsystem names (SSN) facility:

1. In the CRAM-XDM installation job (LKCRAMJ in RKOBJLIB) which creates module IGCLM244, specify as the CRMSSN parameter value a CRAM SSN you select in coordination with your systems programmers.

   You probably want to select an SSN corresponding to the new release, say V770. This value must also be defined by the systems programmers in SYS1.PARMLIB(IEFSSNxx).

2. Bring up the M204XDM job (required for CRAM-XDM). That job will initialize with an SSN value of V770.
3. After the M204XDM job has initialized, bring up the Online.

   The Online will use the same IGCLM244 module as the M204XDM job, and it will also initialize with an SSN value of V770.

   Since the CRAM-XDM modules reside in a separate load library, an Online that requires a CRAM connection (IODEV 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).

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, as described in the following subsection.

Communicating with multiple regions of Model 204

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 "Default and alternate channel names" table in the 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.

CRAM debugging

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

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 //SYSPRINT DD SYSOUT=A //CCAPRINT DD SYSOUT=A /* //

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

Required parameter settings for IODEV=29

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.

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

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.
  • IFAMBS is the IFAM2 block size.

    IFAMBS must be set between 2 to 5 times the value of LIBUFF or LOBUFF. (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.

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 protocol 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 following table shows the default channel name and how to define 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.

CICS Interface

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