Administrative Functions

#### Search Results

Search

# Administrative Functions

Natural Monitor administrative functions are discussed in two sections:

- the User Profile System, which is used to generate profiles that define access rules for Natural Monitor users; and

- functions that pertain specifically to Natural Monitor.

This section covers the following topics:

- User Profile System

- Using NATURAL User Exits

- Using the Natural Monitor User Exit: Response Time Detail Record

- Accessing Historical Data in the NM Repository File

- Setting Configuration Parameter Values

## User Profile System

For an explanation of the effect of a great number of users on CICS SHARED storage requirements, see Storage Requirements in Installing Natural Review on z/OS.

The User Profile system provides a series of menus to help you generate profiles that define access rules for Natural Monitor users. You may create profiles for new users, change access rules for existing users, and purge user profiles that are no longer required.

Natural Monitor provides a default profile to allow access for users who do not have a profile defined for them. When a user logs on, Natural Monitor checks the Natural library `SYSRNM` for the user's profile. If one is not found, the default profile is used.

The default profile is also used as a basis for creating user profiles. When a profile for a new user is generated, the default profile is copied. The new profile may then be customized to suit the needs of the user.

Note
The default profile provides unrestricted access to Natural Monitor systems and functions. It is recommended that you first create a user profile for the system administrator and other privileged users; then modify the default profile so that it conforms to the needs of the majority of users.

- Accessing the User Profile System

- Customizing the Default Profile

- Creating a User Profile

- Using the List User Profiles Function

- Editing a User Profile

- Copying a User Profile

- Purging a User Profile

### Accessing the User Profile System

To access the User Profile System

- Enter the `UP` code on the command line of the Natural Monitor Main Menu and press ENTER.

The User Profile System menu appears as shown below:

    16:59:08                  *****   R E V I E W   *****                2006-03-02
                                    User Profile System

                        Code              Description

                         EU          Edit User Profile
                         LU          List User Profiles

      Command ===>
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help        Exit                                                  Menu

The following commands enable you to create and edit profiles, and display lists of existing profiles:

Command | Description
--- | ---
`EU` | Edits a profile for a new or existing user.
`LU` | Displays a list of existing user profiles, including the default profile.

From the list of existing user profiles, you can select a particular profile to be edited or purged.

### Customizing the Default Profile

You do not need to create a user profile for each user of Natural Review. By customizing the default profile so that the access rules meet the needs of the majority of Natural Monitor users, you eliminate the need for individual user profiles.

You can access the Edit User function to edit the default profile in two ways.

To access the Edit User screen

1. From any screen within Natural Review, type `UP EU DEFAULT` on the command line and press ENTER.

2. From any screen within the User Profile system, type `EU DEFAULT` on the command line and press ENTER.

The following Edit User screen is displayed:

    16:59:54                  *****   R E V I E W   *****                2006-03-02
                                         Edit User

                                  User Profile: DEFAULT_

      Please Mark Categories to Select

        General ................. _

        NATURAL MONITOR ......... _

      Command ===>
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help        Exit        Save  Accpt                               Menu

The `User Profile` field usually refers to the user ID corresponding to the profile; in this case it contains the word `DEFAULT`. The categories on the screen refer to types of access rules as described in the following table:

Category | Description
--- | ---
`General` | Access rules that affect all of the systems within Natural Review. Valid values are `Y`/`N`.
`NATURAL MONITOR` | Access rules pertaining to the Natural Monitor system. Valid values are `Y`/`N`.

For the user's default profile, you need to modify the general access rules in addition to those pertaining to Natural Monitor.

- Displaying General Access Rules
- Displaying the Natural Monitor Access Rules
- Modifying Access Rules

#### Displaying General Access Rules

When you select the general access rules, the General window appears as shown in the following screen:

                          General

                 Name: ____________________

          Access NATURAL MONITOR System ....... Y
          Access User Profile System .......... Y
          Default Menu ........................ MM
          Confirm Purge/Save Requests ......... Y

          PF3=Exit  PF6=Accept

