Installing Natural Review

#### Search Results

Search

# Installing Natural Review

This document describes the steps for installing Natural Review (product code RNM) on z/OS.

- Prerequisites

- Storage Requirements

- Installation Medium

- Installation Procedure

- Installation Verification

#### Related Topic:

For information on the features and functions provided by Natural Review, see the Natural Review documentation.

#### Notation vrs or vr:

When used in this document, the notation `vrs` or `vr` represents the relevant product version (see also Version in the Glossary).

## Prerequisites

See General Prerequisites and System Support in the section Overview of the Installation Process.

## Storage Requirements

The Natural Review monitoring system requires CICS shared storage for collecting its monitoring data. For each Natural session, a user account area of 656 bytes is allocated plus space for a Natural call table (NCT). This table is used to track the Natural programs and database calls issued within a transaction. The number of NCT entries is determined by the `NCTSIZE` parameter in the source member `RNMSCB3.A` (see Step 7: Build the Natural Review System Control Block). Each table entry is 48 bytes long and the table contains 32 entries (default). This yields a total amount of 656+32*48=2192 bytes per running session. The storage is reused when the session terminates.

Each active response time report requires a basic control block that is 400 bytes long. Each detail record is 128 bytes long. The maximum number of detail records per report is controlled by the `Number of Records` in the report definition. If the `Transaction Summary` option is set in the report definition, a 64 bytes transaction summary area is allocated for each transaction ID.

After a report has been written to the Natural Review repository file by the history session, all report-depending storage is released.

## Installation Medium

The installation medium contains the following data sets required for product installation:

Data Set Name | Contents
--- | ---
`RNMvrs.LOAD` | Load modules
`RNMvrs.SRCE` | Source modules and macros
`RNMvrs.SYSF` | Natural system file definition
`RNMvrs.JOBS` | Sample installation jobs
`RNMvrs.INPL` | Natural objects

Copy the data sets into your environment as described in Copying Data Sets to a z/OS Disk in the section Installing Natural.

## Installation Procedure

Be sure to read Installation Process and Major Natural Features before you start the installation procedure.

- Step 1: Add CICS Control Table Entries for Natural Review

- Step 2: Load the Natural Review Repository File

- Step 3: Migrate an existing Natural Review Repository File

- Step 4: Build the Natural Parameter Module

- Step 5: Link the Nucleus

- Step 6: Load New Natural Objects

- Step 7: Define the SYSRNM Library in Natural Security

- Step 8: Build the Natural Review System Control Block

- Step 9: Link the Natural Review History Session Startup Module

- Step 10: Activate the Natural Review Modules

- Step 11: Initialize the Natural Review Repository File

### Step 1: Add CICS Control Table Entries for Natural Review

(Job I005, Step 2211)

Define the following CICS table entries with RDO. You may have to include additional parameters according to your requirements. Natural Review supports transaction isolation (that is, it can run in user key).

- Program Control Table (PCT)
- Processing Program Table (PPT)
- Program List Tables CICS Startup and Shutdown (PLTPI and PLTSD)

#### Program Control Table (PCT)

1. Define the Natural Review history session start/stop transaction:

       CEDA DEFINE TRANSACTION(RVH1) PROGRAM(RNMHIST3)
            GROUP(RNMvr)

2. Define the Natural Review asynchronous Natural history session transaction:

       CEDA COPY TRANSACTION(xxxx) GROUP(yyyy) AS(RVH2)
            TO(RNMvr)

   This copies your existing Natural transaction ID `xxxx` from your Natural definition group `yyyy` as an alias transaction for Natural Review. This definition is optional and you may use the online Natural transaction code `xxxx` as well, but it helps the administrator identify the Natural Review asynchronous history session.

   The transaction codes `RVH1` and `RVH2` can be chosen freely (that is, you may change them if required). The Natural session transaction code must be the same as defined with the parameter `NATTRAN` (in this example, `NATTRAN=RVH2`). See Step 7: Build the Natural Review System Control Block and Installation Verification (Step 3).

#### Processing Program Table (PPT)

1. Define the Natural Review history session start/stop program:

       CEDA DEFINE PROGRAM(RNMHIST3) LANGUAGE(ASSEMBLER)
            GROUP(RNMvr)

2. Define the Natural Review system control block:

       CEDA DEFINE PROGRAM(RNMSCB3) LANGUAGE(ASSEMBLER)
            RESIDENT(YES) GROUP(RNMvr)

3. After entering the online definitions, activate them by using `CEDA INSTALL GROUP(RNMvr)`. The new `GROUP` should be added to the `GRPLIST` defined for CICS cold start.

