Defining the user environment (CCAIN): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎CICS Interface: ad links)
m (remove TSO section; does not apply to IODEV 23)
Line 1,677: Line 1,677:
</tr>
</tr>
</table>
</table>
===TSO Interface===
<p>
For the TSO Interface, specify an alternate channel name when the terminal connection is made to <var class="product">Model&nbsp;204</var>:</p>
<ul>
<li>If TSO is installed as a command processor (CP), invoke <var class="product">Model&nbsp;204</var> as follows:
<p class="syntax">M204FS [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=11)
M204TTY [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=29)
M204PROD [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=29)
M204FULL [<span class="term">subsystem</span>:]<span class="term">channel-name</span> (for IODEV=11)
</p>
<p>
<var>M204FULL</var> is the default.</p></li>
<li>If TSO is not installed as a CP, invoke <var class="product">Model&nbsp;204</var> as follows:
<p class="syntax">[M204FS]
CALL '<span class="term">library-name</span>' [(M204TTY)|(M204FULL)|(M204PROD)] '[<span class="term">subsystem</span>:]<span class="term">channel-name</span>'
</p>
<p>
Where:</p>
<table>
<tr class="head">
<th>
<p>
Default channel name for...</p></th>
<th>
<p>
Uses this terminal connection...</p></th>
</tr>
<tr>
<td>
<p>
M204FULL</p></td>
<td>
<p>
M204FS</p></td>
</tr>
<tr>
<td>
<p>
M204PROD</p></td>
<td>
<p>
M204TTY </p></td>
</tr>
</table></li>
</ul>
   
   
===CICS Interface===
===CICS Interface===

Revision as of 19:54, 3 April 2017

Overview

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

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

Setting user parameters

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

Basic rules

The following rules apply:

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

Access methods and device types

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

Access methods

Model 204 supports the following access methods:

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

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

Device types (IODEV settings)

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

z/OS and z/VSE device type codes
IODEV value Access method/device type Essential parameters
1 CCAIN/CCAPRINT (User 0 only) (none)
3 BSAM INPUT
OUTPUT
7 SNA Communications Server 3270 (full screen) LOUTPB
MODEL
NOTERM
NOUTBUF
NSUBTKS
TERMBUF
TERMOPT
VTAMNAME
11 CRAM thread (full screen), supports:
  • TSO
  • CICS
  • Program Communication facilities
CRFSCHNL
LOUTPB
MODEL
NOTERM
POLLNO
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 ALTIODEV as well as the IODEV parameters:

z/VM input/output device type codes
IODEV value Access method/device type Essential parameters
3 BSAM INPUT
OUTPUT
7 SNA Communications Server 3270 (full screen) LOUTPB
MODEL
NOTERM
NOUTBUF
NSUBTKS
TERMBUF
TERMID
TERMOPT
VTAMNAME
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.

Trigger example

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

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

Input or output data set definitions

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

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

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

z/VSE JCL example

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

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

z/OS JCL examples

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

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

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

z/VM FILEDEF example

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

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

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

FILEDEF I0301I READER

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

CP SPOOL PUN some-user FILEDEF I0301O PUNCH

Buffer allocation

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

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

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

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

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

Dynamic allocation and DFSMS/HSM

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SNA Communications Server network definition requirements

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

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

M204 VBUILD TYPE=APPL M204PROD APPL

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

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

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

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

IP address using TN3270 connection to VTAM session: IPADDR

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

  • VIEW command

    VIEW IPADDR

  • SOUL $View function

    %ipaddr=$view('IPADDR')

CCAIN requirements

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

Systemwide parameters Per-user parameters
LOUTPB IODEV
NOUTBUF MODEL
TERMBUF TERMOPT
VTAMNAME TERMID
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 system parameter, VTGCSSRV (see the next section for details).

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

CMS/SNA Communications Server Interface for full-screen terminals

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

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

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

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

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

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

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

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

Preparing the GCS server component

The GCS server component contains the following elements:

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

Defining the GCS directory entry

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

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

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

Notes:

  • OPTION statement

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

  • LINK statements

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

  • IUCV ALLOW service machine

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

  • VTAM GCS group

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

CRAM (IODEV=11, 23, 29)

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

Facilities requiring CRAM

Remote User Language (IODEV=11, 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 in the next section) 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. 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.

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

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.

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

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.

z/OS 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 operate.

The next two sections give the formula for CSA space and explain buffer and Online module space allocation.

z/OS CRAM 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.

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 CRAM SVC debugging

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

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

For CICS transactions: M204

 

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 threads and IODEV 23, see IFAM2 jobs: Running under CICS and HLI: IFAM2 CICS processing.

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:

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.