Defining the user environment (CCAIN)

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)

z/OS and z/VSE device type codes and z/VM input/output device type codes list each access method with its associated IODEV setting and required system (User 0) and user parameters. Details on each IODEV setting follow.

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
19	Horizon SQL thread	INMRL NOTHREAD NSUBTKS SQLBUFSZ
23	CRAM, Host Language IFAM2 thread	IFAMCHNL
27	Horizon	NOTERM
29	CRAM, SOUL thread (line-at-a-time) z/OS and z/VSE, supports: CICS TSO	CRIOCHNL NCCC INMRL NOTERM OUTCCC OUTMRL POLLNO
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 IODEV and ALTIODEV 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
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)

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.

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

Trigger example

The following example uses IODEV=3 as a trigger to monitor the DBMS.

//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. (For details, see the 7.4 installation guide for your operating system.) 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

An APPL statement in VTAMLST for each IODEV type (IODEV=7, IODEV=37) is required for direct SNA Communications Server terminal support by Model 204. 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.

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, set the '02' value of 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 via 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
NSUBTSKS	IPADDR
NOTERM

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

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

IODEV=7 terminals under CMS require an additional systemwide 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 Server communications requests using the CMS/SNA Communications Server Interface:

• All SNA Communications Server 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 a SNA Communications Server APPL and an APPL statement is required for Model 204 in the network's VTAMLST files.
• An additional systemwide CCAIN parameter, VTGCSSRV, is required. The CMS/SNA Communications Server Interface, although using the same SNA Communications Server terminal handler software module as in a z/OS environment (VT75), employs further software, which runs under z/VM's Group Control System (GCS). See the Rocket Model 204 Installation Guide for IBM z/VM, version 7.4 for full details about setting up the GCS server for the VTAM Interface.
• Using the CMS/SNA Communications Server Interface for terminal support means that users are logged on to the ONLINE machine through SNA Communications Server services. A virtual machine is not required for each user.

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.

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 CRAM channel names and parameters.)

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

Remote User Language (IODEV=11, 29) and IFSTRT protocol IFAM2 (IODEV=23) threads require the use of CRAM. Terminals are considered remote User Language threads when either CICS or TSO is used. (See CICS terminal interface and TSO terminal interface for information about these interfaces.)

Facilities requiring CRAM

You must install CRAM if you use the products and interfaces in the following table (products are grouped according to IODEV value):

Facilities	IODEV value
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 provides two CRAM options: CRAM SVC and Cross-Memory Data Mover (CRAM-XDM). CRAM-XDM is the default, and CRAM SVC is deprecated as of Model 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

  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 initializes a single cross-memory environment that is shared among all Onlines. You must submit the M204XDM (XDM master) job before any Online jobs. For Onlines that use CRAM-XDM, the XDM master must be running.

  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.

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

  XDM terminates, on request, only if all cross-memory connections have been disconnected. An outstanding operator reply is used to communicate to XDM. In addition to terminate, a MONITOR,ONLINES command lists on the operator console all address spaces that have connections to XDM. All data moves are done using access registers.

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 to use CRAM without 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.

Invoking a CRAM option

The CRAM option that is invoked is determined by the setting of the XMEMOPT parameter in an Online's CCAIN input:

This XMEMOPT setting...	Initializes...
X'80'	CRAM-XDM environment
Any other setting	CRAM SVC environment (if CRAM threads are defined)

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.

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. The address space that uses a system LX is, by definition, not reusable, and the following z/OS warning message is issued if you EOJ the XDM job:

IEF352I ADDRESS SPACE UNAVAILABLE

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

The importance of non-swappability

Although a non-swappable address space is not required, defining the Model 204 address space as non-swappable (described in the next section) 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

Activating CRAM-XDM

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

1. Install CRAM-XDM.
2. 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.

   3. Set the appropriate XMEMOPT parameter option in your Model 204 Online CCAIN stream. 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.

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 MONITOR,ONLINES 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 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 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 does not shut down if XDM Onlines are still active. When the XDM master address space is active, it displays the following reply message on the operator console:

*nn M204XDM.100: jobname AWAITS COMMAND

Where:

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

Usage

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.

Working with CRAM

If you want, multiple subsystem names (separate IGCLM244 modules) can be used to isolate CRAM-XDM from the current production CRAM environment.

Note: CRAM-XDM requires a non-swappable address space, a system LX, and is recommended as non-cancelable.

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.

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 specified on User 0's parameter line. Subsequently, Model 204 applications can issue commands on a particular channel.

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. You can use the parameters supplied as a default by Model 204 (shown in the table below).

The "CRAM channel names and parameters" table shows CRAM channel names, parameters, and the calls that establish each type of connection:

CRAM channel names and parameters