#### Program List Tables CICS Startup and Shutdown (PLTPI and PLTSD)

This table entry is optional. You can use it for automatic start and termination of the Natural Review history session during CICS startup and shutdown.

1. Define the Natural Review history session start/stop program:

       DFHPLT TYPE=ENTRY,PROGRAM=RNMHIST3

2. Insert the table entry in your assembled PLTPI and/or PLTSD CICS table. This avoids manual starting and stopping of the Natural Review history session (see Step 7: Build the Natural Review System Control Block).

### Step 2: Load the Natural Review Repository File

(Job I050, Step 2620)

You can skip this step if you have already installed a Natural Review repository file.

The repository file is an Adabas file used for storing response time reports and history data. It is possible to share the repository file across several CICS regions. Any Adabas file can be used to contain the Natural Review repository file. The corresponding file number must be defined to Natural as a logical system file (see Step 4: Build the Natural Parameter Module). The repository file has to be initialized via Natural (see Step 11: Initialize the Natural Review Repository File).

- Modify the job as follows before submitting it:

  - Change the data set definitions according to your requirements.

  - Change `DB=dbid` in the Adabas `ADARUN` statements to the correct database ID.

  - Change `SVC=nnn` to the correct Adabas SVC number.

  - Change the Adabas `ADALOD` statement to the file number `fnr` of the Adabas file that will contain the Natural Review repository file, and the Natural Review version `vrs` you are running:

        ADALOD LOAD FILE=fnr,NAME='REPOS-RNMvrs'

### Step 3: Migrate an existing Natural Review Repository File

(Job I050, Step 2620)

You can skip this step if you have installed a Natural Review repository file with Step 2 above.

If you migrate from an older Natural Review repository file lower than Natural Version 9.2, then a migration step needs to be performed.

Alternatively, execute an ADADBS Job containing the following cards:

    //DDKARTE   DD   *
    ADADBS OPERCOM  STOPF=fnr,PURGE
    ADADBS NEWFIELD FILE=fnr
    ADADBS NEWFIELD FNDEF='01,DY,8,A,NU'

where you replace fnr with the file number of your Natural Review repository file.

### Step 4: Build the Natural Parameter Module

(Job I060, Steps 0010, 0015)

1. Modify the settings of the parameters supplied with the Natural parameter module as follows:

       RDCSIZE=2
       MADIO=5000
       MAXCL=0
       RCA=NATGWREV
       NTLFILE 180,dbid,fnr

   where:

   `RDCSIZE` is the Natural profile parameter that determines whether a session is monitored by Natural Review. If you set `RDCSIZE=0` (this is the default) for a session, it is not monitored by Natural Review.

   `RCA` is the Natural profile parameter required if you want to link the Natural Review monitor interface module separate from the nucleus (see Step 7: Build the Natural Review System Control Block) by means of the RCA technique.

   `NTLFILE` (or dynamic `LFILE` parameter) is the macro that determines the Natural Review repository file used by the `SYSRNM` application for retrieving and maintaining report definitions and storing history report data for the history session. The currently accessed repository file can be changed using the `LFILE` command within Natural Review (see the Natural Review documentation).

   `dbid` is the database ID and `fnr` the file number specified in Step 2: Load the Natural Review Repository File.

   For details about the parameters mentioned above, see the Parameter Reference documentation.

2. Assemble and link the Natural parameter module.

### Step 5: Link the Nucleus

(Job I060, Step 0020)

- Link the nucleus for Natural Review by including the following module from the Natural Review load library `RNMLIB`:

       INCLUDE RNMLIB(RNMNUC3)

  Natural Review uses the Natural Data Collector exit interface to get data from Natural. For more information on the `SYSRDC` Data Collector, see the Natural `SYSRDC` utility described in the Utilities documentation.

  The Natural Review module `RNMNUC3` supports all different ways of statically linked Natural subprograms. For more information about linking the nucleus, see Linking Natural Objects to the Natural Nucleus in the Natural Operations documentation.

  If you run an environment-independent nucleus for multiple environments (for example, CICS and batch), link `RNMNUC3` to the environment-dependent nucleus, because Natural Review monitoring runs under CICS only. This prevents unnecessary overload in your non-CICS systems.

- If `RNMNUC3` is not linked to the environment-dependent nucleus, the following CICS assembler command level stub from the CICS load library must be linked to `RNMNUC3`:

       INCLUDE CICSLIB(DFHEAI)