The Name field may be used for the user's name or any other appropriate identifier.

The following table describes the general access rules that appear in the General window.

General Access Rule | Value | Description
--- | --- | ---
`Access NATURAL MONITOR System` | `Y` | The user may access the Natural Monitor system. This is the default value.
`N` | The user may not access the Natural Monitor system.
`Access User Profile System` | `Y` | The user may access the User Profile system. This is the default value.
`N` | The user may not access the User Profile system. Note Before setting this access rule to N in the default profile, you must first create a user profile that allows you to access the User Profile system. Otherwise, you will not be able to maintain user profiles.
`Default Menu` | Determines which menu screen appears on the user's terminal when the user logs on to Natural Review.
`MM` | Natural Monitor Main Menu This is the default value.
`NM` | Natural Monitor Main Menu
`UP` | User Profile System Main Menu
`Confirm Purge/Save Requests` | `Y` | Natural Monitor will prompt the user to confirm the request before the command is executed. This is the default value.
`N` | Natural Monitor will not prompt the user to confirm the request before the command is executed.

#### Displaying the Natural Monitor Access Rules

When the Natural Monitor category is selected, the NATURAL MONITOR window appears displaying access rules as shown below:

                       NATURAL MONITOR

         CANCEL/FORCE/TERMNAT/START/STOP Cmd .. Y
         Edit Report Definitions .............. Y
         Purge Historical Data ................ Y
         Purge Report Definitions ............. Y
         Purge Started Reports ................ Y
         Start Reports ........................ Y
         View Reports ......................... Y

         PF3=Exit  PF6=Accept

The following table describes the Natural Monitor access rules that appear in the NATURAL MONITOR window.

Natural Monitor Access Rule | Value/Description
--- | ---
`CANCEL/FORCE/TERMNAT/START/ STOP Cmd` |
`Y` | The user may issue a `CANCEL`, `FORCE`, `TERMNAT`, `START` or `STOP` command. This is the default value.
`N` | The user may not issue a `CANCEL`, `FORCE`, `TERMNAT`, `START` or `STOP` command.
`Edit Report Definitions` |
`Y` | The user may edit response time reports (`RT` function). This is the default value.
`N` | The user may not edit response time reports.
`Purge Historical Data` |
`Y` | The user may delete historical data. This is the default value.
`N` | The user may not delete historical data.
`Purge Report Definitions` |
`Y` | The user may delete response time report definitions. This is the default value.
`N` | The user may not delete response time report definitions.
`Purge Started Reports` |
`Y` | The user may delete the data accumulated by response time reports that have been started. This is the default value.
`N` | The user may not delete the data.
`Start Reports` |
`Y` | The user may initiate data accumulation by starting response time reports. This is the default value.
`N` | The user may not start response time reports.
`View Reports` |
`Y` | The user may view the results of started response time reports online. This is the default value.
`N` | The user may not review the results of started response time reports online.

#### Modifying Access Rules

You may modify access rules by typing over the settings displayed on the screen. When you have made all of the changes to a particular group of access rules, you have the following options:

- To exit without saving the changes, press PF3 or enter the `EXIT` command.

- To save the changes temporarily while you edit the next access rules screen, press PF6 or enter the `ACCPT` command.

- To save the changes to the Natural library, press PF5 or enter the `SAVE` command.

If you selected more than one category, pressing PF3 or PF6 displays the next access rules screen instead of returning you to the previous screen.

### Creating a User Profile

To create a user profile

1. From any screen within Natural Review, type the following string on the command line and press ENTER:

       UP EU userid

2. From any screen within the User Profile System, type the following string on the command line and press ENTER:

       EU userid

The User Profile System creates a profile for the user by copying the default profile. It then displays the user profile for editing, and the following message appears at the bottom of the screen:

    REV00101 - NEW USER PROFILE

If you wish to customize the user's profile, mark the appropriate categories by typing a character on the line following your selection:

- To change access to two Natural Monitor systems, mark the General category.

