Defining the runtime environment (CCAIN)

Overview

CCAIN is the Model 204 control file used to define the runtime and user environments, and to control system operations.

When all the CCAIN input stream is read, Model 204 automatically terminates.

The discussion of the CCAIN file is presented in these pages:

• The page you are reading describes the structure of the CCAIN file and the parameters used to define the runtime environment. Topics directly relating to the runtime parameters such as resource locking, disk buffers, and server areas are included.
• Defining the user environment (CCAIN) discusses setting up the user environment.
• Controlling system operations (CCAIN) discusses the commands used to control system operations.

Special considerations relating to Model 204 configurations or operating systems follow each discussion whenever appropriate.

Structure of CCAIN

The CCAIN file is divided into three sections, as described here:

Runtime environment

The runtime environment specifications line, which is known as the User 0 parameter line, sets system characteristics and default user parameters during Model 204 initialization.

User 0, which acts as the system operator, is the name given to the input stream used by Model 204 initialization routines. The input stream is read from the CCAIN file and echoed on the CCAPRINT file. (For more information on CCAPRINT, see Obtaining User 0 output (CCAPRINT).)

The User 0 parameter line, which is described in this page, includes:

• System table sizes
• I/O buffer sizes
• Scheduler and performance options
• Recovery options

Pre-user 0 commands

Parameters on the User 0 line are specified on the first line of the CCAIN input stream unless certain commands are used. The following commands are the only ones that can precede the User 0 parameter line:

• *LOWER
• *UPPER
• APPDATE
• DEFINE DATASET
• DEFINE STREAM
• MSGCTL
• UNICODE

• * (a comment) is also allowed, however, a blank must follow the *.
• An all-blank line is also allowed.

In addition, starting with version 7.5, you can provide a common configuration for all Model 204 jobs by linking PRECCAIN into your ONLINE, IFAM1, and/or IFAM4 load modules. PRECCAIN, an assembler module which you modify and link into the load modules, contains Model 204 commands and parameters set and executed, respectively, during Model 204 initialization.

User environments and definitions

User environment definitions and specifications are set for each user on a separate line for:

• Device type and terminal communication network
• Compiler table defaults
• Server configuration
• Default output options

System control commands

System control commands are entered on successive lines. System commands include:

• Recovery procedures
• Suspension of User 0
• Message control
• Allocation and freeing of data sets
• Definition of data sets and printers
• End-of-data and end-of-job statements
• SOUL requests
• FLOD programs

ONLINE data streams with CCAIN

The following pages present z/OS, z/VSE, and z/VM examples for ONLINE data streams. The ONLINE examples illustrate the structure of CCAIN, including the runtime environment specifications line (User 0), user environment definitions and specifications, and system control commands.

A z/OS example for a BATCH204 run follows the ONLINE data streams.

Parameter lines

A CCAIN parameter line consists of one or more 80-column card images with parameter keywords and values in columns 1 through 71.

If the line exceeds 71 characters, any non-blank character in column 72 indicates continuation to the next card image.

The maximum length of the parameter area is controlled by the LIBUFF parameter, which is listed in the Common runtime parameters and Fixed server table values tables.

Model 204 accepts comment lines or blank lines after the User 0 parameters in the CCAIN input stream. IODEV lines can have comments and blank lines before, between and after them.

As shown in the following examples, these rules governing parameter lines apply in all operating environments.

z/OS JCL

The following example shows z/OS JCL for an ONLINE data stream containing the CCAIN file.

//M204ONLN JOB CLASS=A,MSGCLASS=A,NOTIFY=LEN //RUN EXEC PGM=ONLINE,REGION=4096K, // TIME=1440,PARM=('SYSOPT=149,LIBUFF=1024,LOBUFF=3000') //STEPLIB DD DSN=M204.RLSE.LOADLIB,DISP=SHR //CCAJRNL DD DSN=M204.JOURNAL,DISP=SHR //CHKPOINT DD DSN=M204.CHKPOINT,DISP=SHR //CCATEMP DD UNIT=3380,SPACE=(TRK,90), // DISP=(NEW,DELETE) //CCASNAP DD SYSOUT=A //SYSMDUMP DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CCAAUDIT DD SYSOUT=A //CCASTAT DD DSN=M204.CCASTAT,DISP=SHR //CCAGRP DD DSN=M204.CCAGRP,DISP=SHR //CLIENTS DD DSN=M204.FILE.CLIENTS,DISP=SHR //VEHICLES DD DSN=M204.FILE.VEHICLES,DISP=SHR //CLAIMS89 DD DSN=M204.FILE.CLAIMS89,DISP=SHR //CLAIMS90 DD DSN=M204.FILE.CLAIMS90,DISP=SHR //CCASERVR DD UNIT=3380,DISP=(NEW,DELETE), // SPACE=(CYL,5,,CONTIG) //CCAPRINT DD SYSOUT=A //CCAIN DD * X Runtime NUSERS=9,NSERVS=2,MINBUF=18,MAXBUF=1000, X environment TERMBUF=5,NFILES=4,NDCBS=4,NDIR=4,SPCORE=50000, X definitions IFAMBS=4000,LRETBL=800,VTAMNAME=M204,CRFSCHNL=M204FULL, X User0 CRIOCHNL=M204PROD,IFAMCHNL=IFAMPROD, X RCVOPT=9,CPMAX=1,CPTIME=30,CPTO=5,CPTQ=5, X LFSCB=7000,LGTBL=500,LSTBL=3000,LVTBL=200, X LOUTPB=3000,NBKPG=5,OUTCCC=80,SERVSIZE=72456 IODEV=7,NOTERM=3,POLLNO=1,SERVSIZE=72456 User environment IODEV=7,POLLNO=2 defining 8 users IODEV=7,POLLNO=3 device types, and IODEV=29,NOTERM=2,POLLNO=1 the communication IODEV=29,POLLNO=2 network IODEV=11,NOTERM=2,POLLNO=1 IODEV=11,POLLNO=2 IODEV=23 HALT 27,MODEL 204 IS UP AND RUNNING,3,EOD EOD *SLEEP 300 BROADCAST URGENT 1***SYSTEM GOES DOWN IN 5 MINUTES *SLEEP 300 HALT 24,WAIT FOR USERS TO LOGOUT,3,EOJ CHECKPOINT System operation BUMP ALL control commands *SLEEP 300 EOJ

z/VSE JCL

The following example shows z/VSE JCL for an ONLINE data stream containing the CCAIN File:

// JOB ONLINE // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT SYSnnn,... // LIBDEF PHASE.SEARCH=(M204LIB.V210,PRD1.BASE) // DLBL CCAJRNL,'MODEL204.CCAJRNL' // EXTENT SYS001,balance of extent information // DLBL CHKPNT,'MODEL204.CHKPOINT' // EXTENT SYS001,balance of extent information // DLBL CCATEMP,'MODEL204.CCATEMP',,DA // EXTENT SYS001 // DLBL CCASRVR,'MODEL204.CCASERVR',,DA // EXTENT SYS001 // DLBL CCASRV0,'MODEL204.CCASERV0',,DA // EXTENT SYS001 // DLBL CCAGRP,'MODEL204.CCAGRP,,DA // EXTENT SYS001 // DLBL CCASYS,'MODEL204.CCASYS',,DA // EXTENT SYS001 // DLBL CCASTAT,'MODEL204.CCASTAT' // EXTENT SYS001,balance of extent information // ASSGN SYS001,X'cuu' // ASSGN SYS002,X'108' ---- Local 3270 terminal // ASSGN SYS003,X'019' ---- Local 3270 terminal // ASSGN SYS008,PRINTER ---- Audit trail *** INSERT LABEL INFORMATION AND ASSIGNMENTS *** FOR USER DATABASE FILES HERE // UPSI 10011011 // OPTION SYSPARM='LIB=512' // EXEC ONLINE,SIZE=AUTO NUSERS=6,MAXBUF=1000,LFSCB=4900, Runtime environment LOUTPB=2400,NDIR=10,NSERVS=2,SERVSIZE=95000, definition (User 0) RCVOPT=9 IODEV=35,INPUT=SYS002,SERVSIZE=95000 User environment IODEV=35,INPUT=SYS003 defining 5 users, IODEV=41,NOTERM=2,POLLNO=1 device types, and the IODEV=11,POLLNO=2 communication network IODEV=23,NOTERM=1,POLLNO=1 *** INSERT USER ZERO REQUESTS HERE HALT 22,MODEL 204 IS AVAILABLE,3,EOJ System operation CHECKPOINT EOJ control commands /* /&

CMS CCAIN file

PAGESIZE=6184,NUSERS=5,NSERVS=2, X NFILES=3,NDCBS=3,MINBUF=18,MAXBUF=1000, X RCVOPT=9,SERVSIZE=95000 IODEV=41,NOTERM=2,POLLNO=1 IODEV=41,POLLNO=2 IODEV=39,NOTERM=1,POLLNO=1 IODEV=43,NOTERM=1,POLLNO=1 HALT 19,MODEL 204 IS NOW UP,10,END OF DAY EOD HALT 24,WAIT FOR USERS TO LOGOUT,3,EOJ CHECKPOINT EOJ

z/VM ONLINE processing

A Model 204 ONLINE environment is created in a z/VM environment by:

• Defining runtime parameters in the User 0 input file.
• Executing the CMS ONLINE command, which causes an EXEC procedure to:
  • Execute a user-created EXEC procedure to define the file recovery environment
  • Invoke Model 204 to perform file recovery
  • Execute a user-created EXEC procedure to define the ONLINE environment
  • Invoke Model 204 to establish the ONLINE environment

Samples of the components necessary to invoke a Model 204 ONLINE environment follow.

EXEC procedure defining the ONLINE environment

&TRACE OFF &C FILEDEF * CLEAR &C LABELDEF * CLEAR &C FILEDEF CCAIN DISK DOCONLN CCAIN A &C FILEDEF CCAPRINT DISK DOCONLN CCAPRINT A &C FILEDEF CCAAUDIT J DSN M204 CCAAUDIT &C FILEDEF CCASNAP PRINTER &C FILEDEF CCAJRNL G DSN M204 CCAJRNL &C FILEDEF CHKPOINT G DSN M204 CHKPNT &C FILEDEF CCATEMP H DSN M204 CCATEMP &C FILEDEF CCASERVR I DSN M204 CCASRVR &C FILEDEF CCAGRP J DSN M204 CCAGRP &C FILEDEF CCASYS J DSN M204 CCASYS &C FILEDEF CCASTAT J DSN M204 CCASTAT &C FILEDEF CARS J DSN M204 CARS &STACK SYSOPT 146 LIBUF 1000