- Instead of linking `RNMNUC3` to the nucleus, you can link it as a separate module defined with the Natural profile parameter `RCA` (described in the Parameter Reference documentation). The following linkage editor statements are then required:

       MODE RMODE(ANY)
       INCLUDE CICSLIB(DFHEAI)
       INCLUDE RNMLIB(RNMNUC3)
       ENTRY NATGWREV
       NAME NATGWREV

  The `MODE` statement is optional. A CICS PPT entry is required for the module `NATGWREV`. It must be specified with the profile parameter `RCA` (see Step 3: Build the Natural Parameter Module). The module can be shared between multiple Natural nuclei.

### Step 6: Load New Natural Objects

(Job I061, Step 2661)

1. If you want to continue using a profile text object `DEFAULT` you modified according to your requirements, rename your `DEFAULT` object in the `SYSRNM` library before you start loading the new Natural objects.

2. Load the Natural objects specific to Natural Review from the `RNMvrs.INPL` data set into your `FNAT` system file by using the Natural INPL utility.

   It is sufficient to load the Natural objects only into one `FNAT` system file even if you want to monitor other `FNAT` system files as well.

   The Natural Review User Profile Subsystem is initialized when the profile text object `DEFAULT` is copied to the `SYSRNM` library.

3. If you renamed the profile text object `DEFAULT` in the first step, replace the newly loaded `DEFAULT` by this object.

### Step 7: Define the SYSRNM Library in Natural Security

This step only applies if Natural Security is installed.

- Define the Natural Review library `SYSRNM` in Natural Security.

  You can define a startup menu for the `SYSRNM` library. If the library is `People-protected`, each user of this library must be linked to it.

- Define `REVHIST` as a user of type `PERSON` with a default application of `SYSRNM`. `REVHIST` is used as the user ID by the Natural Review history session.

### Step 8: Build the Natural Review System Control Block

(Job I070, Steps 2622, 2623)

The Natural Review System Control Block `RNMSCB3` is defined as a program in CICS. `RNMSCB3` is not an executable program. Its storage is used by Natural Review as the common anchor and control point for all monitored Natural sessions and reports within one CICS address space. There are some installation-specific generation parameters you can specify in object `RNMSCB3` in the Natural Review source library.

- Set the following parameters in `RNMSCB3` according to your requirements:

  Parameter | Explanation
  --- | ---
  `NATTRAN=` | This is the Natural/CICS transaction code for the Natural Review history session. You must specify this parameter to set the correct Natural transaction code (see Step 1: Add CICS Control Table Entries for Natural Review).
  `NPARMS=` | Additional dynamic Natural parameters for the Natural Review history session. This parameter is optional.
  `CLOSE=` |
  This parameter determines whether any started Natural Review reports are closed automatically during the termination of the Natural Review history session. There are two possible values:
  `CLOSE=YES` | All started reports are closed. This is the default setting.
  `CLOSE=NO` | Started reports are not closed.
  `DATE=` |
  The date format used in the records stored in the Natural Review repository file. There are two possible values:
  `DATE=OLD` | The date format is `YY/MM/DD`. This is the default setting.
  `DATE=NEW` | The date format is `YYYYMMDD`.
  `EMPTY=` |
  This parameter determines whether empty history records are stored in the Natural Review repository file. A record is considered empty if no transactions occurred within the report time interval. There are two possible values:
  `EMPTY=YES` | Empty history records are stored.
  `EMPTY=NO` | Empty history records are not stored. This is the default setting.
  `NCTSIZE=` | This parameter determines the number of entries in the Natural Call Table (NCT) of Natural Review. The NCT is allocated in CICS shared storage and is used to track the usage of the Natural programs per session. Possible values: `0` - `128`. The default setting is `NCTSIZE=32`.

- Modify and run the job `RNMI070` to generate the Natural Review System Control Block. The module must be linked with the `NORENT` option. The target link library can be any library defined to CICS.

### Step 9: Link the Natural Review History Session Startup Module

(Job I070, Step 2625)

Natural Review history data is written to the Natural Review repository file by an asynchronous (that is, not terminal-bound) Natural session.

- Modify and run job `RNMLINK` in the Natural Review source library.

  It links the CICS-dependant history session startup module `RNMHIST3`. The target link library can be any library defined to CICS.

  There can be only one history session within one CICS address space. The Natural objects specific to Natural Review (see Step 5: Load New Natural Objects) must be loaded to the `FNAT` system file running with the history session.

### Step 10: Activate the Natural Review Modules

- Use the following `CEMT` transaction to activate the nucleus module to which `RNMNUC3` and the modified the Natural parameter module are linked:

      CEMT SET PROGRAM(. . . .) NEWCOPY