- If you wish to modify access to certain Natural Monitor system functions, mark the Natural Monitor category.

When the profile provides appropriate access privileges for the user, press PF5 to save the profile to the Natural library.

Refer to Customizing the Default Profile for information regarding access rules for the various categories.

### Using the List User Profiles Function

The List User Profiles (`LU`) function displays a list of user profiles that are stored in the Natural library `SYSRNM`.

To access the list of user profiles

- Enter the code `LU` on the command line of the User Profile System menu and press ENTER.

The User Profiles screen, similar to the one shown below, is displayed:

    11:15:14           *****   R E V I E W NM UTILITY  *****                2000-09-01
                                       User Profiles

        Sel  Userid    Name                     Sel  Userid    Name

      ! __   DEFAULT
      ! __   GGS

      Command ===>
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help        Exit                           +                      Menu

From this screen, you may edit or purge a particular user profile.

To access the Available Functions window that displays the available commands

- Enter a question mark (?) on the selection line preceding a profile name as shown below and press ENTER.

The Available Functions window, similar to the one shown below, is displayed:

        Available Functions

        EU  Edit User Profile
        PU  Purge User Profile
        .   EXIT

        __  Enter Function

### Editing a User Profile

To edit an existing user profile

- Enter the command `EU` on the selection line preceding the profile name.

The profile is displayed and can be edited. Refer to Customizing the Default Profile for additional information.

If you are editing your own user profile, the changes you make take effect as soon as you save your profile. If you are editing a profile other than your own, the changes do not take effect until the user next logs on to Natural Review.

You may also use this command to copy an existing profile to create a profile for a new user. If you have several users who require access privileges that are different from those specified in your default profile, you may use an existing profile as a model for the other profiles.

### Copying a User Profile

To copy a profile

1. Enter the command `EU` on the selection line preceding the profile name to be copied.

2. Type the new user ID on the line labeled `User Profile`.

3. Press PF5 to save the new user profile.

### Purging a User Profile

To delete a user profile

- Enter the command `PU` on the selection line preceding the profile name.

Depending on the setting in your profile, you may or may not be prompted for confirmation of the purge command as shown in the following screen:

    11:17:35         *****   R E V I E W  NM UTILITY *****                2000-09-01
                                       User Profiles

        Sel  Userid    Name                     Sel  Userid    Name

        __   DEFAULT
        PU   GGS

                                     +-------------------------------------+
                                     !                                     !
                                     ! Please confirm PURGE request for:   !
                                     !                                     !
                                     !              GGS                    !
                                     !                                     !
                                     !             (Y or N) Y              !
                                     !                                     !
                                     +-------------------------------------+

      Command ===>
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help        Exit                           +                      Menu

## Using NATURAL User Exits

Natural Monitor has two Natural user exits which are applicable to the Natural Monitor components:

- `P-UEXIT1`

- `P-UEXIT2`

These exits are located in `SYSRNM`, the Natural Monitor system library in Natural. They can be modified using the Natural editor.

- P-UEXIT1

- P-UEXIT2

### P-UEXIT1

This program is invoked when the online portion of Natural Monitor is entered. You may insert code into this program to satisfy site-specific needs.

Possible uses for this exit include:

- Setting colors on (`SET CONTROL 'T3279'`).

- Turning the PC mode on or off.

Note
This program must not alter the Natural stack, and it must end with a `STOP` command.

### P-UEXIT2

This program is invoked when the online portion of Natural Monitor is terminated. You may insert code in this program to alter the processing that occurs when terminating Natural Review.

Possible uses for this exit include:

- Terminating your Natural session.

- Logging on to another Natural application.

- Returning to a previous Natural application (using `SETUP/RETURN`).

## Using the Natural Monitor User Exit: Response Time Detail Record

Each time a transaction finishes (a terminal write is performed), Natural Monitor creates a record that contains information about the resources consumed by that transaction:

- the response time for the transaction;

- the number of database calls issued for the transaction;

