Version 4.2.6 for Mainframes
 —  Operations  —

Natural Roll Server Operation

This document covers the following topics:

See also Natural Roll Server Functionality.


Roll Server System Requirements

This section describes the Roll Server system requirements.

APF Authorization

Link the module NATRSMvr (vr=version, release number) to an Authorized Program Facility (APF) library, specifying IEWL parameter AC(1). Refer to Installation Procedure for Natural under z/OS.

System Linkage Index

As the Roll Server reserves one system linkage index (System LX), check whether there is a high enough value of NSYSLX in member IEASYSxx of library SYS1.PARMLIB.

When the Roll Server terminates, its address space ID is no longer available because a System LX has been used. It becomes available again with the next IPL.

To avoid this, deactivate the Roll Server with the DEAL operator command and restart it afterwards.

Once a System LX has been reserved, it is reused with every restart of the Roll Server until the next IPL.

Virtual Storage

Storage Size
ECSA 84 bytes
Private program storage 30 KB above
Fixed subpool storage (incl. ELSQA): 10 KB below, 50 KB above
LRB directory 32+(64*number of LRB slots)
100 slots per roll file 4 KB above
Every additional roll file 30 KB above
Working storage depending on load, about 1 MB above

CF Structure

The space required is calculated using the following formula:

24 KB + (RFN + 1) * 1 KB + (RFS + 8) * 160 bytes

where RFN denotes the number of roll files and RFS denotes the total number of roll-file slots in all roll files.

Example:

XCF Signalling Paths

In a z/OS Parallel Sysplex environment, the Roll Servers communicate via the XCF Signalling Services. As the default XCF group name, the leftmost eight bytes of the CF structure name are used.

If you want to specify your own XCF groupname, use the NATRSU24 user exit. For more information on this user exit, see NATRSU24 User Exit.

Top of page

Formatting the Roll File

To format the roll file, proceed as follows:

  1. Allocate it as a physical, sequential dataset with a fixed-record format.

  2. Format it using module NATRSRFI.

During formatting, the roll file is converted to BDAM format with a device-dependent block size.

Note:
If you plan to use an existing roll file of a previous version, it is sufficient to execute the NATRSRFI RESET function.

To format, enter the following parameter string under the DD name RFIPARMS, or as PARM on the JCL EXEC statement:

function,dd-name,slot-size,number-of-slots

All parameters are positional; they are explained in the table below:

Parameter Description
function FORMAT Format the roll file.
RESET

All roll file slots are reset (marked as free). You can only use this parameter value if the roll file has already been formatted.

The only other parameter allowed is dd-name.

LIST

Print a list of session-IDs contained in the roll file and their last activity.

The only other parameter allowed is dd-name.

dd-name The name of the DD statement under which the roll file has been specified.
slot-size

The size of a roll file slot in bytes. This size is rounded to the next higher multiple of the block size used.

It is recommended to initially use a slot size equal to the size of the Natural thread. Then look at the Roll Server statistics. They also show the largest occurrence of a thread size. Use this value to reduce the slot size, if necessary.

number-of-slots

The number of roll file slots to be allocated. This number is the maximum number of concurrently active users.

This parameter is optional. If omitted, the entire roll file, as allocated, will be formatted.

To calculate the required disk space in cylinders for a roll file (SPACE parameter of the DD statement), use the following formula:

number-of-cylinders = ceiling (number-of-slots * slot-size / 30*block-size)

or in tracks

number-of-tracks = ceiling (number-of-slots * slot-size / 2*block-size)     

The block size used is:

23476 for 3380 DASD

27998 for 3390 DASD

22928 for 9345 DASD

In addition, space is needed for the roll file directory header (40 bytes) and one directory entry for each roll file slot (24 bytes). Thus, one additional block is needed for roughly 976 slots on 3380, 1164 slots on 3390, or 953 slots on 9345 DASD.

NATRSRFI Output

If a DD statement with ddname RFIPRINT is specified, NATRSRFI directs its output to this dataset. When RFIPRINT is omitted, output is written to JESMSGLG using the WTO macro (ROUTDCE=11). Note that RFIPRINT must be specified for the LIST function.

NATRSRFI Conditon and Abend Codes:

The following condition codes are used:

0 Normal completion.
4 Number of slots formatted is less than requested.
20 Parameter error.

The following user abend codes are used:

Abend Code Cause
U0100 Open for RFIPARMS or RFIPRINT failed.
U0101 Open for roll file failed.

Example 1:

//FBRUNRFI JOB  (FB,218),FB,CLASS=K,MSGCLASS=X,NOTIFY=FB                        
//FORMAT   EXEC PGM=NATRSRFI                                                    
//STEPLIB  DD  DISP=SHR,DSN=NATURAL.NATvr.LOAD                                  
//RF1      DD  DISP=SHR,DSN=FB.SYSF.ROLLF1                                      
//RF2      DD  DISP=SHR,DSN=FB.SYSF.ROLLF2                                      
//RFIPARMS DD  *                                                                
FORMAT,RF1,200000,1000                                                          
FORMAT,RF2,200000                                                               
/*
 
Exerpt from resulting JESMSGLG:
+FBRUNRFI: FORMAT,RF1,200000,1000
+FBRUNRFI: RF1: FB.SYSF.ROLLF1
+FBRUNRFI:      Creation date: 2001/06/13 Volume: ADA002(3390)
IEC031I D37-04,IFG0554P,FBRUNRFI,FORMAT,RF1,305B,ADA002,FB.SYSF.ROLLF1
+FBRUNRFI: Not enough space for 1000 slots.
+FBRUNRFI:       60 Blocks written. Block size is 27998.
+FBRUNRFI:        1 Directory block.
+FBRUNRFI:        8 Blocks per slot. Slot size is 223984.
+FBRUNRFI:        7 Slots initialized. Roll file version vrs.
+FBRUNRFI:        3 Blocks unused.
+FBRUNRFI: FORMAT,RF2,200000
+FBRUNRFI: RF2: FB.SYSF.ROLLF2
+FBRUNRFI:      Creation date: 2001/06/08 Volume: USRF08(3380)
IEC031I D37-04,IFG0554P,FBRUNRFI,FORMAT,RF2,020F,USRF08,FB.SYSF.ROLLF2
+FBRUNRFI:       60 Blocks written. Block size is 23476.
+FBRUNRFI:        1 Directory block.
+FBRUNRFI:        9 Blocks per slot. Slot size is 211284.
+FBRUNRFI:        6 Slots initialized. Roll file version vrs.
+FBRUNRFI:        5 Blocks unused.

where vrs = version, release, system maintenance level.

Example 2:

//FBRUNRFI JOB  (FB,218),FB,CLASS=K,MSGCLASS=X,NOTIFY=FB
//FORMAT   EXEC PGM=NATRSRFI,PARM='FORMAT,RF1,200000'
//STEPLIB  DD  DISP=SHR,DSN=NATURAL.NATvr.LOAD
//RF1      DD  DISP=SHR,DSN=FB.SYSF.ROLLF1
//RFIPRINT DD  SYSOUT=X

Resulting RFIPRINT:

Natural Roll Server - Roll File Utility Version 
vrs
FORMAT,RF1,200000
RF1: FB.SYSF.ROLLF1
Creation date: YYYY/MM/DD Volume: ADA002(3390)
60 Blocks written. Block size is 27998.
1 Directory block.
8 Blocks per slot. Slot size is 223984.
7 Slots initialized. Roll file version vrs.
3 Blocks unused.

Notes Concerning the Formatting or Resetting of Roll Files

Top of page

Starting the Roll Server

You start the Roll Server either as a batch job or as a started task by executing module NATRSMvr. The roll file(s) must be defined as DD statements with ddname ROLLF1 to ROLLF5.

On the JCL EXEC statement, specify as PARM the following parameters:

subsystem-id,number-of-roll-files,number-of-LRB-slots,LRB-slot-size,CF-structure-name,low-water-mark,high-water-mark,non-activity-time,timeout-check-time,message-case

All parameters are positional and must be separated by a comma. They are explained in the table below:

Parameter Possible Values Default Comment
subsystem-id 4-byte non-blank string NATv

The specified value must match the value of the Natural profile parameter SUBSID (v = version number).

Note:
With Natural under CICS, refer to the ROLLSRV parameter in the NCMDIR macro for setting the appropriate subsystem ID.

number-of-roll-files 0 - 5 1 In a z/OS non-Parallel Sysplex system, the Roll Server can operate without a roll file, using only the in-storage Local Roll Buffer.
number-of-LRB-slots 1 - 32767 none

The number of LRB slots multiplied by the slot size must not exceed 2 GB.

The same number of LRB slots is assigned for each LRB, i.e. for each roll file used. The total number of LRB slots is calculated by the formula:

number-of-roll-files * number-of-LRB-slots

LRB-slot-size any numeric value roll file slot size Value in number of bytes.

This parameter must be specified if no roll file is used.

If roll files are used, this parameter is ignored and the roll file slot size is used instead.

CF-structure-name any valid structure name none If you specify less than 16 characters, blanks are appended.

Only specify this parameter if you use the Coupling Facility (with z/OS Parallel Sysplex).

low-water-mark 1 - 9 7 Specifies the low water mark in steps of ten percent of the number of LRB slots.

This parameter is ignored in a z/OS Parallel Sysplex environment.

high-water-mark 1 - 10 8 Analogous to low-water-mark parameter.

Value "10" means that the staging task will never be activated. It is only recommended to specify "10" if the LRB is large enough to serve all simultaneously active Natural sessions.

This parameter is ignored in a z/OS Parallel Sysplex environment.

non-activity-time 1 - 999999 none Number of hours a session can be inactive before it is deleted from the roll file.

If this time is exceeded, the session is deleted during the next scheduled timeout check.

If this parameter is omitted, no timeout check will be executed.

This parameter can be changed using operator command TIMEOUT, see below.

timeout-check-time 0000 - 2359 none The time of day that the timeout check is to be run.

Sessions will be deleted if they have been inactive longer than the non-activity time specified by the preceding parameter.

If this parameter is omitted, no timeout check will be scheduled.

This parameter can be changed using operator command TIMEOUT, see below.

message-case UCTRAN or blank blank Specify UCTRAN if the Roll Server is to issue all its messages in upper case.

Note:
The Local Roll Buffer resides in a Memory Object "above the bar". Use the MEMLIMIT parameter on the EXEC statement to ensure enough memory can be allocated "above the bar".

Examples for Starting the Roll Server as a Batch Job

//   EXEC PGM=NATRSMvr,PARM='NAvr,,1000'
//ROLLF1 DD DSN=SYSF.ROLLFILE

The subsystem ID is NA vr, one roll file is used (default), and the Local Roll Buffer has 1000 slots. The slot size used is identical with the roll file's slot size. The low water mark is 70% (default), the high water mark is 80% (default).

//   EXEC PGM=NATRSMvr,PARM=',5,1000,150000,NATROLL1',MEMLIMIT=800M
//ROLLF1 DD DSN=DASD1.ROLLFILE
//ROLLF2 DD DSN=DASD2.ROLLFILE
//ROLLF3 DD DSN=DASD3.ROLLFILE
//ROLLF4 DD DSN=DASD4.ROLLFILE
//ROLLF5 DD DSN=DASD5.ROLLFILE

The subsystem ID is NATv (default), five roll files are used, and each of the five Local Roll Buffers has 1000 slots. The LRB slot size is 150000 bytes. The roll file directory resides in the Coupling Facility structure NATROLL1. Low and high water marks are ignored, because every thread is written to the roll file (see Natural Roll Server Functionality). Since this job is intended for z/OS, the MEMLIMIT option specifies 800 Megabytes for the Local Roll Buffers.

Note:
The Roll Server will not start in the following cases:

Top of page

Roll Server Messages, Condition Codes and Abend Codes

The Roll Server writes informational and error messages to JESMSGLG using the WTO macro (ROUTCDE=11). The messages are preceded by a message identifier and the Roll Server's job name, for example:

RSM0019 FBRSMvrs: Roll Server Version vrs is active

The messages are explained in the section Roll Server Messages in the Messages and Codes documentation.

Condition Codes of the Roll Server Started Task

The following condition codes are used:

0 Normal completion
12 Wrong parameter input
16 Runtime error
20 Abend has occurred
>100 Initialization error

User Abend Codes

When an unexpected return code is issued by an XCF or XES Service Call, an abend with a dump is forced. Register 14 of the abend register contains the reason code. To find a description of the reason, refer to Programming: Sysplex Services Reference (IBM documentation). If the error was not environment-specific, send the dump to Software AG support.

The following user abend codes are used:

Abend Code Cause
U0200 IXLCONN failed
U0201 IXLFORCE failed
U0202 IXLLIST failed
U0203 IXLDISC failed
U0204 IXCLEAVE failed
U0301 IXLLIST failed
U0302 IXCMSGO failed
U0401 IXLLIST failed
U0501 IXLLIST failed

Top of page

Return Codes and Reason Codes of the Roll Server Request

These are codes that Natural may receive from the Roll Server's PC services routines. They are reported by the respective teleprocessing interfaces (Natural CICS or Natural IMS interface). For a list of these codes, refer to the Return Codes and Reason Codes of the Roll Server Request in the Messages and Codes documentation.

Top of page

Operating the Roll Server

The following commands can be passed to the Roll Server via the MODIFY operator command:

Command Description
DEAL The Roll Server is stopped, but the address space is not terminated. The roll file directory and all modified LRB slots are written to the roll file. In a de-allocated status, the Roll Server can be restarted with new parameters and the old address space ID. The roll files can be reformatted in de-allocated status. If you do that, however, currently active Natural sessions are no longer restartable.

Statistics are written to JESMSGLG using the WTO macro (ROUTCDE=11). Statistics include information about roll-out and roll-in activity, as well as roll file I/O.

DIAGNOSE Debugging function, only to be used at Software AG's advice.

This command does not have any function. Its intended future use is in connection with special Zaps to aid in diagnosing specific customer problems, as the need arises.

SNAP Debugging function. The Roll Server's address space is dumped to SYSUDUMP.
START,parmstring Reactivates the Roll Server with the specified parameters. You can only use this command in deactivated status.
STATS Write Roll Server statistics to JESMSGLG using the WTO macro (ROUTCDE=11). Statistics include information about roll-out and roll-in activity, as well as roll file I/O.
TERM Stops the Roll Server. The roll file directory and all modified LRB slots are written to the roll file and the address space is terminated. The address space ID is no longer available until the next IPL.

Statistics are written to JESMSGLG using the WTO macro (ROUTCDE=11). Statistics include information about roll-out and roll-in activity, as well as roll file I/O.

TIMEOUT NAT nnn Specifies or replaces the non-activity time parameter.
TOC hhmm Specifies or replaces the time of day of the timeout check.
OFF Disables timeout checking.
ON Reinstates timeout checking.
NOW Starts an immediate timeout check. Normal timeout check scheduling (if specified) remains in effect.
?

(or no specification)

Displays current timeout settings. The question mark (?) is optional and can be omitted.
TRSTART Debugging function, only to be used at Software AG's advice. Activates the Trace Task. If the General Trace Facility (GTF) is started and enabled for user records of Type 200, trace records are written to the GTF.
TRSTOP Deactivates the Trace Task.

Top of page

Roll Server Performance Tuning

As a general rule for Roll Server performance tuning, give the Roll Server a higher dispatching priority than the address spaces where Natural runs.

To find out where the weaknesses in performance are, analyze the system performance using the Natural Subsystems and Roll Server Information function of the SYSTP utility.

When looking at Roll-Server Statistics, keep an eye especially on the following values:

Top of page

Roll Server User Exits

The roll server has two user exits.

Sample source modules are delivered for these.

NATRSU14 User Exit

Specifies the roll file number to be used.

Entry calling conventions:

Return calling convention:

Note:
If access registers are modified within this user exit, these access registers must be saved and restored on return. This user exit is called in primary addressing mode with PSW Key 8. Since it runs in cross-memory mode, no SVC except SVC 13 may be used.

NATRSU24 User Exit

Specifies the XCF group name to be used.

Entry calling conventions:

As a group name default, the Roll Server will use the leftmost 8 bytes of the CF structure name.

This user exit is called in primary mode, PSW Key 8 and in task mode.

Top of page