- Restart CICS if you cannot activate the nucleus module.

### Step 11: Initialize the Natural Review Repository File

Skip this step if your Natural Review repository file is already initialized.

- Initialize the repository file after loading it in Step 2: Load the Natural Review Repository File:

  Logon to the `SYSRNM` library and enter the following at the `NEXT` prompt:

      INSTALL NM

  The following messages will then appear:

      Now creating sample report system response time
      Now creating sample report highest response
      Natural Review repository initialization complete.
      Press <ENTER> to continue

  During the initialization process, two default (`sample`) response time reports are added as shown above.

## Installation Verification

You can verify the successful installation of Natural Review by performing the following steps:

1. At any Natural command prompt, enter the following:

       SYSRNM

   Natural Review is started and a Natural Review logo screen similar to the example below appears:

       17:30:01                 ***** REVIEW NM UTILITY *****               date

                  RRRRRRRR    EEEEEEE   VVV    VVV   III   EEEEEEE  WWW         WWW
                 RRRRRRRRR   EEEEEEE   VVV    VVV   III   EEEEEEE  WWW         WWW
                RRR   RRR   EEE       VVV    VVV   III   EEE      WWW         WWW
               RRR   RRR   EEE       VVV    VVV   III   EEE      WWW         WWW
              RRRRRRRR    EEEEEE    VVV    VVV   III   EEEEEE   WWW    W    WWW
             RRRRRRRR    EEEEEE    VVV    VVV   III   EEEEEE   WWW    WW   WWW
            RRR   RRR   EEE       VVV    VVV   III   EEE      WWW   WWWW  WWW
           RRR   RRR   EEE        VVV  VVV    III   EEE       WWW WWWWWW WWW
          RRR   RRR   EEEEEEE     VVVVVV     III   EEEEEEE    WWWWW   WWWWW
         RRR   RRR   EEEEEEE      VVVV      III   EEEEEEE     WWW     WWW

                          N A T U R A L    M O N I T O R

                     A    P R O D U C T    O F    S O F T W A R E    A G

   (You can suppress this screen by specifying `BANNER=N` in the text object `CONFIG` in the library `SYSRNM`.)

2. Press ENTER to invoke the Natural Review Main Menu screen:

       17:30:17                 ***** REVIEW NM UTILITY *****               date
                                         - Main Menu -

                             Code  Function

                              NM   Natural Monitor System
                              UP   User Profile System

        Command ===>

        REV00001 - Welcome to Review NM running under CICS

        Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
              Help        Exit                                                  Fin

   Alternatively, you can invoke this menu by logging on to the Natural library `SYSRNM` and then entering the following command:

       MENU

3. In the command line of the Natural Review Main Menu screen, enter either of the following commands:

       NM

   (for Natural Monitor System)

   or

       UP

   (for User Profile System)

   Depending on the command entered, the main screen of the requested subsystem appears. You can then check your installation parameters and the status of the history session. For detailed information on the functions provided by the subsystems, see the Natural Review documentation.

4. If you want to run history reports, start the history session. It runs as an asynchronous (non-terminal) Natural session and writes the collected report data to the repository file each time a report time interval has expired.

   You can start and stop the history session either automatically by using the CICS PLTPI/PLTSD (see Step 1: Add CICS Control Table Entries for Natural Review), or manually outside Natural by using the `RVH1` transaction (see Step 1: Add CICS Control Table Entries for Natural Review) in the following ways:

   `RVH1` | Start the Natural Review history session with the transaction code `RVH2` as defined with `NATTRAN` in Step 8: Build the Natural Review System Control Block. The history session can also be started with the `START` command of Natural Review (see the Natural Review documentation).
   `RVH1 STOP` | Terminate the Natural Review history session. The history session can also be terminated with the `STOP` command of Natural Review (Natural Review documentation).
   `RVH1 TEST` | Start the Natural Review history session on the current terminal. This option can be used for debugging purposes, for example, to debug the history session with CEDF (the CICS debugging facility). Note that no Natural terminal I/Os are supported during the normal processing of the history session. Therefore, you have to terminate the history session from another terminal.

5. Check the Natural Review initialization messages on the console log of your CICS system to find out whether the history session has started successfully. The following message should appear: `REV20200 - REVIEW NM HISTORY SESSION STARTED`.

   For more detailed explanations of the messages in Natural Review, enter `MSG` followed by the message number (for example, `MSG 1`) in the command line of Natural Review.

### On this page

- Prerequisites
- Storage Requirements
- Installation Medium
- Installation Procedure
- Installation Verification