Natural Roll Server Operation

#### Search Results

Search

# Natural Roll Server Operation

This section covers the following topics:

- Roll Server System Requirements

- Formatting the Roll File

- Starting the Roll Server

- Roll Server Messages, Condition Codes and Abend Codes

- Return Codes and Reason Codes of the Roll Server Request

- Operating the Roll Server

- Resetting the Coupling Facility Structure

- Roll Server Performance Tuning

- Roll Server User Exits

See also Natural Roll Server Functionality.

## Roll Server System Requirements

This section describes the Roll Server system requirements.

- APF Authorization

- System Linkage Index

- Virtual Storage

- CF Structure

- XCF Signaling Paths

### APF Authorization

Link the module `NATRSMvr` (vr represents the relevant product version) to an Authorized Program Facility (APF) library, specifying `IEWL` parameter `AC(1)`. Refer to Installing Natural on 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.

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

A CF structure is used to hold the roll file directory in a z/OS Parallel Sysplex environment.

The size of a CF structure can be calculated using the IBM web utility "CFSizer", which can be found here:https://www.ibm.com/support/pages/cfsizer

There, you must choose "XCF" in the selection box, there where you see "Choose one".

You get a new window, which is pre-filled with "Number of systems" = 8 and "CLASSLEN" = 956 (= 936 + 20 -> CONA + CONALOCKATTR)

See macro `IXLYCONA` for those size:

    01 SIZE:
    *            CONA          -- X'03A8' bytes = 936
    *            CONALOCKATTR  -- X'0014' bytes =  20
    *            CONALISTATTR  -- X'0028' bytes =  40
    *            CONACACHEATTR -- X'001C' bytes =  28

Roll Server only uses CONA = 936 bytes.

Once you select "Number of systems" = n (LPARs), and you press "Submit", you get something like (5 LPARs with 936 bytes):

Function | Type | Structure Name | INITSIZE | SIZE
--- | --- | --- | --- | ---
XCF | LIST | IXC...... | 18M | 19M

followed by a number of lines with JCL.

### XCF Signaling Paths

In a z/OS Parallel Sysplex environment, the Roll Servers communicate via the XCF Signaling 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 group name, use the `NATRSU24` user exit. For more information on this user exit, see NATRSU24 User Exit.

## Formatting the Roll File

To format the roll file, proceed as follows:

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

2. Format it using module `NATRSRFI`.

3. If the roll server executes in a z/OS Parallel Sysplex environment, reset the Coupling Facility structure as described in the Notes Concerning the Formatting or Resetting of Roll Files.

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. Note that during formatting, the system abend code SB37 or SD37 (or S209 for a VSAM file) can be encountered. This abend is intercepted by the formatting routine and can be ignored.

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 data set. 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 Condition and Abend Codes:

The following condition codes are used:

Code | Explanation
--- | ---
`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.

#### Examples:

In the following examples, vr or vrs represents the relevant product version.

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

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

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

- You can format or reset several roll files at once by specifying several parameter lines in `RFIPARMS`.

- You cannot format or reset a roll file while the roll server is active.

- When the roll file is formatted in a z/OS Parallel Sysplex environment, the roll server Coupling Facility structure must also be cleared using the `SETXCF` operator command, for example:

      SETXCF FORCE,STR,STRNAME=NATROLL1

## Starting the Roll Server

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

You can specify parameters in the JCL `EXEC` statement, in a parameter file, or in both. A parameter specified in the `EXEC` statement overwrites the corresponding parameter in the parameter file.

Software AG recommends using a parameter file. The parameter `TIMEOUTREPEAT` (see Parameters in the Parameter File) and future parameters can only be specified in the parameter file. Existing JCL will continue to execute unchanged.

This section covers the following topics:

- Parameters in the JCL EXEC Statement

- Parameters in the Parameter File

- Examples for Starting the Roll Server as a Batch Job

### Parameters in the JCL EXEC Statement

Parameters in the JCL `EXEC` statement:

    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 | Parameter name for parameter dataset | Possible Values | Default | Comment
--- | --- | --- | --- | ---
`subsystem-id` | `SUBSID` | 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` | `NUMFILES` | `0 - 5` | `1` | In a z/OS non-Parallel Sysplex environment, the Roll Server can operate without a roll file, using only the in-storage Local Roll Buffer.
`number-of-LRB-slots` | `NUMSLOTS` | `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` | `SLOTSIZE` | 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. If no roll files are used meaning the number-of-roll-files is zero, this parameter is mandatory.
`CF-structure-name` | `STRUCTURE` | 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). Otherwise, using this parameter might cause unnecessary overhead
`low-water-mark` | `LOWWATER` | `0 - 9` | `7` (single z/OS) `0` (sysplex) | Specifies the low water mark in steps of 10 percent of the number of LRB slots. LWM can not be higher than the current HWM. This value is always ignored and reset to `0` if CF-structure-name has a value, independently of what was specified.
`high-water-mark` | `HIGHWATER` | `0 - 10` | `8` (single z/OS) `0` (sysplex) | 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. HWM can not be lower than the current LWM. This value is always ignored and reset to `0` if CF-structure-name has a value, independently of what was specified.
`non-activity-time` | `NONACTIVITY` | `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. Both the Authorized Services Manager and the Roll Server allow to specify a timeout value. If Natural is running in a SYSPLEX environment, set the same value for this parameter and the `NONACTIVITY` parameter of the Authorized Services Manager.
`timeout-check-time` | `TIMEOUTCHECK` | `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` | `MSGCASE` | `UCTRAN` or blank | blank | Specify `UCTRAN` if the Roll Server is to issue all its messages in upper case.
`repeat-timeout-check` | `TIMEOUTREPEAT` | `0000 - 1440` | none | The number of minutes between two consecutive timeout checks. This allows for a timeout check to occur several times a day.

### Parameters in the Parameter File

The parameter file is a physical sequential file (DSORG=PS). In your JCL, specify this file with `DDNAME RSMPARM`.

Parameters in the parameter file are specified as name=value pairs, for example, `NUMFILES=1`. Specify one parameter per line, starting in Column 1. The name=value pair is terminated by the first blank, and the rest of the line is not examined. Lines starting with an asterisk (*) in Column 1 are treated as comments. Parameters are translated to upper case before they are processed.

Parameter | Possible Values | Default | Comment
--- | --- | --- | ---
`SUBSID` | 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 `CICSPLX` parameter in the `NCMDIR` macro for setting the appropriate subsystem ID.
`NUMFILES` | `0 - 5` | `1` | In a z/OS non-Parallel Sysplex environment, the Roll Server can operate without a roll file, using only the in-storage Local Roll Buffer.
`NUMSLOTS` | `1 - 32767` | none | The number of LRB slots assigned for each roll file in use. (The total number of LRB slots is calculated by this formula: NUMFILES * NUMSLOTS)
`SLOTSIZE` | 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.
`STRUCTURE` | 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).
`LOWWATER` | `0 - 9` | `7` (single z/OS) `0` (Sysplex) | Specifies the low water mark in steps of 10 percent of the number of LRB slots. LWM can not be higher than the current HWM. This value is always ignored and reset to `0` if `STRUCTURE` has a value, independently of what was specified.
`HIGHWATER` | `0 - 10` | `8` (single z/OS) `0` (Sysplex) | Analogous to low-water-mark parameter. A value of `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. HWM can not be lower than the current LWM. This value is always ignored and reset to `0` if `STRUCTURE` has a value, independently of what was specified..
`NONACTIVITY` | `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 the operator command `TIMEOUT`, (see Operating the Roll Server).
`TIMEOUTCHECK` | `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 Operating the Roll Server).
`TIMEOUTREPEAT` | `0 - 1440` | none | The number of minutes between two consecutive timeout checks. The first timeout check after Roll Server start is run after `TIMEOUTREPEAT` minutes. If `TIMEOUTCHECK` is also specified, the first timeout check is run at the time specified with `TIMEOUTCHECK`, and then every `TIMEOUTREPEAT` minutes. Specifying `0` or `1440` indicates no timeout repeat, and the timeout check is run only at the time specified with `TIMEOUTCHECK`.
`MSGCASE` | `UPPER` or `MIXED` | mixed case | `MSGCASE=UPPER` causes all messages to be displayed in uppercase letters. `MSGCASE=MIXED` causes all messages to be displayed in mixed case letters.

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

In the following examples, vr represents the relevant product version

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