CMS ONLINE command

The ONLINE command brings up Model 204 in the service machine, allowing multiple users to log on.

Syntax

The format of the ONLINE command is:

ONLINE [TEST] [NODCSS] [IFDIAL] [exec1] [BYPASS] [exec2] [BYPASS] [execargs]

Where:

• TEST specifies that a TEST version of the Model 204 ONLINE module or shared segment, such as T204, is to be invoked. The default is the production version M204.
• NODCSS specifies that shared segments are not to be used, even though they exist.
• IFDIAL specifies that a single user IFDIAL connection is to be made (saved segments mandatory). The IFDIAL connection must be made on the main (nonrecovery) step.

  A single-user IFDIAL EXEC procedure, SAMPDIAL, is supplied as part of the distributed material. Customize and install SAMPDIAL on an accessible minidisk. The M204 EXEC expects the IFDIAL EXEC to be named SINGDIAL.

  For more information, refer to the Rocket Model 204 Installation Guide for IBM z/VM, version 7.4.

• exec1 specifies the name of the EXEC procedure that contains the ACCESS commands for the required minidisks and the file definition (FILEDEF or M204FDEF) commands for Model 204 recovery purposes. You must create the EXEC in accordance with the file requirements for the Model 204 ONLINE environment to be recovered.
• BYPASS specifies not to use the EXEC procedure name in the ONLINE command and bypasses the recovery or Online steps, or both.
• exec2 specifies the name of the EXEC procedure that contains the ACCESS commands for the required minidisks and the file definition (FILEDEF or M204FDEF) commands for Model 204 regular online production files. You must create the EXEC in accordance with the file requirements for the Model 204 online environment to be initiated.
• execargs are any user arguments, which are passed directly to the EXECs (1 and 2).

Usage notes

The EXEC can also include the Dictionary and Access/204 file definitions, if they are installed.

The following considerations apply to CMS online command processing:

• If no operands are specified on the ONLINE command, the default name of the restart EXEC procedure is M204REST.
• The default name of the Online EXEC procedure is M204DEF.
• If one operand is specified, it is assumed to be the name of the Online EXEC procedure.
• EXEC procedures invoked by ONLINE provide the necessary Model 204 parameters.
• Required options must be placed in the stack (the &STACK command) as keyword-value pairs, separated by blanks.
• If IFDIAL is specified, the main (nonrecovery) EXEC must provide only one parameter, the user program name, in the stack. The program name must be placed in the CMS stack before returning to the ONLINE EXEC.

  The IFSETUP function (see the Rocket Model 204 Host Language Interface Reference Manual) is used to send the CCAIN parameters via the user program. Neither CCAIN nor CCAPRINT are used for IFDIAL connections.

• A single-user Model 204 interactive Online environment uses an EXEC procedure, SAMPSING, which is supplied as part of the distributed material. An IODEV statement is not required. (See Server areas.)

  Customize and install SAMPSING and its companion, SAMPSING CCAIN, on a generally accessible CMS minidisk. Name the customized files SINGLUSR EXEC and SINGLUSR CCAIN to sustain compatibility with the standard distributed user interfaces.

Return codes are evaluated as follows:

• A return code of zero from any one of the EXEC procedures invokes Model 204.
• A return code of one (1) bypasses the invocation of Model 204.
• Any other return code is considered an error and causes the ONLINE EXEC to terminate immediately.

Example

ONLINE BYPASS DOCONLN

The parameters used in the sample above:

• Use the version of Model 204 with saved segments
• Provide no recovery arguments
• Execute a user-written EXEC (DOCONLN) that defines the ONLINE environment

CMS utilities and EXECs

The "CMS utilities" table explains how to use CMS utility command modules relating to Model 204 in the CMS environment. None of the commands can be issued within the Model 204 environment. For information about syntax, refer to CMS utility command modules.

CMS utilities

Utility	Purpose	Comments
M204APND	Concatenates file definitions.	A DDNAME of CLEAR removes all file definitions.
M204CMS	The interface between CMS and Model 204 that provides system services during execution of load modules, for example M204ONLN, M204IFM1, and M204UTILC.
M204FDEF	Creates file definitions for files on unaccessed variable format disks without accessing the resident disk.	An example defining the file CLI: CP LINK MVS 201 201 MW WRITE M204FDEF CLI 201 DSN M204 CLI
M204LDEF	Specifies magnetic tape label information for tape volumes using the M204APND module.	Standard LABELDEF command parameters and options are used.
M204UTIL	Initializes, labels, allocates, erases, renames, and lists variable-format volumes.	Not recommended for space allocation on DOS or OS format disks owned by a guest operating system, because the catalog is not updated and does not work on indexed VTOCs. You can use IEFBR14 for space allocation and M204FDEF or a FILEDEF for access.
M204XFER	Transfers control to the version of the M204CMS module that executes in a saved segment (DCSS).	M204XFER can also load a second DCSS containing the Model 204 program invoked by M204CMS.

Using the M204UTIL utility

The M204UTIL utility uses RESERVE/RELEASE logic when updating the VTOC of a variable-format disk. You can use it to manipulate a volume being used by one or more Model 204 service virtual machines.

Note: Erasing data sets that are in use by Model 204 on such volumes produces unpredictable results.

The "M204UTIL options" table lists the options that are available with M204UTIL.

M204UTIL options

Allocation unit	Option
BLKSIZE	Block size
DSORG	Either PS or DA
LRECL	Record length
PRIMARY	CYL TRK BLK
RECFM	F/FA/FBA/V/VA/VBA/U

You must specify the primary option. Other options are not mandatory. The operands and options are function-dependent.

For example, the first statement below initializes a temporary minidisk. The second creates a data set named DEV.SCRATCH.CCATEMP to be stored on it. The third statement erases the data set.

M204UTIL INITIAL 291 TMP291 M204UTIL ALLOCATE DEV SCRATCH CCATEMP 291 (PRIMARY 5 CYL) M204UTIL ERASE DEV SCRATCH CCATEMP 291

Using the M204MOUN EXEC to mount and dismount tapes

When a tape must be mounted, the CMS interface to Model 204 invokes the EXEC procedure M204MOUN, passing the DDname, device address, volume serial number, volume sequence, and access type (READ or WRITE) as arguments.

The M204MOUN EXEC determines the status of the tape device, issues appropriate Control Program and CMS commands, and sends a message to the system operator for a tape mount and drive attachment to the service virtual machine, if necessary.

Based on criteria at its disposal, the EXEC can reject the attempt to mount the tape. You can alter the M204MOUN EXEC defaults to meet site requirements.

When a tape volume is dismounted, the CMS interface to Model 204 invokes the EXEC procedure M204UNLD, passing the DDname, device address, volume serial number, volume sequence, access type (READ or WRITE), and file status (EOV or EOF) as arguments.

• EOV (request another volume) indicates an entry at end-of-volume.
• EOF (no further requests) indicates an entry due to end-of-file.

BATCH204 JCL with CCAIN

Sample z/OS JCL for invoking a BATCH204 run

//RUN EXEC PGM=BATCH204,REGION=1200K, // TIME=10,PARM='SYSOPT=144' //STEPLIB DD DSN=M204.LOADLIB,DISP=SHR //CCAAUDIT DD SYSOUT=A //CCASTAT DD DSN=M204.CCASTAT,DISP=SHR //CCAJRNL DD DSN=M204.JOURNAL,DISP=SHR //CCATEMP DD UNIT=3330,SPACE=(TRK,20), // DISP=(NEW,DELETE) //CCASNAP DD SYSOUT=A //SYSMDUMP DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CENSUS DD DSN=M204.FILE.CENSUS,DISP=SHR //CCAPRINT DD SYSOUT=A //CCAIN DD * PAGESZ=6184,NFILES=1,SNAPCTL=2 . . .

STEPLIB points to the load module library where the Model 204 program is linked.

• If the load module library is added to the LINKLIB concatenation, STEPLIB is not necessary.
• If EXCPVR under z/OS is used, STEPLIB must be authorized.

Runtime environment specifications

You can specify Model 204 runtime environment parameters on the EXEC statement and on the User 0 parameter line of the CCAIN input stream.

The following sections explain how to set EXEC parameters, discuss the most commonly used User 0 parameters, and detail procedures specific to z/VSE and z/VM environments.

Specifying EXEC statement parameters

The JCL EXEC statement includes the following parameters that affect the runtime environment (see the sample in z/OS JCL).

• PGM specifies the Model 204 configuration.
• TIME specifies how long Model 204 can run before being canceled by the operating system. Specify at least 10 seconds for system initialization and normal termination.

  Under z/OS, if TIME is set to 1440, the operating system's automatic cancellation of the run is bypassed. If the Model 204 automatic shutdown facility is also bypassed, then Model 204 can run indefinitely until brought down by other means.

• PARM sets various Model 204 parameters, including the LIBUFF parameter and the SYSOPT parameter, which is described in the SYSOPT parameter options table.

  Note: The value set for LIBUFF takes effect immediately, so you must set LIBUFF large enough to accommodate CCAIN.

• REGION specifies the size of the memory area allocated for the Model 204 configuration. The next section explains how to estimate the value of this parameter.

Calculating region size

Consider the following factors when estimating region size for an Online system (z/OS) or z/VM machine size (CMS):

• Size of the load module, which varies depending on the use of optional modules
• Spare core (SPCORE) specification, the default is 8192 bytes

  Increase the default, if you use deferred update, the FLOD exit (FLODXT) feature, directed output, or active subsystems. Additional memory is also required to open sequential data sets. The requirements for FLODXT are given under SPCORE in the "Common runtime parameters" table.

• Number of buffers used for each server

  Four buffers for each server is the minimum requirement. Each buffer requires slightly more than one Model 204 page. The main memory required is dependent upon the SERVSIZE parameter setting.

  No work space is required. Under normal conditions, five active users or application threads can be serviced efficiently by one server.

• Number of servers allocated

  The size of each user's area is dependent on the settings of the compiler table parameters governing the size and complexity of the SOUL requests. The formula to calculate server area size is given in Sizing user server areas.

  In exceptional cases, processing needs might require a distinct server for each user.

• Storage overhead

  Approximately 500 bytes per user and 700 bytes per file are required. The actual amount depends on the number of data sets and extents.

Setting the SYSOPT parameter