IODEV setting	Parameter	Default name	Call to establish connection	For connection to...
11	CRFSCHNL	M204FULL
23	IFAMCHNL	IFAMPROD	IFAM2 IFSTRT IFAM2 IFSTRTN	IFAMPROD channel Channel named on IFAMCHNL
29	CRIOCHNL	M204PROD	IFAM2 IFDIAL IFAM2 IFDIALN	M204PROD channel Channel named on CRIOCHNL

Required parameter settings for IODEV=29

The following parameter settings are required for IFDIAL protocol IFAM2 line-at-a-time threads (IODEV=29):

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

For general information about these parameters, see User environment control parameters.

Using CRAM on a z/OS operating system

CRAM storage requirements for z/OS

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

The next three sections give the formula for CSA space and explain buffer and ONLINE space allocation.

Calculating CSA space for HLI

• CRAM-XDM

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

  CSA Space = 1510 + 28 + (50 * onln) + (30 * chnl) + (60 * cnct) + (18 * asid) + trace

  Where (the values shown are in hexadecimal):

  • 1450 is the size of the XMEMCSA module (resident in CSA).
  • 28 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).

  Note: Using CRAM-XDM, you need not calculate buffer spaces.

• CRAM SVC

  The following calculation determines the approximate requirements for each active HLI/Model 204 region:

  CSA Space = 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.

z/OS CRAM buffer allocation

For IODEV=29, the size of the CRAM SVC 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.

This parameter...	Determines the maximum length of data that...
INMRL	Can be transferred as input to Model 204.
OUTMRL	Can be transferred as output from Model 204.

If an application program uses the extended communication buffer, you can set INMRL and OUTMRL up to 32K to accommodate it.

CRAM buffers are allocated as users are activated. The minimum CSA usage, without active users, is 68 bytes per channel and 100 bytes per user as defined by the number of IODEV definitions of the same type. When the first user opens a thread, the associated CRAM buffer, sized by IFAMBS, INMRL, OUTMRL, and LOUTPB parameters, is allocated.

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

z/OS ONLINE space allocation

When ONLINE is initialized, the following space is allocated:

CSA Space = Min(nif,1) * (68 + (nif * 100)) + Min(nul,1) * (68 + (nul * 100)) + Min(nfs,1) * (68 + (nfs * 100))

In addition, ONLINE allocates space in the Model 204 address space based on the following formula:

GETMAIN space = Min(nif,1) * 568 + Min(nul,1) * 568 + Min(nfs,1) * 568 + 568 bytes allocated by each user program in its own address space.

Debugging CRAM SVC

The SNAPCRAM utility is used to debug CRAM SVC. Its counterpart for CRAM-XDM is M204XMON. 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.

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 multithread configuration of Model 204 that supports host language calls to the Host Language Interface (HLI) from one or more user programs. The user programs normally run as separate jobs in other regions or partitions and share a single copy of the database management system software. Each user program must have a small interface module linked in its region to enable communication between the user program and the IFAM2 region through a special interregional supervisor call.

The concept of a Host Language Interface thread corresponds to that of an Online user for ONLINE. As with an Online user, each Host Language Interface thread is defined by a user's parameter line in the CCAIN input stream.

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	Defines an alternate channel name with...
11	Full-screen	M204FULL	CRFSCHNL parameter on the User 0 parameter line.
23	IFSTRT protocol IFAM2 threads	IFAMPROD For CICS transactions: M204	IFAMCHNL parameter on the User 0 parameter line. To access the Model 204 version, call IFSTRTN and specify the alternate channel name.
29	IFDIAL protocol IFAM2, line-at-a-time	M204PROD	CRIOCHNL parameter on the User 0 parameter line. To access the Model 204 version, call IFDIALN and specify the alternate channel name.

TSO Interface

For the TSO Interface, specify an alternate channel name when the terminal connection is made to Model 204:

• If TSO is installed as a command processor (CP), invoke Model 204 as follows:

  M204FS [subsystem:]channel-name (for IODEV=11) M204TTY [subsystem:]channel-name (for IODEV=29) M204PROD [subsystem:]channel-name (for IODEV=29) M204FULL [subsystem:]channel-name (for IODEV=11)

  M204FULL is the default.

• If TSO is not installed as a CP, invoke Model 204 as follows:

  [M204FS] CALL 'library-name' [(M204TTY)|(M204FULL)|(M204PROD)] '[subsystem:]channel-name'

  Where:

  Default channel name for...	Uses this terminal connection...
  M204FULL	M204FS
  M204PROD	M204TTY

CICS Interface

With the CICS Interface, invoke Model 204 as follows:

M204 [subsystem:]channel-name (for IODEV=11) L204 [subsystem:]channel-name (for IODEV=29)

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.

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

Parameters for IUCV 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 be issued.
• The user ID on the LOGIN or LOGON command must equal the CMS user ID of the CMS virtual machine on which the login originated.

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

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

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:

• Terminal processing and support.
• If you do SQL processing, see also SQL connectivity.

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.