The subsystem ID is `NAvr`, 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 percent (default), the high water mark is 80 percent (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:

- Another Roll Server is running with the same subsystem-id.

- Another Roll Server is accessing a roll file specified in its JCL

- A roll file has been reformatted without resetting the CF structure, using the `SETXCF FORCE` command.

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

where vrs represents the relevant product version.

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

## 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 Interface or Natural IMS TM 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.

## Operating the Roll Server

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

Command | Description
--- | ---
`HELP` | Shows an overview of the available syntax.
`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.
`HWM n` | Sets the LRB high water mark to n times 10 percent of the number of LRB slots (n=0-10). HWM can not be lower than the current LWM. HWM is always ignored and reset to `0` if `STRUCTURE` has a value. If n is not specified, the current low and high water marks are displayed.
`LWM n` | Sets the LRB low water mark to n times 10 percent of the number of LRB slots (n=0-9). LWM can not be higher than the current HWM. LWM is always ignored and reset to `0` if `STRUCTURE` has a value. If n is not specified, the current low and high water marks are displayed.
`SNAP` | Debugging function. The Roll Server's address space is dumped to `SYSUDUMP`.
`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.
`TERMinate` | `STOP` | 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.
`TERSE` | Suppresses the messages RSM0072 and RSM0074 during `TIMEOUT NOW` processing. Message RSM0047 `Operator command: TIMEOUT NOW` is also suppressed.
`VERBOSE` | Displays the messages RSM0072, RSM0074 and RSM0047 `Operator command: TIMEOUT NOW`. This is the default setting.
`REPEAT hhmm` | Specifies or replaces the interval at which a timeout check occurs.
`?` (or no specification) | Displays current timeout settings. The question mark (?) is optional and can be omitted.

## Resetting the Coupling Facility Structure

When a TP Monitor or server region which uses the Roll Server abends, the Roll Server might return an error. For example, the Roll Server directory might be reported as full because session cleanup had not been performed before the region abended. To resolve such an error, delete the respective Coupling Facility structure:

1. Shut down all Roll Servers which use the affected CF structure.

2. Issue the operator command `SETXCF FORCE,STR,STRNAME=structure-name`, where `structure-name` is the name of the CF structure used for the Roll Servers.

3. Restart all Roll Servers.

4. Format the Roll Files.

If, under normal operation, the Roll Files or the LRB become full due to the number of concurrently active users, restart the Roll server and specify larger Roll Files or a larger LRB.

You can also monitor the usage of Roll Files with the `SYSTP` utility.

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

- The number of direct writes.

  "Direct write" means that the Natural thread that was received was written to the roll file directly.

  There are two possible reasons:

  1. No LRB slot available. Increase the LRB.

  2. The compressed thread was larger than a single LRB slot. Increase the LRB slot size.

- The number of direct reads.

  "Direct read" means that the requested thread was no longer in the LRB and had to be read directly from the roll file.

  If the ratio of direct reads to the total number of reads is very high in a single z/OS system, the LRB is too small (increase it).

  If the ratio of direct reads to the total number of reads is very high in a z/OS Parallel Sysplex environment, this may also mean that there are many inter-system activities, which in turn means that a Natural session changes z/OS images quite frequently during its lifetime.

- The number of staging waits (in a single z/OS environment).

  A "staging wait" is a situation where a write request had to wait until the Staging Task had written the LRB slot to the roll file. If the ratio of staging waits to the total number of write requests is very high, this indicates that the high and low water marks are set inappropriately or that there is a bottleneck on the roll file device/roll file channel.

  Based on experience with stress tests, the following is recommended:

  If the ratio of maximal number of active users to number of LRB slots is very small, increase the high water mark. If not, decrease the high water mark.

  The difference between high water mark and low water mark should not be larger than three (30 percent).

  Ideally, if the number of LRB slots is definitely larger than the maximum number of concurrent users, the high water mark should be set to 10.

## Roll Server User Exits

The roll server has two user exits.

- `NATRSU14`

- `NATRSU24`

Sample source modules are delivered for these.

### NATRSU14 User Exit

Specifies the roll file number to be used.

Entry calling conventions:

- Register 1 addresses the parameter list that is described by the following `DSECT`:

      PLIST      DSECT
      PLRSVER    DS CL4    Roll server version  (= 'vrs')
      PLNRF      DS H      Number of roll files
      PLUID      DS CL16   Userid
      PLTSNUM1   DS H      Total number of slots  Roll file 1
      PLUSNUM1   DS H      Number of slots in use Roll file 1
      PLTSNUM2   DS H      Total number of slots Roll file 2
      PLUSNUM2   DS H      Number of slots in use Roll file 2
      PLTSNUM3   DS H      Total number of slots Roll file 3
      PLUSNUM3   DS H      Number of slots in use Roll file 3
      PLTSNUM4   DS H      Total number of slots Roll file 4
      PLUSNUM4   DS H      Number of slots in use Roll file 4
      PLTSNUM5   DS H      Total number of slots Roll file 5
      PLUSNUM5   DS H      Number of slots in use Roll file 5
      PLISTL EQU *-PLIST

  where vrs represents the relevant product version.

- Register 13 points to a 36-fullword save area.

- Register 14 contains the return address.

- Register 15 contains the entry address of `NATRSU14`.

Return calling convention:

- Register 15 contains the number of the roll file in binary format.

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:

- Register 1 points to an 8-byte area in which the group name must be generated.

- Register 13 points to an 18-fullword save area.

- Register 14 contains the return address.

- Register 15 contains the entry address of `NATRSU24`.

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.

### On this page

- Roll Server System Requirements
- Formatting the Roll File
- Starting the Roll Server
- Roll Server Messages, Condition Codes and Abend Codes
- Return Codes and Reason Codes of the Roll Server Request
- Operating the Roll Server
- Resetting the Coupling Facility Structure
- Roll Server Performance Tuning
- Roll Server User Exits