SYSOPT values, which can be summed, define actions taken during a run. Individual SYSOPT options are shown in the following table:

SYSOPT parameter options

Option	Specifies...
128	Log for the CCAJRNL and the CCAAUDIT data sets
64	Abend without a dump when the return code is nonzero
32	Print lines relating to system initialization or IFAM function calls (RK lines) on the audit trail or journal
16	Login is required
8	Automatic disconnect operation in response to the LOGOUT command
4	Execution of data definition commands within a particular run only through the File Management facility of Dictionary
2	Existing permanent group file (CCAGRP) is required
1	CCASYS file, which is required for subsystem applications

SYSIPT logical unit in z/VSE

In the z/VSE environment, CCAIN is replaced by the logical unit SYSIPT, a device-independent input reader. Typically, the SYSIPT logical unit is assigned to the same device as that used by the Job Control program for reading JCL. It is usually unnecessary to provide a z/VSE ASSGN statement for this logical unit.

You must place CCAIN data in one of the following:

• Job stream immediately following the z/VSE EXEC Job Control statement:

  // EXEC ONLINE,SIZE=AUTO PAGESZ=6184,RCVOPT=1 . . . . /* /&

  For a full example, see z/VSE JCL.

• A disk data set. Use any utility that takes card input and writes it to a file of 80-byte unblocked records. You must also supply a DLBL and EXTENT for either CCAIN or IJSYSIN:
• For CCAIN, the symbolic unit referenced on the EXTENT statement must be a programmer logical unit, for example, SYS022.
• For IJSYSIN, the symbolic unit referenced on the EXTENT statement must be SYSIPT.
• Procedure with the DATA=YES option on the CATALP statement.

User 0 input file in the z/VM environment

In z/VM, the User 0 output file is specified as a file stored on a minidisk. There are no restrictions on the choice of the CMS file identifier. For example:

FILEDEF CCAIN DISK DOCONLN CCAIN A

Model 204 also runs within a user's virtual machine in a single-user mode. In this case the file is defined with a FILEDEF command, similar to the example shown above, in the single-user EXEC. Runtime parameters are set up the same as for multiple users, except that the number of users is set to one (NUSERS=1).

Stacking z/VM runtime parameters

In a z/VM environment, the EXEC containing the FILEDEF commands can specify SYSOPT (and any other runtime parameters) before initialization by stacking the parameters:

&C FILEDEF CCAIN DISK DOCONLN CCAIN A &C FILEDEF CCAPRINT DISK DOCONLN CCAPRINT A . . . * *STACK THE PARM FIELD VALUE FOR MODEL 204 * &STACK SYSOPT 128 LIBUFF 2048

User 0 parameters

The runtime environment specifications entered on the User 0 parameter line further define system options, user default values, and work area sizes.

Parameters common to many Model 204 configurations are summarized in the "Common runtime parameters" table.

Common runtime parameters

