Version 4.2.6 for Mainframes
 —  Natural Review  —

Installing Natural Review

This section describes step by step how to install Natural Review under the operating systems z/OS and z/VSE using Adabas system files. It covers the following topics:

Notation vrs or vr: If used in the following document, the notation vrs or vr stands for the relevant version, release, system maintenance level numbers. For further information on product versions, see Version in the Glossary.


General Installation Information

Installation Jobs

The installation of Software AG products is performed by installation jobs. These jobs are either created "manually" or generated by System Maintenance Aid (SMA).

For each step of the installation procedures described below, the job number of a job performing the respective task is indicated. This job number refers to an installation job generated by SMA. If you are not using SMA, an example installation job is provided in the job library on the Natural Monitor installation tape; you must adapt this job to your requirements.

Using System Maintenance Aid

For information on using Software AG's System Maintenance Aid (SMA) for the installation process, refer to the System Maintenance Aid documentation.

Prerequisites

The current version of Natural for Mainframes must be installed.

Further product/version dependencies are specified under Natural and Other Software AG Products and Operating/Teleprocessing Systems Required in the current Natural Release Notes for Mainframes.

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 source member RNMSCB3 (see Step 8: Modify, Assemble and Link 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 repository file by the history session, all report-depending storage is released.

Top of page

Installation Tape - z/OS

The installation tape contains the datasets listed in the table below. The sequence of the datasets is shown in the Report of Tape Creation which accompanies the installation tape.

Dataset Name Contents
RNMvrs.JOBS Natural Review example installation jobs
RNMvrs.LDEL Instructions to delete Natural Review system objects of Version 4.1
RNMvrs.INPL Natural Review system objects
RNMvrs.LOAD Natural Review load modules
RNMvrs.SRCE Natural Review source programs and macros
RNMvrs.SYSF Natural Review data file (Adabas)

Copying the Tape Contents to a z/OS Disk

If you are using SMA, refer to the System Maintenance Aid documentation (included in the current edition of the Natural documentation CD).

If you are not using SMA, follow the instructions below.

This section explains how to:

The JCL in this dataset is then used to copy all datasets from tape to disk.

If the datasets for more than one product are delivered on the tape, the dataset COPY.JOB contains the JCL to unload the datasets for all delivered products from the tape to your disk.

After that, you will have to perform the individual install procedure for each component.

Step 1 - Copy Dataset COPY.JOB from Tape to Disk

The dataset COPY.JOB (Label 2) contains the JCL to unload all other existing datasets from tape to disk. To unload COPY.JOB, use the following sample JCL:

//SAGTAPE JOB SAG,CLASS=1,MSGCLASS=X
//* ---------------------------------
//COPY EXEC PGM=IEBGENER
//SYSUT1 DD DSN=COPY.JOB,
// DISP=(OLD,PASS),
// UNIT=(CASS,,DEFER),
// VOL=(,RETAIN,SER=tape-volume),
// LABEL=(2,SL)
//SYSUT2 DD DSN=hilev.COPY.JOB,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,VOL=SER=volume,
// SPACE=(TRK,(1,1),RLSE),
// DCB=*.SYSUT1
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
// 

where:

hilev is a valid high level qualifier
tape-volume is the tape volume name, for example: T12345
volume is the disk volume name

Step 2 - Modify COPY.JOB on Your Disk

Modify the COPY.JOB on your disk to conform to your local naming conventions and set the disk space parameters before submitting this job:

Step 3 - Submit COPY.JOB

Submit COPY.JOB to unload all other datasets from the tape to your disk.

Top of page

Installation Tape - z/VSE

The installation tape contains the datasets listed in the table below. The sequence of the datasets is shown in the Report of Tape Creation which accompanies the installation tape.

Dataset Name Contents
RNMvrs.LIBR Natural Review installation sublibrary
RNMvrs.LDEL Instructions to delete Natural Review system objects of Version 4.1
RNMvrs.INPL Natural Review system objects
RNMvrs.SYSF Natural Review data file (Adabas)

The following sublibrary member types are used:

.A Assembler source code, examples etc.
.E Edited macros
.J Installation jobs
.OBJ Object modules

Copying the Tape Contents to a z/VSE Disk

If you are using SMA, refer to the System Maintenance Aid documentation (included in the current edition of the Natural documentation CD).

If you are not using SMA, follow the instructions below.

This section explains how to:

The JCL in this member is then used to copy all datasets from tape to disk.

If the datasets for more than one product are delivered on the tape, the member COPYTAPE.JOB contains the JCL to unload the datasets for all delivered products from the tape to your disk, except the datasets that you can directly install from tape, for example, Natural INPL objects.

After that, you will have to perform the individual install procedure for each component.

Step 1 - Copy Dataset COPYTAPE.JOB from Tape to Disk

The dataset COPYTAPE.JOB contains the JCL to unload all other existing datasets from tape to disk. To unload COPYTAPE.JOB, use the following sample JCL:

* $$ JOB JNM=LIBRCAT,CLASS=0,                                          + 
* $$ DISP=D,LDEST=(*,UID),SYSID=1                                       
* $$ LST CLASS=A,DISP=D                                                  
// JOB LIBRCAT                                                           
* *****************************************                              
*     CATALOG COPYTAPE.JOB TO LIBRARY                                    
* *****************************************                              
// ASSGN SYS004,nnn                                <------  tape address 
// MTC REW,SYS004                                                        
// MTC FSF,SYS004,4                                                      
ASSGN SYSIPT,SYS004                                                      
// TLBL IJSYSIN,'COPYTAPE.JOB'                                           
// EXEC LIBR,PARM='MSHP; ACC S=lib.sublib'         <------- for catalog
/*
// MTC REW,SYS004                                                                       
ASSGN SYSIPT,FEC                                                         
/*                                                                       
/&                                                                     
* $$ EOJ                                                                 

where:

nnn is the tape address
lib.sublib is the library and sublibrary of the catalog

Step 2 - Modify COPYTAPE.JOB

Modify COPYTAPE.JOB to conform to your local naming conventions and set the disk space parameters before submitting this job.

Step 3 - Submit COPYTAPE.JOB

Submit COPYTAPE.JOB to unload all other datasets from the tape to your disk.

Top of page

Installation Procedure

This section describes the actual installation steps after restoring the installation tape.

Step 1: Add CICS Control Table Entries for Natural Review

(Job I005, Step 2211)

Define the following CICS table entries with RDO. If you still have assembled CICS tables, you find sample table entries in member RNMTBLS in the Natural Review source library. You may have to include additional parameters due to your site requirements (that is, security keys, etc.). For CICS Version 3 or higher, Review supports transaction isolation (that is, it can run in user key).

Program Control Table (PCT):

Define the Natural Review history session start/stop transaction:

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

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 to identify the Natural Review asynchronous history session.

The transaction codes RVH1 and RVH2 can be chosen freely (that is, you may change them if desired). The Natural session transaction code must be the same as defined with parameter NATTRAN (in this example NATTRAN=RVH2) in Step 14: Start the Natural Review History Session.

Processing Program Table (PPT):

Define the Natural Review history session start/stop program:

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

Define the Natural Review system control block:

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

After entering the online definitions, activate them 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):

Define the Natural Review history session start/stop program:

DFHPLT TYPE=ENTRY,PROGRAM=RNMHIST3

This table entry is optional. You may use it for automatic start and termination of the Natural Review history session during CICS startup and shutdown. 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 8: Modify, Assemble and Link the Natural Review System Control Block).

Step 2: Load the Natural Review Repository File

(Job I050, Step 2620)

The Natural Review repository file is an Adabas file used for storing response time reports and history data. The format of the Natural Review repository file is compatible with previous versions. If you have already installed a repository file, you may continue to use it and omit this step.

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 3: Modify, Assemble and Link the Natural Parameter Module). The repository file has to be initialized via Natural (see Step 12: Initialize the Natural Review Repository File).

Load the Natural Review repository file using SMA or the job RNMLOAD provided in the Natural Review source library. Modify this job as follows before submitting it:

Step 3: Modify, Assemble and Link the Natural Parameter Module

(Job I060, Steps 0010, 0015)

You can monitor Natural sessions with Natural Review. Include the following parameter settings in the Natural parameter module(s):

NTPRM ...
RDCSIZE=2
MADIO=5000
MAXCL=0
NTLFILE 180,NNN,NNN

The parameter RDCSIZE determines whether a session is monitored by Natural Review.

Note:
If you set RDCSIZE=0 (this is the default) for a session, it is not monitored by Natural Review.

The NTLFILE macro (or dynamic LFILE parameter) definition determines the repository file being used by the SYSRNM application for retrieving and maintaining report definitions and history report data. For the history session, it determines the repository file in which the history report data is stored. The DBID=NNN and FNR=NNN subparameters must be set to the correct values for the Natural Review repository file (see Step 2: Load the Natural Review Repository File). The currently accessed repository file can be changed using the LFILE command within the SYSRNM application.

If you want to link the Natural Review monitor interface module separate from the Natural nucleus (see Step 8: Modify, Assemble and Link the Natural Review System Control Block) by means of the RCA technique, the following parameter is required:

RCA=NATGWREV

Step 4: Link the Natural Nucleus with Natural Review

(Job I060, Step 0020)

Relink all your Natural nuclei you want to monitor with Natural Review, 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 about the SYSRDC Data Collector, see SYSRDC Utility in the Natural Utilities documentation.

The Natural Review nucleus RNMNUC3 supports all different ways of statically linked Natural subprograms. For more information about linking the Natural nucleus, see Linking Natural Objects to the Natural Nucleus in the Natural Operations documentation. If you run a shared Natural nucleus for multiple environments (for example, CICS, batch, etc.), you should link RNMNUC3 to the environment-dependant Natural CICS 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 Natural CICS 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 Natural nucleus, you can link it as a separate module defined with profile parameter RCA. 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 module NATGWREV. It must be specified with the RCA parameter (see Step 3: Modify, Assemble and Link the Natural Parameter Module). The module can be shared between multiple Natural nuclei of different Natural versions.

Step 5: Delete Natural Review Objects

(Job I061, Step 0026)

This step is optional but recommended to avoid data inconsistencies.

If you are using a Version 4.1 Natural FNAT system file, delete obsolete Version 4.1 Natural Review objects by loading the RNMvrs.LDEL data set with the Natural INPL utility.

See also the corresponding step Delete Natural System Objects in the Installation documentation:

Installation Procedure for Natural under z/OS
Installation Procedure for Natural under z/VSE

Step 6: INPL Natural Review Objects

(Job I061, Step 2661)

Natural Review now runs in the new library SYSRNM, without Review DB or DC.

Load the Natural Review objects (SYSRNM application) into your Natural system file (FNAT) from where you want to use the SYSRNM application. It is not required to use the INPL utility to load Natural Review on all system files you want to monitor. You may use any of your site-dependent Natural INPL JCL to accomplish this or use the sample job RNMINPL provided in the Natural Review source library.

Step 7: Natural Security Definitions - if installed

If you want to run Natural Review under Natural Security (NSC), the Natural Review library SYSRNM must be defined in Natural Security. The SYSREV and SYSREVNM libraries from previous versions are no longer used.

SYSRNM can have a startup menu. If the library is defined as private (that is, with NSC parameter PEOPLE=Y), each user of this library must be linked to it.

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

Step 8: Modify, Assemble and Link 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 member RNMSCB3 in the Natural Review source library.

The following parameters can be specified in RNMSCB3:

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.

CLOSE=NO: Started reports are not closed.

The default setting is CLOSE=YES. In previous versions of Natural Review, started reports were not closed during termination of the history session.

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
DATE=NEW The date format is YYYYMMDD

The default value is DATE=OLD. This is the format that previous releases of Natural Review have used. If you have any existing user-written reporting programs extracting the repository file, you may have to change them if you want to use DATE=NEW.

EMPTY=
This parameter determines whether empty history records are stored in the Natural Review repository file. A record is considered as "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.

The default setting is EMPTY=NO. In previous versions of Natural Review, empty records were stored.

NCTSIZE= This parameter determines the number of entries in the Natural Call Table (NCT) of 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 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 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.

Within one CICS address space there can be only one history session. The Natural Review application (see Step 6: INPL Natural Review Objects) must be loaded to the FNAT system file running with the history session.

Step 10: Activate the Natural Review Modules

If you have assembled CICS tables or if you cannot copy the Natural nucleus module(s) with RNMNUC3 and NATPARM linked, you have to restart CICS. Otherwise, just copy the linked Natural nucleus module(s), to which RNMNUC3 and the modified NATPARM are linked, by means of transaction CEMT:

CEMT SET PROGRAM(. . . .) NEWCOPY

Step 11: Initialize the Review User Profile Subsystem

The User Profile Subsystem is no longer shared between the three Review products (DB, DC and NM).

This step is no longer required, since the profile text member DEFAULT will be delivered with the Natural INPL and will be copied to SYSRNM.

If you have a previous version of Natural Review installed and you want to keep the user profiles, use online SYSMAIN to copy the profile text members from SYSREVUS to SYSRNM.

Nevertheless, you can re-initialize the User Profile Subsystem. Logon to library SYSRNM and enter the following on the NEXT prompt:

INSTALL UP

The following message will then appear:

Default user Profile installed

Step 12: Initialize the Natural Review Repository File

After loading the Natural Review repository file (see Step 2: Load the Natural Review Repository File), you must initialize it. If your repository file is already initialized, skip this step.

During the initialization process, two default response time reports are added. To initialize the Natural Review repository file, logon to library SYSRNM and enter the following on 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

Step 13: Start the Natural Review Application

Each time you want to start the Natural Review application, logon to library SYSRNM and enter the following:

MENU

or enter SYSRNM anywhere at the NEXT prompt.

Either the Natural Review logo screen (see below) or the Natural Review Main Menu screen appears.

09:19:19                 ***** REVIEW NM UTILITY *****               2008-02-20
                                                                               
                                                                               
                                                                               
           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    v.r.s            
                                                                               
                                                                               
                                                                               
                                                                               
              A    P R O D U C T    O F    S O F T W A R E    A G              
                                                                               
                                                                               

Note:
v.r.s stands for version, release, system maintenance level of the current Natural Review version.

If the Natural Review logo screen is shown, press Enter to invoke the Natural Review Main Menu screen. The Natural Review logo screen can be suppressed by specifying BANNER=N in the text member CONFIG in library SYSRNM.

When the Natural Review Main Menu screen is shown, you can enter the Natural Review subsystem IDs NM (Natural Monitor) or UP (User Profiles). The main screen for the desired subsystem is then shown.

For installation verification, enter NM and then the TE command. You can then check your installation parameters and the status of the history session.

Step 14: Start the Natural Review History Session

If you want to run history reports, the history session must be started. 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 using the CICS PLTPI/PLTSD (see Step 1: Add CICS Control Table Entries for Natural Review) or manually.

For manual starting and stopping of the history session, the RVH1 transaction (see Step 1: Add CICS Control Table Entries for Natural Review) can be used in the following ways:

RVH1 Start the Natural Review history session.

The history session can also be started with the START command of Natural Review.

RVH1 STOP Terminate the Natural Review history session.

The history session can also be terminated with the STOP command on the TE HC screen or with the TERMNAT command on the SA screen of Natural Review.

RVH1 TEST Start the Natural Review history session on the current terminal.

This option may be used for debugging purposes, e.g. 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.

After starting the history session, the following message should appear:

REV20200 - REVIEW NM HISTORY SESSION STARTED

Check the Natural Review initialization messages on the console log of your CICS system to find out whether the history session has started successfully. Any error messages from the history session are displayed on the operator console log.

If desired, you can get a more detailed explanation of the messages in Natural Review. Just enter MSG followed by the message number on the command line of Natural Review.

Top of page