- the total database elapsed time and command time for all calls issued; and

- information about the user who performed the transaction.

A user exit (`RNMRTUEX`) is provided with Natural Monitor to allow the user to handle this information as follows:

- examine the record;

- process the record; and

- accept or reject the record's inclusion into any active Natural Monitor response time reports.

The user can also write this record to a sequential data set or to SMF (System Management Facility) for later processing or as input to a chargeback system.

A sample `RNMRTUEX` user exit is supplied in the Natural Monitor source library. A copy book containing a `DSECT` mapping the detailed record is also provided.

This user exit can be modified to suit the needs of a user site and must be linked into the Natural nucleus with the rest of the Natural Monitor code in the step that links the Natural nucleus with Natural Monitor; see the corresponding step in Installing Natural Review on z/OS.

- Calling Conventions to Invoke the User Exit

### Calling Conventions to Invoke the User Exit

The following calling conventions are used to invoke the `RNMRTUEX` user exit:

- Register contents when entering the user exit:

  Register 1: Address of the parameter list

  Register 13: Address of an 18-fullword save area

  Register 14: Return address in the calling module

  Register 15: Entry address within `RNMRTUEX`

- Register contents returned by the user exit:

  Register 1: Address of the parameter list

  Registers 2 through 13: Must be unchanged.

- Content of parameters passed:

  Word 1: For record type 1: Response time report detail record

  Word 2: Address of the response time report detail record

- Return codes passed using Register 15:

  Zero(0): Process the record for all active response time reports

  Non-zero(0): Reject the record for response time report processing

## Accessing Historical Data in the NM Repository File

The Natural Review repository file contains Natural Monitor response time report definitions and historical data for response time reports that have a history interval. The historical data can be accessed by user-written applications and used as input for other processing (for example, trend analysis).

The view for this file is called `REVIEW-NM-FILE`.

The file can be read using the following key definition against the view field `NM-KEY`:

      1 REPORT-KEY                  (A50)
      1 REDEFINE REPORT-KEY
      2 REPORT-SUBSYSTEM            (A02)
      2 REPORT-DATE                 (N08)
      2 REPORT-TIME                 (N06)
      2 REPORT-NAME                 (A32)
      2 REPORT-SEQ                  (B02)

where:

Field | Description
--- | ---
`REPORT-SUBSYSTEM` | `RT` for the Response Time subsystem.
`REPORT-DATE` | Date (in `YYYYMMDD` format) that the historical data record was written.
`REPORT-TIME` | Time (in `HHMMSS` 24-hour format) that the historical data record was written.
`REPORT-NAME` | Response time report name for which the historical data record was written.
`REPORT-SEQ` | Record type for the historical data record. Record type 1 is used for response time interval data (corresponding to the `VW` or `VH` display in the Response Time subsystem). Record types 2 through n are used for response time detail records (corresponding to the `VD` display in the Response Time subsystem). The first detail record written for a given history interval will have a `REPORT-SEQ = 2`, and for each additional detail record written, the `REPORT-SEQ` field will increment by 1.

Two sample Natural programs are provided in the Natural Monitor library (`SYSRNM`) which read Response Time subsystem historical data. These two programs are called `HISTORY1` and `HISTORY2`.

`HISTORY1` is an example of how to read the response time interval history data (corresponding to the `VW` or `VH` command in the response time subsystem). For a specific response time report within a specified date and time range, `HISTORY1` reads all associated response time interval history records and performs some summary statistical evaluation.

`HISTORY2` is an example of how to read the response time detail history records (corresponding to the `VD` command in the response time subsystem). For a specific response time report within a specified date and time range, `HISTORY2` reads all associated response time detail history records and displays summary information of the 20 detail records had the highest response time.

In addition to the two sample Natural programs, a Natural local data area (LDA) called `L-NMHIST` is provided which incorporates fields from the Natural Monitor DDM. This LDA may be used by user-written programs to read the Natural Review repository file. See Local Data Area View Description for the contents of this LDA.