Parameter	Specifies...
CFRLOOK	Collect critical file resources conflict statistics.
CPMAX	Maximum number of checkpoints
CPTIME	Checkpoint time intervals
LENQTBL	Number of entries in each user's resource enqueuing table. (See Resource locking table for sizing formulas.) The default is 6.
LIBUFF	Length of the input buffer used for input lines from CCAIN or the 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 255. If an input line is continued with a nonblank character, the number of characters in the original line and all continuations (not including continuation characters) must fit in the LIBUFF specification.
LOBUFF	Length of the output buffer used for output lines to CCAAUDIT, CCAPRINT, for a user's terminal, or for a directed output (USE) data set. LOBUFF can be reset on individual user parameter lines. The default is 256. The recommended value for SQL processing is 5000.
LOGADD	Number of slots reserved for adding new password (CCASTAT) entries. The default is 0.
LOGFAIL	Action taken when the number of consecutive login failures exceeds the value of the LOGTRY parameter. Default is 0.
LOGONENQ	Use of unique user IDs for systemwide logons to a single ONLINE system. (See the LOGONENQ entry in the "User environment control parameters" table to specify unique user IDs for specific terminals.) The default is 0. The Subsystem Management facility is not affected by LOGONENQ.
LOGTRY	Maximum number of login attempts allowed. The default is 0.
LRETBL	Length of each user's part of the record enqueuing table. (See Resource locking.) Default is 200.
LRUTIM	Disk page reference interval for references considered obsolete. Use LRUTIM to calculate DKRR statistics. The default is 0.
MAXBUF	Maximum number of file page buffers allocated below the bar during Model 204 initialization. (See Disk buffers and Model 204 storage.) The default is 256.
MINBUF	Minimum number of file page buffers allocated below the bar during Model 204 initialization. (See Disk buffers and Model 204 storage.) The default is 18.
NDCBS	Number of Model 204 file DCBs that can be used at any one time. The default is 10.
NDIR	Maximum number of Model 204 files that can be opened during a run. The default is 5.
NFILES	Maximum number of Model 204 files that can be open at any one time. Files remain open until an explicit CLOSE is issued or the session ends. The default is 2. NFILES, NDCBS, and NDIR specifications are automatically incremented during system initialization if SYSOPT=2 (permanent group file). With the VIEW command, you can view parameter values during a run.
NGROUP	Maximum number of file groups each user can have open at the same time. The default is 5.
NSERVS	Number of servers. The default is NUSERS (see below).
NSUBTKS	Maximum number of pseudo subtasks that can be generated in a Model 204 run. The default is 4.
NUMBUFG	Number of file page buffers allocated above the bar during Model 204 initialization. (See Disk buffers and Model 204 storage.) The default is 0.
NUSERS	Total number of SOUL users and IFAM2 or IFAM4 threads supported. The default is 1. The value of NUSERS consists of the total number of I/O device types (IODEVs) specified on the user parameter lines plus 1 for User 0. Online users are defined as terminal users with a particular type of terminal or as a host language thread, if IFAM is supported in the online region.
PAGEFIX	Fixes areas in memory; can be useful in reducing paging traffic under z/OS or z/VSE. The default is X `0000000', which means nothing is page fixed. For z/VSE only: A PAGEFIX request is valid only if real pages have been assigned by the ALLOC command. If ALLOC is 0 or if the total number of pages to be fixed exceeds the number of real pages, the PAGEFIX request fails.
RETRVKEY	PF key used to retrieve a previous terminal input line. 280 bytes of spare core is required for each user that has a defined retrieve key. The default is 0.
SEQOPT	Activation of the prefetch (look-ahead) feature for SOUL applications requiring entry order retrieval. Values are 1 (on) or 0 (off). The default is 0. Activation of SEQOPT requires resizing the MAXBUF parameter by using the formula: MAXBUF = NUSERS * (4 + 2 * [maximum FOR EACH RECORD loop nest level]) You can modify SEQOPT with the RESET command.
SERVSIZE	Size of each server area. The default, formerly 0, is 65536. (See Server areas.)
SPCORE	Minimum amount of storage within the Model 204 address space to leave unallocated at the end of Model 204 initialization. You can set SPCORE in the EXEC statement PARM field or on the User 0 parameter line. The default is 8192. Spare core is used by: IFAM4 application program storage. The default is 12288. Active subsystems. (See the formula given in SPCORE size.) FILELOAD or FLOD commands for tape input and deferred update output. When using the FLODXT feature, you must allocate 100 bytes for each FLODXT program. Each defined retrieval key for previous terminal input (180 bytes per key). In z/OS, a number of bytes of virtual storage equal to your SPCORE setting is reserved above the line, and the same number is reserved below the line. The BTB amount is ignored in Model 204 7.7 and higher if the NUMBUFG parameter setting is greater than 0.
TIMESTOP	Amount of time (CPU milliseconds) before automatic termination processing begins or before initiation of commands or SOUL requests stops. TIMESTOP cannot be reset. The default is 1500. If TIMESTOP is set to 0, the Model 204 timing facility's automatic shutdown is bypassed. If, in addition, the JCL EXEC statement parameter TIME is set to 1440, the z/OS automatic shutdown is bypassed, and Model 204 continues to run indefinitely until brought down by other means.
XMEMOPT	Model 204 Cross-Memory Services facility used by Timer PC and IOS Branch Entry for z/OS systems, as well as using SUSPEND/RESUME instead of WAIT/POST for communication between Model 204 real subtasks. Coordinates with XMEMSVC. It is also required for: IOS Branch Entry UL/DB2 CRAM-XDM CPUID check (product license verification; prior to Model 204 7.5) VIO is incompatible with IOSB and EXCPVR.
XMEMSVC	SVC number of the Model 204 Cross-Memory Services module (M204XSVC). Installation of this module with an SVC is deprecated as of Model 204 7.5. XMEMSVC coordinates with XMEMOPT. The default is 0. M204XSVC is also used by: IOS Branch Entry UL/DB2 CRAM-XDM CPUID check (product license verification; prior to Model 204 7.5)

z/VSE UPSI Job Control statement

In a z/VSE environment:

• Use the SYSPARM parameter of the z/VSE OPTION Job Control statement to specify a limited number of parameters that are normally specified on User 0 or any user's parameter lines, if the maximum length of the data does not exceed eight characters. For example, you can set the LIBUFF parameter with the following statement:

  // OPTION SYSPARM='LIB=2048'

• Set the SYSOPT value before initialization by using the z/VSE UPSI Job Control statement. Specify the value as a series of weighted UPSI bit values.

  For example, including RK lines on the audit trail can be specified with the following statement, which is the equivalent of SYSOPT=32:

  00100000

  The "UPSI/SYSOPT settings" table summarizes the UPSI bit settings and SYSOPT equivalents:

  UPSI/SYSOPT settings

  UPSI setting	SYSOPT value	Meaning
  10000000	128	Generate audit trail and/or journal
  01000000	64	Abend without a dump when the return code is nonzero
  00100000	32	Include RK lines on the audit trail
  00010000	16	Login required
  00001000	8	Automatic disconnect in response to the LOGOUT command
  00000100	4	Restrict the use of data definition commands within a run
  00000010	2	Open CCAGRP for use of permanent file group
  00000001	1	Open CCASYS for use of application subsystem definitions

Resource locking

To maintain data integrity, resource locking requests and reserves system and file resources for share (SHR) and exclusive (EXCL) use with other users. Data corruption is prevented by using linked lists of system and file resources. Conflict in the locking table results from attempts to lock exclusively on a file resource.

Resource locking messages indicate a wait for a file, a conflict for a resource, or that the table is full and needs to be increased with the LENQTBL parameter.

Locking occurs on:

• File resources, which are usually locked in SHR mode, such as:
  • File access
  • Record locking table
  • Table B and Group index
  • Tables C and D
  • Permanent procedures
  • Access Control Table
• System resources, which are usually locked in EXCL mode, such as:
  • Access to the CCASTAT file
  • Group definition table in CCATEMP
  • Updates to CCAGRP
  • Names of a file and subsystem
  • User defined resources
• Records

The following sections explain the resource locking tables and the details of resource locking on single and multiple CPUs.

Record locking table

The record locking table (also called: record enqueuing table), whose length is the product of the number of users (NUSERS) and the length in bytes of one user's part of the table (LRETBL), contains control information necessary to detect conflicts between users trying to update records simultaneously.

You can issue a MONITOR ENQ command to determine current usage in the record locking table.

Calculating allocated size of record locking table

The amount of space required by a request is roughly proportional to the number of lists and FIND statements contained in the request. Each FIND statement or list requires about 46 bytes per file for files less than or equal to 300,000 records. Space requirements increase at the rate of 2.25 bytes per segment. The maximum value is 65,535.

SYSOPT2=X'40'

Record sets — found sets, including FDWOL found sets, sorted sets, lists, and LPU lists — are traced through entries in the record locking table. One entry is required for each segment (49,152 records) in the record set. These entries are CCATEMP page numbers.

When the SYSOPT2 X'40' bit is set, the entries contain 4-byte CCATEMP page numbers. Setting the X'40' bit provides a substantial increase in the number of simultaneous record sets that can be concurrently active in a given Model 204 run. Therefore, if you set the SYSOPT2 X'40' bit, you should also at least double the LRETBL value.

• When the SYSOPT2 setting does not include X'40', then at any given time the bit maps corresponding to all users holding found sets of any kind must fit into CCATEMP pages designated as the small model page pool no matter how large CCATEMP has been allocated.
• When the SYSOPT2 setting does include X'40', the CCATEMP page restriction is removed and user found sets can be placed anywhere within CCATEMP. This includes both the small model page pool and the CCATEMP expansion area, allowing for the possibility of a greater number of concurrent found sets being held by all users.

Resource locking table

You can use the $CenqCt function to obtain information on the number of unused entries in the resource locking table (also called: resource enqueuing table).

Sizing the resource locking table

For details on estimating the size of the resource locking table, see LENQTBL.

For z/OS, Model 204 allocates the resource locking table above the 16-megabyte line.

Multiple jobs running on one CPU

Locking occurs at the file level when application files are shared between multiple jobs.

File locking modes is EXCL when:

• Files are opened from a SOUL thread or an IFAM1 thread that has file update privileges.
• Files are opened from an IFAM2 thread or an IFAM4 thread that has allowed updates with thread update and file update privileges.
• Command is entered to create or delete a permanent group.

File locking is SHR mode when:

• Files are opened under any other circumstances than those listed above.
• Files are opened in deferred update mode. Such files remain in SHR mode for the duration of the run.

  Note: Up to 192 files can be opened in deferred update mode. An attempt to exceed 192 files results in an error message.

• Files have the file recovery option (FRCVOPT) parameter set to include X'10'. Locking on an application file does not occur when it is closed, unless FRCVOPT is set to X'10'. FRCVOPT is discussed extensively in File integrity and recovery.
• The Model 204 job uses the CCAGRP data set.

The following sections explain how locking conflicts are handled by Model 204, and how data integrity is ensured when multiple jobs run on one CPU.

Handling locking conflicts

Locking conflicts for application files are handled first by the operating system and next by Model 204.

The operating system initially examines the disposition for all application files, as specified in the JCL for a job. If two jobs specify SHR for the same application file, the operating system allows both jobs access to the file. When the second job attempts to process the application file, Model 204 determines that another job poses a locking conflict.

Model 204 reads the first page of the file and examines the lock, which is located on that page. If a conflict is detected, Model 204 waits until the job's time limit is reached for the file to become available. Then, if the file is not available, Model 204 sends error messages to the operator's console and to the output device of the user who attempted to open the file.

Error messages are issued once every five minutes until the file becomes available, the job time limit for an online job is reached, or the maximum number of error messages for a batch job (ERMX) is reached.

Messages sent to the operator's console are:

• For an Online job:

  *** M204.0582: ACCESS TO FILE filename PREVENTED BY: jobname *** M204.0584: FILE IS IN USE — filename

• For a batch job the message sent from Model 204 to the operator:

  *** M204.0582: ACCESS TO FILE filename PREVENTED BY: jobname *** M204.0581: ENQ'ING TO SHR FOR FILE filename volname *** M204.0582: ACCESS TO FILE filename PREVENTED BY: jobname *** M204.0583: ENQ'ING TO EXCL FOR FILE filename volname

Data integrity

When multiple jobs run on the same CPU, data integrity is ensured by using:

• Operating system locking and unlocking facility for shared application files and the system file containing file group definitions (CCAGRP).
• Special lock stored in the system file containing user and file security information (CCASTAT).
• Restriction on sharing the system file that provides space for user work tables (CCASERVR) and the system scratch file (CCATEMP) between jobs.

Multiple Model 204 versions running on separate CPUs

The operating system file locking mechanism prevents concurrent updating and retrieval of data sets by jobs that run on separate CPUs. The RESERVE/RELEASE hardware feature restricts use of a device to a single CPU in the following ways:

• Device containing a file's first data set can be reserved when control of the file is gained on one CPU and one of the following conditions is true:
• File is opened in a Model 204 job for the first time.
• File that was read-only is first opened for update.
• Last updating user closes the file.
• File is completely closed.
• Device is released in each case after a single disk read and disk write have been performed.

Each file contains a list of jobs that have control of the file. The list is read and updated only while the device is reserved. If control of the file cannot be obtained, then the list is not updated, and the list of jobs preventing access, with their system IDs, is sent to the operator.

Each list entry contains the following information:

• SMF system ID lock type (SHR or EXCL)
• Job and step names
• Date and time that the list entry was created

How Model 204 resolves locking conflicts

Locking conflicts can be handled automatically or by issuing the ENQCTL command.

Conflicts are handled automatically in single CPU error cases where a Model 204 job has a file open and either the operating system crashes or the Model 204 job is canceled. In these instances, the locking list in the file still shows the file as locked and the following process occurs:

1. When a file is opened, the locking list is processed after the operating system enqueuing. If the operating system enqueuing succeeds, there is no conflicting job on the requesting job's system. Any conflicting list entries for the same system are obsolete.
2. If the locking request is exclusive, any list entries for the current system are eliminated as obsolete.
3. If the request is shared, any exclusive entries for the current system and any shared entry having the same system ID, job, and step names are eliminated.

Locking conflicts between CPUs

You can clear conflicts occurring between CPUs by issuing the ENQCTL command to interrogate or modify the status of a file's locking list. The following rules apply to the ENQCTL command:

• If an ENQCTL command is issued with only a file name, all list entries for the file are displayed.
• If an ENQCTL command is issued with arguments, all the entries satisfying the arguments are deleted.

For example, if a system crash occurs for system S133, the operator at another system can issue the following command to remove all the locking list entries from CENSUS that were added by jobs running on system S133:

ENQCTL CENSUS S133

Indiscriminate use of the ENQCTL command can cause shared DASD integrity exposure through the removal of entries of active systems or jobs.

Shared DASD locking conflicts

If a shared DASD locking conflict occurs, Model 204 sends an error message to the operator's console. Error messages are issued once every five minutes until the conflict is resolved and the file becomes available.

Messages sent to the operator's console are:

• For a batch job:

  *** M204.0582: ACCESS TO FILE filename PREVENTED BY: jobname *** M204.0584: FILE IS IN USE -- filename

  Note: Both of these messages increment the error count for the batch job. Because the batch OPEN command is aborted after the specified maximum number of errors (ERMX) is reached, Model 204 does not wait indefinitely for the conflict to be resolved.

• For active system or job locking list entries deleted by using the ENQCTL command:

  *** M204.0585: SHARED DASD ENQ LIST OVERLAID FOR filename AT hh:mm:ss ON yy.ddd

  The date and time identify the most recent update of the file. Used in conjunction with the operating system job logs, this information can determine the cause of the problem.

z/VSE considerations

The following considerations apply to resource locking in a z/VSE environment:

• File locking is available for z/VSE releases that support LOCK and UNLOCK (SVC 110).
• Multiple copies of Model 204 running in separate z/VSE systems cannot share any Model 204 database files.

Resource locking in z/VM

The following considerations apply to resource locking in z/VM environments:

• CMS-format disks cannot be shared in read/write mode by multiple virtual or real machines. Any attempt at SHR access destroys the data.

  The file allocation techniques that are used and the lack of support in CMS for access serialization prevent effective read/write file sharing.

  Files on CMS-format disks do not require preallocation. The files are created automatically the first time they are referenced and continue to increase in size as more data is added. File size is restricted only by the available space defined on the minidisk.

• Several virtual machines can share variable-format disks by using virtual RESERVE/RELEASE facilities.

  RESERVE/RELEASE permits access to a volume restricted to a particular (real or virtual) access path. Because allocations are static in nature, a file can be read and written without further reference to the allocation information, unless secondary allocation functions are required.

  Files on variable-format disks require preallocation. A primary allocation must be provided. Secondary extents can be specified to permit limited extension of the file. The file allocation information is recorded on a disk in the Volume Table of Contents (VTOC).

  Some files on variable-format disks can be read/write shared by multiple Model 204 virtual machines while others cannot:

  • Files that can be shared are CCAGRP, CCAIN, CCASTAT, CCASYS, and Model 204 files.
  • Files that cannot be shared are CCAAUDIT, CCAJRNL, CCAPRINT, CCARF, CCASERVR, CCASNAP, CCATEMP, CHKPOINT, RESTART, USE data sets, and deferred update data sets.
• SHR mode access on a read-only device can cause data inconsistencies.

  If a CMS user has SHR access to a Model 204 file on a read-only minidisk, SHR does not prevent another user from upgrading to the EXCL mode.

Disk buffers and Model 204 storage

The disk buffer pool holds pages from database files and from CCATEMP and CCAGRP. CCATEMP pages consist of found sets, sorted sets, backpage images, temporary procedures and other data structures. Database pages consist of pages from Tables FCT, A, B, C, D, E and X. Pages are read into and written from this buffer pool by the disk buffer manager which manages this resource using a least recently used algorithm. This pool of buffers is shared by all users.

Model 204 utilizes the following areas of storage, depending on the operating system architecture your site supports:

• Below the line, for 24-bit storage for non-XA systems: z/OS, z/VM, and z/VSE
• Above the line, for sites that support 31-bit storage for OS/390, XA, ESA, z/OS, z/VM, and z/VSE
• Above the bar, for sites that support 64-bit storage for z/OS, z/VM, and z/VSE

The buffer pool consists of the following data structures:

• Disk Buffer Control Blocks: 160 bytes each, one per buffer
• Hash cells: 16 bytes each. The number of hash cells allocated for each buffer is equal to the HASHCELL parameter value, which defaults to 3.
• Page fix lists: 16 bytes per buffer
• Buffers: 6184 bytes, plus 8-byte overrun detection area

  The disk buffer overrun detection area, the space between each buffer in the disk buffer pool, is eight bytes of hexadecimal FF, so for each buffer, 6192 bytes is allocated. The total size of the buffer pool is then:

  (NUMBUF + NUMBUFG) * (6192 + 160 + (16*HASHCELL) + 16)

  NUMBUF is a viewable parameter that is equal to the number of buffers allocated above the line. NUMBUF is equal to or less than MAXBUF, depending on the amount of virtual storage available to the job.

  NUMBUFG is a settable and viewable parameter that is equal to the number of buffers allocated above the bar (ATB). If NUMBUFG buffers cannot be allocated in available above the bar storage, the run terminates.

  Note: As of version 7.7 of Model 204, either NUMBUF or NUMBUFG is 0: all disk buffer storage is allocated BTB, or all is allocated ATB, depending on the setting of NUMBUFG.

Using 31-bit storage

When BTB buffers are being used (that is, NUMBUFG is 0 under version 7.7 or higher, or NUMBUFG is any value under Model 204 prior to 7.7) in systems that support 31-bit addressing, Model 204 disk buffers are allocated above the 16-megabyte line. This frees virtual storage for other data that must remain below the line, and it allows for the allocation of a larger buffer pool, since there is more virtual storage above the line. As the number of buffers increases, database pages can remain in memory for longer periods of time, and repeated reads (I/O) for the same pages are reduced.

• If IOS Branch Entry (XMEMOPT X'02') is used, control blocks, hash cells, and page fix lists are allocated above the line.
• If IOS Branch Entry is not used, the disk buffer control blocks and hash cells (and page fix lists if EXCPVR is used) are allocated below the line. The buffers themselves are allocated above the line.

Note: For information about controlling the allocation of hash cells per buffer pool page, see the HASHCELL parameter.

A minimum number of BTB buffers is required to bring up an Online configuration:

• Model 204 7.6 or lower:

  The minimum number of buffers is equal to the result of the following calculation:

  NLRUQ * ((NSERVS + NSUBTKS) * MAXOBUF + 15)

  If MINBUF is set smaller than the above result, Model 204 resets MINBUF to the result value.

  If MAXBUF is smaller than MINBUF after the previous calculation, MAXBUF is reset to the value of MINBUF.

  Rocket Software recommends that you start with a minimum setting of MAXBUF=10000 and monitor performance statistics to determine if that number is adequate. Generally, performance will improve as the size of the buffer pool increases. That will not be the case, however, if real storage is limited and system paging increases. Many sites are running with MAXBUF=50000, 100000, or more.

• Model 204 7.7 and higher:

  If NUMBUFG is 0, only BTB buffers are used, and the minimum number of buffers calculation and the effects on MINBUF and MAXBUF are as described in the preceding item.

  If NUMBUFG is greater than 0, only ATB buffers are used, and the minimum number of ATB buffers is described in Managing ATB storage with NUMBUFG.

Using 64-bit addressing and Above the Bar (ATB) storage

In systems that support 64-bit virtual storage, you can place Table B and Table X pages (and other entities listed in Model 204 entities in above the bar storage) in the above-the-bar buffer pool, or above the two gigabyte (2GB) address line. Pages that are not stored above the bar reside in the buffer pool above the line.

Important:

• For Model 204 version 7.4, you should ensure that your user-written and third-party $functions can work with non-swappable server tables in 64-bit storage above the bar.
• For Model 204 version 7.5 and higher, any assembler language functions that you have written for use within Model 204 version 7.5 must be 64-bit compliant. Contact Technical Support if you need help with conversion of your functions.
• For Model 204 version 7.7 and higher, activating usage of ATB buffers (setting NUMBUFG greater than 0) causes all buffer storage to be ATB and none to be BTB.

  Prior to the gradual introduction of ATB storage for Model 204, storage was rather limited, so Model 204 took all the storage it could, returned SPCORE bytes, and allocated the rest into the buffer pool. If the resulting number of buffers was not between MINBUF and MAXBUF, the run terminated. On more contemporary systems, virtual storage is abundant, making obsolete the concept of calculating the amount of storage (BTB) that will fit.

  The following documentation retains many remarks that apply to versions preceding 7.7 where ATB and BTB buffers might both be used together.

• In most cases, Table B pages constitute the biggest portion of all pages in the buffer pool. Moving Table B pages to an above-the-bar buffer pool lets Model 204 place more pages from all other tables in the below-the-bar buffer pool and thereby reduce I/O and CPU time to read and write pages to and from disk.
• When a buffer is allocated above the bar, the corresponding disk buffer control blocks (one per buffer, 160 bytes each) and hash cells (three per buffer, 16 bytes each) are also allocated above the bar. This means there is no below the bar storage penalty for allocating above-the-bar buffers.
• Having these two buffer pools rather than one improves Model 204 scalability by reducing MP collisions when using buffer pool resources.
• Eight bytes added to the end of every buffer, above and below the bar, detect buffer overruns. The buffer size per page is 6192 bytes (or 6184 plus 8).

Managing ATB storage with NUMBUFG

Note: If you set NUMBUFG greater than zero to use storage above the bar, IBM requires that you set a limit on how much of that virtual storage each address space can use. This limit is called MEMLIMIT.

When NUMBUFG is set to a nonzero value, an above-the-bar buffer pool is allocated with NUMBUFG buffers. As of Model 204 7.7, this ATB buffer pool handles all disk buffer storage, and you get the exact amount of storage you specify with NUMBUFG. Before version 7.7 of Model 204, nonzero NUMBUFG activates an ATB buffer pool in addition to the BTB buffer pool.

If ATB and BTB buffer pools are both being used:

• The ATB and the BTB buffer pool are allocated with at least a minimum number of buffers, and the calculations for those minimums are very similar:

  The ATB minimum, calculated by Model 204, is:

  NLRUQG * ((NSERVS + NSUBTKS) * MAXOBUF + 15)

  If you set NUMBUFG to a lower value, it is reset to the calculated value.

  The BTB minimum is:

  NLRUQ * ((NSERVS + NSUBTKS) * MAXOBUF + 15)

  If you set MINBUF to a lower value, it is reset to the calculated value.

• Table B and Table X pages (and other entities listed in Model 204 entities in above the bar storage) use the above-the-bar buffer pool. Those pages are not read into the below-the-bar buffer pool. Consequently, most sites can reduce the size of the below-the-bar buffer pool by the highwater mark of Table B pages currently resident in that buffer pool.
• To quickly implement the above-the-bar feature, initially set NUMBUFG equal to your MAXBUF setting and leave MAXBUF at its current setting.
• If NUMBUFG is greater than zero, the buffer hash pool is allocated above the bar. In addition, control blocks associated with ATB buffers are also allocated above the bar. NUMBUFG is limited to buffer pools of 4.2 terabytes or fewer.
• To use the above-the-bar buffer pool in z/OS, IOS Branch Entry is required. This means XMEMOPT must be set to include X'02'. You can explicitly exclude allocating above-the-bar buffers by setting NUMBUFG=0.

  If NUMBUFG is greater than zero and XMEMOPT does not include X'02', the following message is issued, NUMBUFG is not reset, and the job terminates.

  M204.2581: XMEMOPT=2 (IOS BRANCH) REQUIRED FOR NUMBUFG > 0

  If you cannot get the number of buffers you requested, the job fails.

Determining the NUMBUFG setting

The number of buffers you want to allocate above the bar and below the bar is dependent on the mix of work that is being done on your system. See Model 204 entities in above the bar storage for a list of entities that can go above the bar.

• The LDKBMWNG parameter, which applies to above-the-bar buffers, corresponds to the LDKBMWND parameter, which applies to below-the-bar buffers.
• If NLRUQG is set greater than 1, the value of LDKBMWNG is rounded up to a multiple of NLRUQ. LDKBMWND has a minimum size of one (1).

High values of LDKBMWNG might unnecessarily increase the number of writes done (measured by the DKWR statistic). Low values might cause excessive waiting for buffers (measured by the MAXIOX statistic). Rocket Software recommends starting values for LDKBMWND and LDKBMWNG at 10% of NUMBUF and NUMBUFG, respectively.

If you do not set LDKBMWNG, it is set to the same value as LDKBMWND.

Designating non-swappable and swappable server space

You can allocate designated server tables for each user in storage above the bar that will not be subject to server swapping. This feature enables you to divide the server storage into two parts: swappable and non-swappable. This makes the swappable part of the server storage smaller and faster to swap.

The SERVNSSZ and SERVNSA parameters control non-swappable server areas.

• SERVNSSZ (server non-swappable size) is the amount of space in bytes required for the above the bar server tables per user.
• SERVNSA (server non-swappable areas) specifies the tables above the bar.

In order to store a table in ATB storage:

• Increase the SERVNSSZ parameter by the corresponding table size.
• Set the proper bit in SERVNSA; for example:
  • For FTBL, set the first byte to X'02', so the value of SERVNSA is X'02000000'.
  • For GTBL, set the second byte to X'80', so the value of SERVNSA is X'00800000'.
  • For NTBL, set the third byte to X'40', so the value of SERVNSA is X'00004000'.
  • For QTBL, set the third byte to X'20', so the value of SERVNSA is X'00002000'.

Note: The settings for each server table above the bar are independent of each other. So if FTBL, GTBL, NTBL, and QTBL are all placed above the bar, SERVNSA should be set to X'02806000'.

The non-swappable server part can be used with server swapping done in storage or on disk. It can also be used when there is no server swapping (NUSERS=NSERVS) to make servers below the bar smaller by using the non-swappable server part above the bar and saving storage below the bar.

To obtain below-the-bar storage savings when the non-swappable server part is used, decrease the value of the SERVSIZE parameter by the LFTBL value used in calculating the server size.

Note: When a table such as FTBL is placed in the non-swappable server part above the bar, the UTABLE command decreasing the table size will not free any storage in the regular server below the bar.

When using non-swappable ATB server space, each user will get SERVNSSZ bytes of ATB space, even if the thread is logged out or running resident requests.

For greater efficiency, Model 204 version 7.5 also provides swappable ATB server areas that can supplement or replace the non-swappable areas.

The SERVGA and SERVGSZ parameters control swappable server areas.

• SERVGA (server swappable areas) specifies the tables above the bar. Each server table is controlled by a bit in SERVGA.
• SERVGSZ (server non-swappable size) is the amount of space in bytes required for the swappable above-the-bar server tables per server. The total amount of storage allocated for swappable above-the-bar server areas equals SERVGSZ rounded to 4K and multiplied by NSERVS.

Note: In Model 204 V7.5 and higher, server tables can be in three different places:

• The BTB swappable server area
• The ATB swappable server area
• The ATB non-swappable server area

But server tables cannot be in two places at the same time. For example, you cannot make servers swappable and non-swappable at the same time. If, for instance, you set the NTBL bit on for the SERVNSA parameter, and you also set it on for SERVGA, the result would be:

M204.1399: Same server area defined for server above the bar and non-swappable server

However, you can make parts of your server swappable and other parts non-swappable: the non-swappable areas are like having NUSERS=NSERVS, but only for some tables. So if you had large STBLs and GTBLs, you might want to make them non-swappable to reduce server swap times. And if you had small TTBLs and ITBLs, you might want to put them in the swappable area. Any table in the above-the-bar SRVR (the swappable part of the server) is not taking up space in the below-the-bar server. The same is true for any table in the ATB-non-swappable part of the server.

The goal is to reduce the requirement for below-the-bar server area so that you can increase NSERVS (as NSERVS increases, so does the need for below-the-bar virtual storage).

ATB storage for APSY precompiled procedures

The RESPAGE parameter activates the APSY precompiled procedures in storage feature using above-the-bar pages by specifying a number of 4K-byte operating system pages.

Specifying RESPAGE stores precompiled procedures as resident requests above the bar in the RESPAGE area. Using RESPAGE allows you to substantially increase the resident request area and decrease server swapping of QTBL and NTBL pages.

Also, when RESPAGE is greater than 0, RESSIZE is reset to -1, and no storage is allocated for RESSIZE.

RESPAGE is independent of SERVNSA. That is, if RESPAGE is greater than 0, NTBL and QTBL for resident requests will always be stored in the resident request area, outside of the non-swappable server areas, even if the SERVNSA bits specify NTBL or QTBL are to be stored in the non-swappable server areas. This avoids the duplication of storing NTBL and QTBL in two different locations. In other words, a resident request is only stored in the resident request area and nowhere else.

Storing resident requests above the bar is independent of tables above the bar. You can use a combination of resident requests and swappable servers ATB to reduce BTB-server sizes and thus increase the number of servers.

ATB storage for EBM pages

Existence Bit Map (EBM) pages reside in above the bar storage.

Each Model 204 file contains one EBM page for each segment in a file. If a file has five segments, that means there are five EBM pages for that file.

To allow more ATB buffers for the EBM pages, increase the NUMBUFG setting by a value that accommodates all the EBM pages for all files that might be open concurrently in your job. If in addition the version of Model 204 is lower than 7.7, BTB buffers are also being used, and you can reduce the MAXBUF parameter by the same amount you increased NUMBUFG for EBM pages.

ATB storage for procedure pages

Procedure text pages, located in Table D, are also eligible to reside in the ATB buffer pool. Each SOUL procedure is stored in one or more procedure text pages, the initial page of which is pointed to by the procedure dictionary. (Pages from the procedure dictionary, which is also stored in Table D, are read into the BTB buffer pool.)

In a development environment where procedure page volume is high and where NUMBUFG is allocated, you might need to increase NUMBUFG to accommodate the procedure text pages. In this case, if BTB buffers are also being used (Model 204 version less than 7.7), you can reduce the MAXBUF parameter by the same amount you increased NUMBUFG.

ATB storage for screens and images

Pages used for Model 204 SCREEN and IMAGE items reside in the buffer pool above the bar.

ATB storage for hash table cells

The hash table is used to locate pages in the buffer pool based on the file and page number. You control the number of hash cells allocated in the hash table with the parameter HASHCELL. If NUMBUFG is also set to a value greater than zero to allocate buffers above the bar, the hash cells are also allocated above the bar.

ATB storage for XmlDoc object pages

As of Model 204 version 7.5, the CCATEMP pages used for XmlDoc objects use the ATB buffer pool, which might allow the BTB buffer pool to be reduced, perhaps providing more storage for server areas. It also might provide a reduction in CPU utilization, especially when the TEMPPAGE parameter is used to allocate CCATEMP in memory.

Monitoring disk buffers

To get started using ATB buffers in an environment where both ATB and BTB buffers will be used, you might want to implement NUMBUFG, then do more analysis later. A suggested starting value for NUMBUFG in this case is equal to your MAXBUF setting (while leaving MAXBUF at its current setting). Then use the MONITOR DISKBUFF commands to analyze the buffer pool utilizations.

Managing delayed disk updates

The disk update process allows delayed disk updates, which avoids duplicate database writes in certain situations.

When a user completes an update unit for a file and there are no other update units active against that file, Model 204 writes the buffer to disk with all of the file's modified pages, marks the file as physically consistent, and issues a message stating that the disk update is complete.

Specifying delayed updates with the DKUPDTWT parameter

The CCAIN parameter DKUPDTWT specifies delayed disk updates. The value of DKUPDTWT determines how many seconds a disk buffer containing a file's modified pages must have aged before it can be written to disk.

When DKUPDTWT is zero, the default value, Model 204 writes all of the file's modified pages to disk at the end of the last in-flight update of the file. The user who completed the last in-flight update waits for this disk update process to complete and for the message stating that the disk update is complete.

If DKUPDTWT is not zero, Model 204 delays the start of the disk update process for at least DKUPDTWT seconds, after which it may be the checkpoint pseudo subtask (CHKPPST) that performs the disk update. The user who completed the last in-flight update does not have to wait for the disk update process to complete.

When DKUPDTWT is not zero, the CHKPPST and CHKPTIMR pseudo subtasks are started automatically at Model 204 initialization. An error message informs you if the NSUBTKS parameter is set too low to start these pseudo subtasks.

The maximum value of DKUPDTWT depends on the value of the CPTIME parameter. If CPTIME is nonzero, DKUPDTWT must be less than or equal to CPTIME*30. The absolute maximum value of DKUPDTWT is 60.

The system manager can reset DKUPDTWT to zero while the online is running. It can be reset to a nonzero value as long as the CHKPPST and CHKPTIMR pseudo subtasks were started during Model 204 initialization.

Handling delayed updates and CHKPPST

The CHKPPST pseudo subtask plays a central role in handling delayed disk updates. When DKUPDTWT is set to 0, CHKPPST does the following:

1. Sleeps for CPTIME minutes.
2. Tries to quiesce updates, for up to CPTQ, plus CPTO seconds.
3. Takes the checkpoint, if all updates are quiesced.

If DKUPDTWT is greater than 0, CHKPPST has substantially more processing to perform:

1. Sleeps for DKUPDTWT divided by four seconds.
2. Further processing depends on the value, rounded to the nearest integer of:

   N = (CPTIME * 60) / (DKUPDTWT / 4)

Attempting a checkpoint

If the number of wake-up calls since the last checkpoint is N, CHKPPST takes a new checkpoint, as follows:

Attempt	Purpose
1.	Performs the disk update process on all files that are not being updated, regardless of how long since they were marked disk-update-needed.
2.	Attempts to deactivate Host Language Interface (HLI) updates for CPTQ seconds. Performs the disk update process on all files that are not being updated each time Model 204 determines that there are more HLI jobs to wait for.
3.	Attempts to deactivate all other updates for CPTO seconds. Performs the disk update process on all files that are not being updated each time Model 204 determines that there are more users to wait for.
4.	If all updates have been deactivated, performs the disk update process on all remaining files marked disk-update-needed. Otherwise, abandons the checkpoint attempt.
5.	Performs the disk update process again. Then takes the checkpoint.
6.	If the number of wake-up calls since the last checkpoint is not N, CHKPPST performs the disk update process on all files that have aged sufficiently — that is, marked disk-update-needed for at least DKUPDTWT seconds.

Factors affecting disk update and checkpoint processing

Several important factors affect the processing of disk updates and checkpoints:

• Some disk updates might be interrupted by another thread's request for the file's UPDATE resource. Attempts 1, 2, 3, 4, and 6 might be interrupted by an attempt to start a new update or by a user doing a disk update as part of CLOSE FILE processing. In these cases, the following message is issued, and the next file is processed:

  M204.0440: DISK UPDATED ABORTED

• Attempts 2, 3, and 4 might be interrupted by the expiration of the waiting time set with Model 204 parameters CPTQ and CPTO, respectively. In these cases, the M204.0440 message is issued, all remaining files are bypassed, and the checkpoint is timed out.
• If CPTQ and CPTO are zero (no time-out intervals specified) and the DKUPDTWT parameter is nonzero, updates are deactivated for as long as required to perform the disk update process for all available files. If you do not want checkpoint attempts to deactivate updates, set DKUPDTWT to zero.
• If Attempts 2, 3, or 4 abort due to a CPTO or CPTQ time-out, the checkpoint time-out message indicates the name of the file being written at the time of the time-out:

  M204.0843: CHECKPOINT TIMED OUT ON date/time UPDATING FILE file

• Attempt 5 cannot be interrupted once it begins. Therefore, CPTO and CPTQ intervals are not honored for a CLOSE FILE command that is blocking a checkpoint. This type of event is likely to be infrequent and of short duration.
• The sleep intervals of CHKPPST are not adjusted by the amount of time required to perform Attempt 6. Therefore, checkpoints might be spaced out by more than CPTIME minutes. If this is a frequent problem, adjust CPTIME downward.

Understanding file statistics

For descriptions of the file statistics DKUPTIME, UPDTTIME, and PDNGTIME, see Disk buffer monitor statistics and parameters.

Handling 64-bit statistics

To support very long running Model 204 regions, Model 204 V7R1 included modifications to the capacity of statistical counters (by increasing the size of some statistics and also exploiting 64-bit processing where appropriate). For sites upgrading to V7R1 or later, in-house or third-party support applications that process statistical counters need to review the statistics generated:

• As some of the statistics fields became double-words, check Using system statistics for a revised layout of the System, Final, and Partial statistics. Also, additional Disk Buffer Monitor, MP/204, and File statistics were updated.
• Examine your in-house or third-party support applications for changes you need to make because of the increased length of some of the statistics. Make any changes necessary to your applications, then reassemble with the release upgrade.
• If your in-house or third party support applications don't reference any of these double word statistics, you only need to reassemble your program with the updated offsets.

Server areas

Server areas are the internal work areas allocated to each user. Each area is divided into a fixed and variable portion. The fixed portion, which includes logical I/O buffers and user resettable parameters, is calculated by Model 204 at initialization. The variable portion can be changed dynamically with the UTABLE command or the IFUTBL IFAM function.

Sizing user server areas

The default size of all user server areas is set on User 0's parameter line. If the default is used, the allocated server area is exactly large enough to contain the tables for each user specified on each user's parameter line. If SERVSIZE is also specified on a particular user's parameter line, the default is overridden for that user.

The value of SERVSIZE must be as large as, or larger than, the user's aggregate table size. It is calculated by examining the user's server area requirements and monitoring the system statistics (described in ONLINE monitoring) that provide information about the installation work load. The following formula gives the approximate size:

SERVSIZE = fixed-table-size + variable-table-size

Where:

• fixed-table-size represents settings, defined during initialization, that cannot be modified during the run.
• variable-table-size represents settings that can be varied using the UTABLE command or its IFAM equivalent, IFUTBL.

SERVSIZE and server page alignment

Servers and some server tables are always aligned on a 4K page boundary. In pre-7.4 releases, server and tables alignment took place only when DSPOPT had settings of bits X'01' or X'02', or when the APSYPAGE parameter was indicated.

If you used server alignment previously, there is no change in your server size requirements.

If you did not use server alignment previously, then you might notice an increase in server size that in the worst case could be up to 24528 bytes per server.

When you calculate server size, take into account that FSCB, HEAP, NTBL, QTBL, STBL, and VTBL are each rounded on a 4K page boundary, so in the worst case each area could require up to 4088 bytes of server space, compared to servers with no alignment in previous releases.

The following sections explain how server area sizing parameters are processed, which parameters determine fixed and variable table sizes, and the ranges of values these parameters can take.

Initialization and error handling

During initialization, each user, except User 0, is identified in the output before the user's parameter line is read. The aggregate size of each user's tables and the size of tables fixed during initialization are printed after the user's parameters are read.

If errors are detected, they are reported and initialization continues whenever possible. If errors are detected during initialization, the run is canceled at the end of initialization. Error conditions in initializing the server cause the run to end immediately with a return code of 96.

The results of user changes to the sizes of FTBL, GTBL, ITBL, and XTBL are discussed in the UTABLE command Usage notes.

Calculating fixed table size

Use the following formula to calculate fixed table size, the FIXSIZE parameter value:

Fixed table size = 2520 + ((MAXINCL+6) * 80)dwr + ((LAUDPROC + 9) * (MAXINCL-1))dwr + (LIBUFF + 4) + (LOBUFF + 5)dwr + (LOUTPB)dwr + (((NGROUP + 12) * (NRMTFILE + NFILES + 1)) + (NRMTFILE + 1))dwr + ((NORQS*3) + 2)dwr + (3 * ERRMSGL)

Each term of this formula that is followed by dwr must be double word rounded to the next multiple of eight. For example, if the value of LOBUFF is 500, the term (LOBUFF + 5) equals 505, which must be rounded to 512, the next multiple of 8.

If SYSOPT is 1 or 2 (indicating CCASYS or CCAGRP), add 1 to the value of NFILES used in the formula. If SYSOPT is 3 (indicating both CCASYS and CCAGRP), add 2.

If any SQL threads are specified in CCAIN (IODEVs 13, 17, or 19), add 6712 bytes for C language work areas.

The "Fixed server table values" table, below, shows the minimum, maximum, and default values for parameters that affect fixed server table sizing. The rightmost columns show the relevant units of measure; for example, the maximum value of NORQS is 32767 entries (not bytes). The values of LIBUFF and LOBUFF may need to be increased for SQL processing. Recommended values are LIBUFF=3000 and LOBUFF=5000.

Fixed server table values

Parameter	Default	Max	Bytes/entries
ERRMSGL	80	256	Bytes
LAUDPROC	21	253	Bytes
LIBUFF	255	32767	Bytes
LOBUFF	256	32767	Bytes
LOUTPB	0	3000	Bytes
MAXINCL	5	40	90+LAUDPROC bytes per INCLUDE level
NFILES	2	16383	Entries
NGROUP	5	16383	Entries
NORQS	5	32767	Entries
NRMTFILE	0	16383	Entries

Calculating variable table size

Use the following formula to calculate variable table size:

Variable table size = 96 + ((HTLEN+5) * (MAXHDR + MAXTRL)) dwr + (LFSCB) dwr + (LFTBL) dwr + (LGTBL) dwr + (LHEAP) dwr + (LITBL) dwr + (LNTBL * 12) + (LPDLST +32) dwr + (LQTBL * 16) + (LSTBL) dwr + (LTTBL * 4)dwr + (LVTBL * 32) + (LXTBL) dwr

Each term of this formula that is followed by dwr must be doubleword rounded to the next multiple of eight. The "Variable server table values" table shows minimum and maximum values:

Variable server table values

Parameter	Default	Max	Bytes/entries/lines
HTLEN	132	32767	Bytes
LFSCB	8 (as of V7.7) 0 (7.6 or earlier)	65528	Bytes
LFTBL	1000	30 million	Bytes
LGTBL	288	2 billion	Bytes
LHEAP	0	2 million	Bytes
LITBL	8 (as of V7.7) 0 (7.6 or earlier)	32760	Bytes
LNTBL	50	32760	12-byte entries
LPDLST	2600	32760	Bytes
LQTBL	400	262,143	16-byte entries
LSTBL	600	16M	Bytes
LTTBL	50	8190	4-byte entries
LVTBL	50	524287	32-byte entries
LXTBL	1000	32760	Bytes
MAXHDR	5	32767	Lines
MAXTRL	5	32767	Lines

Server tables

Server tables are sections of the server area used by the SOUL compiler and evaluator to store all the information necessary to run a request. Some server tables are also used by the editor and HLI functions.

Each user has a copy of the server tables in the server. Table sizes are controlled by the parameters shown in the "Common runtime parameters" table. Parameter settings on the user's parameter line affect the size of the servers and the region.

The "Summary of server tables" lists the server tables. Further information on individual tables is contained in the subsections that follow.

Summary of server tables

Table	Contents
FSCB	Menu, screen, and image information
FTBL	File groups
GTBL	Global variables
ITBL	Dummy string and $READ responses
NTBL	Statement labels, list names, and variables
QTBL	Statements in internal form (quadruples)
RTBL	User privileges, class, and field level security information
STBL	Character strings
TTBL	Temporary work pages
VTBL	Compiler variables
XTBL	Procedure security

Full-screen buffer table (FSCB)

The full-screen buffer table (FSCB) stores menu, screen, and image definitions, in addition to the values of screen variables and image data blocks. FSCB space is reused by each logical menu definition, logical screen definition, or block definition.

The FSCB must be large enough to hold the largest screen, image, or menu definition. The following space is required:

• 144 bytes of fixed overhead for every menu, including the menu title
• 144 bytes for each menu prompt
• 432 bytes of fixed overhead for the first panel of every screen:
• 144 bytes for each subsequent panel, including the screen title
• 32 bytes for each screen prompt and input item
• 32 bytes for every screen line containing at least one input item
• 80 bytes for each defined screen line, including skipped lines
• Additional space for automatic validation, including:
• 2 or 4 bytes for each automatic validation option
• 256 bytes for the VERIFY command when a particular character set is used in a compiled screen for the first time

Additional occurrences of the same character set do not add extra space. ONEOF and character RANGE store each character string plus one byte for each string's length.

• 8 bytes for each number in a NUMERIC RANGE statement (16 bytes for each range pair)
• Space for every block used in image definition

The amount of required space is computed as the sum of the specific SOUL statements, clauses, and items. For a complete list of these values, see Full-screen feature.

File group table (FTBL)

Data structures particular to file groups are stored in FTBL. FTBL entries are:

• Sixty-two-byte fixed size entry plus six bytes for each file in the group definition.

  This entry is allocated each time a group is opened (explicitly by the OPEN command or implicitly for an ad hoc group) and is released when the group is closed.

• Variable entry, consisting of nine fixed-bytes plus a number of bytes equal to the length of the field name plus 11 bytes per file in the group

  This entry is created for collecting field-name codes and properties during a SOUL request. An entry is allocated each time a new field name is encountered in the request. The field entries are deleted at every END statement (including END MORE).

When the Inverted File Access Method (IFAM) is used:

• Host Language threads use FTBL under the same circumstances as SOUL.
• Field entries are not deleted until the group is closed or until IFFNSH is called.
• Increase the total FTBL requirement by NGROUP times four bytes.

For Parallel Query Option/204 server nodes, the required size of FTBL increases by eleven bytes times the total number of group members for temporary scattered groups opened at the client and containing a member on the server node.

For information on using FTBL in 64-bit storage, see Above the bar storage.

Understanding the global variable table (GTBL)

GTBL contains information about:

• Global variables
• Global images, screens, and menus

GTBL entries are created by the $Incrg, $Getg, and $Setg functions. When a global variable is redefined, its old entry is deleted from GTBL and a new entry is added.

In addition, a 32-byte trailer stores information about offsets.

For information on using GTBL in 64-bit storage, see Above the bar storage.

Clearing GTBL entries

The CLEARGO command deletes all images, screens, and menus. You can also use the CLEAR GLOBALS statement to delete selected types of GTBL entries. For details, see Global features.

Space allocation

The space allocation for a global variable includes:

• 4 bytes indicating the length of GTBL
• 1 byte for the length of the variable name
• Variable name
• 1 byte for the length of the current name
• Current value

Global images, screens, and menus require space for a 20-byte header in addition to the size of the object.

When allocating GTBL space, always remember to add 32 bytes for the trailer.

The minimum length of GTBL is 40 bytes (X'28').

Improving global variable processing

You can improve global variable processing by setting the FASTGLOB, GTBLPCT, and GTBLHASH parameters. See Global features for a discussion of how these parameters affect performance.

Dummy string and $READ table (ITBL)

ITBL holds dummy string and $READ responses that are entered as arguments to an INCLUDE statement or command.

The space allocation for an ITBL entry includes:

• Argument strings, including delimiters, which are saved as they are entered
• 4 bytes of overhead for each saved string

Space taken by a string is released when the included procedure is executed.

Labels, names, and variables table (NTBL)

NTBL holds labels, names, and variables. Each entry is allocated 12 bytes. NTBL has two entries for each first occurrence of a COMMON declaration.

NTBL has one entry for each of the following elements:

• Statement label
• List name
• %variable
• Image, menu, and screen variable
• Partner process opened by a request
• Additional COMMON declaration
• Unlabeled Find
• For Each Value statement
• For statement with the In Order clause
• Sequential or VSAM file opened simultaneously

Most NTBL entries are preserved by the MORE command, except for the unlabeled Find and secondary For entries, which are deleted.

A host language thread requires NTBL entries for list names, compilation names, and variables.

FLOD uses NTBL entries for tags and index registers. The size of NTBL determines the highest tag or index that can be specified. In this case, NTBL must be at least 12 bytes multiplied by the highest tag or index size desired.

You need not allow extra space for runtime NTBL storage used during request evaluation of an Open Dataset, Open External, or Open Terminal statement. Use the compiler highwater mark to set LNTBL.

For information on using NTBL in 64-bit storage, see Above the bar storage.

Internal statement table (QTBL)

QTBL holds internal Model 204 instructions that result from compilation of each internal statement. After compilation, the entries in QTBL drive the evaluator. QTBL is emptied by End and End More statements.

The Editor formats all of QTBL into 16-byte entries, which provide a map of text being edited. The number of entries used depends on the number and position of insertions and deletions, not on the amount of text.

Quadruple (QTBL) entries generated by SOUL statements vary in number and size. The "Sample QTBL entries" table, below, shows typical values for each entry. For more QTBL information, see QTBL (internal statement table).

You can reduce server I/O by allowing users executing shared precompiled procedures to use a shared copy of QTBL.

For information on using QTBL in 64-bit storage, see Above the bar storage.

QTBL and IFAM processing

When using the Inverted File Access Method (IFAM):

• IFFIND, IFCOUNT, and list manipulations build quadruples so that the SOUL evaluator routines can be used.
• IFGET, IFMORE, and IFPUT build field name lists in QTBL.
• Other calls are evaluated directly.

IFAM's use of QTBL and the effect of the compiled IFAM feature are discussed in detail in Internal statements/quad table (QTBL) and Using the compiled IFAM facility.

QTBL and FLOD processing

FLOD builds its own quadruples (flodruples) in QTBL. Flodruple sizes vary, but most are 20 bytes or less.

Major exceptions are:

• Read-and-load-field flodruple, which expands four bytes for each entry in a translation table
• CASE statement, which requires eight bytes for each comparison string

Sample QTBL entries

"Sample QTBL entries" shows typical QTBL entry sizes for various SOUL statements and program structures:

Sample QTBL entries

SOUL statement	QTBL entry size
$functions	16 + 3 per argument
%variable, subscripted (reference to)	16 + expression evaluation
ADD	20
AFTER	20
AND (except where AND is part of BETWEEN)	16
Conversion between a string and a number	16
CALL	16
CHANGE	44
CLEAR LIST	20
CLEAR ON	16
CLEAR TAG	16
CLOSE	16
CLOSE PROCESS	16
COMMIT	4
COMMIT RELEASE	20
COUNT RECORDS (with a group)	52 + 20
DELETE	24
DELETE RECORD	16
ELSE	16 + body of the clause
ELSEIF	16 + body of the clause END
END	4
Function call	16 + argument evaluation
FIND (with at least one direct condition)	64 + 16
FIND (with inverted condition)	64 + 36
FIND ALL RECORDS (no qualification)	64
FIND ALL RECORDS (with record security and group)	64 + 52 + 20
FIND ALL RECORDS (with record security)	64 + 52
FIND ALL VALUES (FRV field)	74
FIND ALL VALUES (ORDERED field)	32
FOR EACH RECORD	24 + body of the loop
FOR EACH VALUE OF (with IN ORDER, a group)	88 + body of the loop + 68 + 24
GREATER THAN	20
IDENTIFY	16
IF	32
IF (with operator)	32 + 16
Index loop	40 + expression evaluation + body of the loop
IN RANGE FROM and TO, BETWEEN	28
INSERT	24
MODIFY	16
NOTE	20
ON	16 + included statements
OPEN	20
OPEN PROCESS	20
OR	16
PAUSE	16
POSITION	20
PREPARE IMAGE	8
PREPARE MENU	8
PREPARE SCREEN	8
PRINT	16 for each term
PRINT (a field)	16 + 20
PRINT MENU	16
PRINT SCREEN	16
READ IMAGE	16
READ MENU	20
READ SCREEN	20
RECEIVE	16
RELEASE RECORD	20
RELEASE POSITION	8
REPEAT	16 + evaluation of WHILE clause
REREAD SCREEN	20
RETRY	16
RETURN	16
SEND	16
SIGNAL PROCESS	12
STOP (automatically generated)	16
STORE RECORD (with each field)	16 + 16
TAB	4
TAG	16
THEN	16 + body of the clause
TRANSFER	16
WITH	0
WRITE IMAGE	12

User, field, group security table (RTBL)

RTBL contains a user's privileges, class, field-level security (FLS) levels for each open file, and classes for open, permanent groups.

The size of RTBL is calculated from the formula:

(((NGROUPS + 11) * (NFILES + 1)) + (NRMTFILE + 1))dwr

For Parallel Query Option/204 client nodes, the required size of RTBL increases by (NRMTFILE=1) bytes.

Character string table (STBL)

STBL stores all character strings in counted form, with a 1-byte length preceding the string itself. The following considerations apply to space usage:

• Space used to store intermediate results during an arithmetic expression evaluation is freed when the evaluation is completed.
• Space used by FOR EACH OCCURRENCE, FOR EACH RECORD, and FOR EACH VALUE loops is reused until the end of the loop.
• The last value of a Note statement remains in STBL.
• FIXED or FLOAT %variable array uses eight bytes for each element.

When the %variable is reassigned, the STBL space is reused.

• The FIELD SAVE option requires 10 bytes plus the maximum length of the string plus one byte for each element.

NO FIELD SAVE does not reserve the extra 10 bytes and results in significant saving when using a multidimensional array.

• MORE releases all but the space required by %variables and arrays.
• If a user is using the pattern matcher in an IF statement with an IMAGE or SCREEN ITEM as the pattern and an IMAGE or SCREEN ITEM as the comparison string, then the value of the pattern is stored in STBL. The space is freed after each comparison, so the maximum increase is equal to the size of the largest pattern in a request that meets the above criteria.

When the Inverted File Access Method (IFAM) is used

• IFDVAL and IFFILE store the value string from the input parameter in STBL.
• Strings enclosed in quotation marks or values specified for IFFIND that are stored in STBL are the same types as those stored in STBL by SOUL.
• EDIT form of IFPUT uses STBL for each value. Space from previous values is reused.
• FLOD stores translation table values and CASE statement comparison values in STBL.

Parallel Query Option/204 STBL requirements

STBL requires an increase for Parallel Query Option/204 $functions used in remote file or scattered context and for SOUL pattern matching processes

• Using one of the following $functions in remote context requires 12 additional bytes in STBL:

  $Curfile

  $RlcFile

  $Update

  $UpdFile

• If you are using the pattern matcher in any SOUL statement, the full size of the pattern is used and stored in STBL. The space is freed after each statement block using the pattern matcher, for example, FIND or FOR.

Temporary work page list table (TTBL)

TTBL entries keep track of scratch file (CCATEMP) pages. The entries are four bytes each and used by the Editor and FIND (or IFFIND) evaluator routines.

• The Editor uses scratch pages to make a private copy of the procedure being edited.
• FIND uses scratch pages as work space for evaluating Boolean expressions.

The number of TTBL entries required by FIND depends on the complexity of the Boolean expression. Entries are released at the end of the FIND statement evaluation.

Compiler variable table (VTBL)

VTBL stores values of simple variable types and refers to the String Table (STBL) in cases of more complex variables. The variables are local (%variables), internal, screen, and image variables.

Many SOUL statements and some constructs cause one or more compiler variables to be allocated in VTBL.

Entries in VTBL vary in size. The "Sample VTBL entries" table shows typical values. For more information, refer to VTBL (compiler variable table).

Sample VTBL entries

SOUL statement	VTBL entry size (bytes)
% variable:
FIXED	16
FLOAT	12
STRING	24
array	20
array element reference	12
CALL	4 + (4 * arguments)
CALL statement evaluation	28
COUNT	8
FIND (basic entry, single file)	8
workspace	20 + 20 + 28
fieldname = value pair	20 or more
retrieval	28
Ordered Index retrieval	4 + 4 per segment
FIND (basic entry, group)	8 + (8 * files)
FOR EACH RECORD (no IN ORDER clause)	16
FOR EACH VALUE (with FROM, TO, LIKE, ORDERED	48
FOR EACH RECORD IN ORDER BY (with ORDERED field)	48
FOR EACH VALUE (with ORDERED field)	40
Function (SOUL)	4 + (4 * arguments)
Lists:
single files	8
groups	8 + (8 * files)
Menu definition	48
Numeric expression	16
ON	28
Related image set	12 + 4 for every 256 items
Screen definition	68 + 4 for each panel
Screen entry (one panel)	72
SORT
each referenced field	20
each sort key	32
String expression	8
Subroutine declaration	16 + parameters

Effect of the MORE parameter on VTBL

The MORE parameter deletes all VTBL entries except %variables, list entries, images, menus, screens, labeled SORT and sort key entries, labeled FIND entries, and labeled COUNT entries.

IFAM and FLOD considerations

The following considerations apply to VTBL:

IFAM requires VTBL space for IFFIND, IFCOUNT, and lists (matching SOUL requirements), and a few extra bytes for temporary work space.

FLOD needs a minimal amount of VTBL space if the L statement (locate loop) is used.

VTBL requirement for Application Subsystem users

The size of VTBL for Application Subsystem users loading saved compilations does not have to be as large as the compiling user's VTBL. As long as the loading user's VTBL size accommodates the request's VTBL requirement, the loading user can have a smaller VTBL than the compiling user.

Procedure security table (XTBL)

XTBL contains procedure security information for each file and permanent group member that a user has open. The size of each file entry depends on the number of user-class/procedure-class mappings defined in the file for the user's class.