This section covers the following topics:
See also Natural Roll Server Functionality.
This section describes the Roll Server system requirements.
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.
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.
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.
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.
You can define a roll file either as a physical sequential (PS) data set or as a VSAM linear file.
To format a roll file
Allocate the roll file as a PS data set with a fixed record format.
Or:
Use the IDCAMS utility to define a VSAM linear file (see also
Example of an IDCAMS
Job).
Format the roll file by using the module
NATRSRFI
.
Note:
If you plan to use the roll file of a previous version, it
is sufficient to execute the NATRSRFI RESET
function.
During formatting, the PS data set is converted to a BDAM (basic direct access method) data set with a device-dependent block size. The block size of a VSAM file is equal to the control interval size defined by IDCAMS.
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.
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 following table:
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
CI size of the VSAM roll file
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.
The following is an example of an IDCAMS job used to define a VSAM roll file:
//FBDEFINE JOB (FB,117),FB,CLASS=K,MSGCLASS=X,NOTIFY=FB //IDCAMS EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=X //SYSIN DD * DELETE FB.VSAM.LINEAR DEFINE CLUSTER (NAME(FB.VSAM.LINEAR) - LINEAR - REUSE - CONTROLINTERVALSIZE(12388) - CYLINDERS(50,0) - SHAREOPTIONS(4 4)) - DATA (NAME(FB.VSAM.LINEAR.DATA)) /* //
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.
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. |
U0102 |
VSAM PUT failed. |
U0103 |
VSAM GET failed. |
Example 1:
//FBRUNRFI JOB (FB,218),FB,CLASS=K,MSGCLASS=X,NOTIFY=FB //FORMAT EXEC PGM=NATRSRFI //STEPLIB DD DISP=SHR,DSN=NATURAL.NAT85.LOAD //RF1 DD DISP=SHR,DSN=FB.SYSF.ROLLF1 //RF2 DD DISP=SHR,DSN=FB.VSAM.LINEAR //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: 2016/06/08 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 911. +FBRUNRFI: 3 Blocks unused. +FBRUNRFI: FORMAT,RF2,200000 +FBRUNRFI: RF2: FB.VSAM.LINEAR +FBRUNRFI: Creation date: 2016/06/08 Volume: FSMS04(VSAM) IEC070I 209-220,FBFORMAT,RUN1,ROLLF1,4A04,FSMS04,FB.VSAM.LINEAR, 277 IEC070I FB.VSAM.LINEAR.DATA,UCAT.USER1 +FBRUNRFI: 2835 Blocks written. Block size is 16384. +FBRUNRFI: 1 Directory block. +FBRUNRFI: 13 Blocks per slot. Slot size is 212992. +FBRUNRFI: 218 Slots initialized. Roll file version 911.
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.NAT85.LOAD //RF1 DD DISP=SHR,DSN=FB.SYSF.ROLLF1 //RFIPRINT DD SYSOUT=X
Resulting RFIPRINT
:
Natural Roll Server - Roll File Utility Version 851 FORMAT,RF1,200000 RF1: FB.SYSF.ROLLF1 Creation date: 2016/06/08 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 911. 3 Blocks unused.
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
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:
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: |
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 assigned for each roll file in use.
(The total number of LRB slots is calculated by this formula: |
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 |
|
Specifies the low water mark in steps of 10 percent of the number of LRB slots. |
high-water-mark
|
HIGHWATER |
0 - 10 |
|
Analogous to low-water-mark
parameter.
A value of |
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-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 the operator command |
message-case |
MSGCASE |
UCTRAN or blank
|
blank | Specify UCTRAN if the Roll Server is to issue all its messages
in upper case.
|
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: |
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: |
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 |
|
Specifies the low water mark in steps of 10 percent of the number of LRB slots. |
HIGHWATER
|
0 - 10 |
|
Analogous to low-water-mark
parameter.
A value of |
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 |
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 |
TIMEOUTREPEAT |
0 - 1440 |
none | The number of minutes between two consecutive timeout
checks.
The first timeout check after Roll Server start is run after
TIMEOUTCHECK is also specified, the first timeout
check is run at the time specified with TIMEOUTCHECK , and then
every TIMEOUTREPEAT minutes.
Specifying |
MSGCASE |
UPPER or MIXED |
mixed case | MSGCASE=UPPER causes all messages to be displayed in uppercase
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".
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 0
(which is the
default for Sysplex) resulting in every thread being written to the roll file. The
MEMLIMIT
option specifies 800 MB for the Local Roll Buffers.
// EXEC PGM=NATRSMvr //ROLLF1 DD DSN=SYSF.ROLLFILE //RSMPARM DD DSN=FB.SYSF.PARMS(RSMPARM1)
File FB.SYSF.PARMS(RSMPARM1)
:
Subsid=TST1 NumFiles=1 NumSlots=200 Lowwater=4 Highwater=6 *Structure=FBROLLS Comment: No Sysplex today NonActivity=2 Hours TimeoutRepeat=240 Minutes
The subsystem ID is TST1
, 1 roll file is used, the LRB has 200 slots. The
low water mark is set to 40 percent, the high water mark to 60 percent. Every 4 hours a
timeout check is run, killing all sessions that have been idle for at least 2 hours.
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.
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 Roll Server version.
The messages are explained in the section Roll Server Messages in the Messages and Codes documentation.
The following condition codes are used:
0
|
Normal completion |
12
|
Parameter error |
16
|
Runtime error |
20
|
Abend has occurred |
>100
|
Initialization error |
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
|
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.
The following commands can be passed to the Roll Server via the
MODIFY
operator command:
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:
Shut down all Roll Servers which use the affected CF structure.
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.
Restart all Roll Servers.
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.
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:
No LRB slot available. Increase the LRB.
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.
The roll server has two user exits.
Sample source modules are delivered for these.
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 (= '851') 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
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.
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.