## Setting Configuration Parameter Values

For an explanation of the effect of many response time reports on CICS SHARED storage requirements, see Storage Requirements in Installing Natural Review on z/OS.

Within Natural Monitor, the Natural Monitor administrator modifies the configuration program for the following reasons:

- to control the generation of historical data for response time reports;

- to control the intervals used for collection; and

- to set other response time report parameters.

The administrator uses parameters in the program `P-NMCONF` in library `SYSRNM` to control historical data and other response time report options.

The `P-NMCONF` program contains default configuration values for new response time report definitions. Parameter values set in the distributed `P-NMCONF` program are normally not changed until the default values have been in use for a test period. `P-NMCONF` program parameter values generally depend on the site's workload, application use, and response time.

The `P-NMCONF` program is a Natural program called from Natural Monitor code to set defaults in the Natural Monitor global data area. It can be edited just as any Natural program can be edited.

To access and edit the P-NMCONF configuration program

1. Type `LOGON SYSRNM` at the Natural `NEXT` prompt and press ENTER.

2. Type `EDIT P-NMCONF` and press ENTER.

3. Modify the `P-NMCONF` program by typing over the existing values.

   Note
   `P-NMCONF` parameters and values are discussed in the following sections.

4. Type `STOW` and press ENTER to save and catalog the changes.

5. Type `MENU` at the prompt to return to Natural Review.

The changes you make to `P-NMCONF` take effect immediately.

- P-NMCONF Response Time Parameters

- P-NMCONF Report Parameter

- P-NMCONF Historical Data Parameters

### P-NMCONF Response Time Parameters

The `+RT-INTERVAL` and `+RT-THRESHOLD` parameters are used in conjunction with one another to control the color and monochrome attributes of response time reports.

Parameter | Description
--- | ---
`+RT-INTERVAL` | Specifies the reporting interval (in seconds) used to graph a report horizontally and vertically. Valid values are `0.1` to `99.9` (default is `0.5`).
`+RT-THRESHOLD` | Specifies the transaction response time value (in seconds) above which Natural Monitor creates detailed records for the Detailed Records table. Valid values are `0` to `99.9` (default is `3.5`).
`+RT-MAX-DETAIL-RECS` | Specifies the maximum number of detailed response time records to be retained. Valid values are `0` to `999` (default is `20`).
`+RT-WRAP-OPTION` |
Specifies the wrap option. Valid values are:
`NONE` | Detailed response time records are retained to the limit specified by the `RT-MAX-DETAIL-RECS` parameter. This is the default value.
`STD` | (standard) The most current response time records are retained.
`HIGH` | The response time records with the highest value are retained.
`+RT-TS-OPTION` |
Specifies the transaction summary option. Valid values are:
`NONE` | No transaction summary is created. This is the default value.
`SUM` | A transaction summary is created for the root transaction program; for example, `Nvrs` for Natural; where vr represents the relevant product version.
`DET` | A detailed transaction summary is created that includes Natural application information.

### P-NMCONF Report Parameter

Parameter | Description
--- | ---
`+RT-AUTOSTART` |
Specifies the autostart option. Valid values are:
`Y` | Report is autostarted by the Natural Monitor history task when it initializes. This is the default value.
`N` | Report is not autostarted.

### P-NMCONF Historical Data Parameters

Parameter | Description
--- | ---
`+RT-HISTORY-INTERVAL` | Specifies the interval (in minutes) at which response time historical data is written to the Natural Monitor repository. Valid values are `0` to `999` minutes (default is `0`). Note A value of zero (0) prevents historical data from being written.
`+RT-HISTORY-REFRESH` |
Specifies whether the response time report that has a history interval should be refreshed after the history interval has expired.
`Y` | The history report is refreshed. This is the default value.
`N` | The report is not refreshed.

### On this page

- User Profile System
- Using NATURAL User Exits
- Using the Natural Monitor User Exit: Response Time Detail Record
- Accessing Historical Data in the NM Repository File
- Setting Configuration Parameter Values