Installing Natural for VSAM on VSAM System Files on z/OS

#### Search Results

Search

# Installing Natural for VSAM on VSAM System Files on z/OS

This document describes the steps for installing Natural for VSAM in a VSAM file system on z/OS.

The Natural system files `FNAT`, `FUSER`, `FDIC`, `FSEC` and `FSPOOL` can also be located on VSAM files.

The installation of Natural for VSAM in a VSAM file system is basically a combination of the installation descriptions for both base Natural and Natural for VSAM, plus some points specific to VSAM.

For support of source object locking, a separate `FLOCK` file and related paths are required.

- Installation Medium

- Installation Procedure

- Installation Verification

- Restrictions

## Installation Medium

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

If you want to install Natural in a VSAM file system, you need the data sets for both base Natural and Natural for VSAM. The required data sets are listed in the table below:

Data Set Name | Contents
--- | ---
`NATvrs.LOAD` | Load modules
`NATvrs.SRCE` | Source modules and macros
`NATvrs.JOBS` | Sample installation jobs
`NATvrs.INPL` | Natural objects
`NATvrs.EXPL` | Natural example objects
`NVSvrs.LOAD` | Load modules
`NVSvrs.SRCE` | Source modules and macros
`NVSvrs.JOBS` | Sample installation jobs
`NVSvrs.VINI` | `FDIC` initialization file for Natural for VSAM
`NVSvrs.LINI` | `FLOCK` initialization file for Natural for VSAM
`NVSvrs.EMPL` | EMPLOYEES example data
`NVSvrs.EXPL` | Natural example objects

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

## Installation Procedure

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

The VSAM jobs (for example, VSAMI008) indicated in this section are identical to the jobs generated by System Maintenance Aid (for example, I008).

- Step 1: Define the CICS RDO Definitions

- Step 2: Load the Employees Example Data

- Step 3: Prepare the VSAM Clusters for the Natural System Files

- Step 4: Prepare a VSAM Cluster for the Spool File

- Step 5: Prepare a VSAM Cluster for the Security File

- Step 6: Prepare a VSAM Cluster for the Scratch-Pad File

- Step 7: Prepare a VSAM Cluster for the Source Locking File FLOCK

- Step 8: Build the Natural for VSAM I/O Module

- Step 9: Build the Natural Parameter Module for Batch Mode for VSAM

- Step 10: Link the Nucleus for Batch Natural

- Step 11: Load the Natural Objects

- Step 12: Load the Natural Example Objects

- Step 13: Reorganize the FNAT System File

- Step 14: Build the Natural for VSAM I/O Module for CICS

- Step 15: Link the Nucleus for Natural Under a TP Monitor

- Step 16: Customize your TP Monitor

### Step 1: Define the CICS RDO Definitions

(Job VSAMI005)

- Define the CICS RDO definitions for the sample VSAM files.

### Step 2: Load the Employees Example Data

(Job VSAMI008, Steps 1403 - 1407)

1. Define the VSAM cluster and files to contain the Employees example file.

2. Load the `NVSvrs.EMPL` data set into the first of these files (suffix `.EMPL`).

3. Build a secondary index of this into the second file (suffix `.EMPLX`) and define the path for this.

### Step 3: Prepare the VSAM Clusters for the Natural System Files

(Job VSAMI008, Steps 1420 - 1446)

- Define three VSAM clusters to be used as system files for Natural (`FNAT`, `FUSER` and `FDIC`), an alternate index and a path for the alternate index for `FDIC`.

  We strongly recommend that you keep these three system files on separate VSAM clusters.

### Step 4: Prepare a VSAM Cluster for the Spool File

(Job VSAMI008, Steps 0300 - 0309)

This step must be performed only if you have Natural Advanced Facilities installed and want your spool file to be a VSAM file, too.

- Define an additional VSAM cluster to be used as the spool file (`FSPOOL`) and five alternate indices.

  Note
  Path processing is not supported for `FSPOOL`.

### Step 5: Prepare a VSAM Cluster for the Security File

(Job VSAMI008, Steps 9900 - 9907)

This step must be performed only if you have Natural Security installed and want your security file to be a VSAM file, too.

- Define an additional VSAM cluster to be used as the security file (`FSEC`) and three alternate indices.

  Note
  Path processing is not supported for `FSEC`.

### Step 6: Prepare a VSAM Cluster for the Scratch-Pad File

(Job VSAMI008, Steps 1450, 1451)

This step must be performed only if you want to use a scratch-pad file; that is, if you want to use read-only Natural system files (`ROSY=ON`); see also the Natural profile parameter `ROSY` and the macro `NTLFILE` described in the Parameter Reference documentation.

- Define an additional VSAM cluster to be used as the scratch-pad file (Step 1450).

- Initialize the VSAM scratch-pad file (Step 1451).

- Set the following parameters in the Natural parameter module according to your requirements:

      NTLFILE 212,dbid,nt-file-number,dd-name-scratch-pad-file
      ROSY=ON

- If you want your Natural system file(s) to be opened for input, adapt your Natural parameter module as follows:

      FNAT=(dbid,fnr,filename,,RO),
      FUSER=(dbid,fnr,filename,,RO),
      FSEC=(dbid,fnr,filename,,RO),

### Step 7: Prepare a VSAM Cluster for the Source Locking File FLOCK

(Job VSAMI008, Steps 1460, 1461)

This step must be performed only if you want to lock source objects in a VSAM file system (`SLOCK=PRE`); see also the parameter `SLOCK` and the macro `NTLFILE` (described in the Parameter Reference documentation).

- Define an additional VSAM cluster to be used as the source locking file (Step 1460).

- Load and print the example data record contained in the VSAM source locking file (Step 1461).

- Set the following parameters in the Natural parameter module according to your requirements:

      NTLFILE 002,dbid,nt-file-number,dd-name-source-locking-file,,PATH
      SLOCK=PRE

  The default DD name (`dd-name`) is `FLOCK`, the related default paths are `FLOCKA`, `FLOCKB` and `FLOCKC`.

### Step 8: Build the Natural for VSAM I/O Module

(Job VSAMI055, Steps 1410, 1411, 1415, 1416)

- Edit, assemble and link the Natural for VSAM I/O module `NVSMISC` with the LSR options:

      DEFER=YES
      COMMIT=NO
      READINT=NO

  For the parameters that can be specified in the `NVSMISC` module, see the relevant section in the Database Management System Interfaces documentation.

### Step 9: Build the Natural Parameter Module for Batch Mode for VSAM

(Job I060, Step 0010)

1. Modify the settings of the supplied Natural profile parameters as required for batch mode. The parameters and corresponding macros (if applicable) are described in the Parameter Reference documentation. The most important parameter/macro settings are described below.

   - Configure the z/OS batch interface:
     Modify the settings of the parameters supplied with the `NTOSP` macro to meet your requirements. For descriptions of these parameters, see the corresponding profile parameter `OSP`.

   - In addition to the `VSIZE` and `NTDB` specifications, modify the parameters `FNAT`, `FUSER` and `FDIC` as follows:

         VSIZE=126,
         FNAT=(vsam-dbid,fnr-fnat,dd-name-fnat),
         FUSER=(vsam-dbid,fnr-fuser,dd-name-fuser),
         FDIC=(vsam-dbid,fnr-fdic,dd-name-fdic),
         NTDB VSAM,vsam-dbid
         NTVSAM

     The `vsam-dbid` must have the same value in all four entries.

     We recommend that you use different files and different file numbers for `FNAT` and `FUSER`. The `FDIC` file must be a file different from `FNAT` and `FUSER`. Therefore, you may not omit the `FDIC` parameter.

     The DD names (`dd-name`) are the logical names of the Natural system files; each DD name can be up to seven characters long. The DD name for the `FDIC` path is created by appending an `X` to the DD name of the `FDIC` file.

   - If you have Natural Advanced Facilities installed and want your spool file to be a VSAM file, modify the `FSPOOL` parameter accordingly:

         FSPOOL=(vsam-dbid,fnr-fspool,dd-name-fspool)

   - If you have Natural Security installed and want your security file to be a VSAM file, modify the `FSEC` parameter accordingly:

         FSEC=(vsam-dbid,fnr-fsec,dd-name-fsec)

     The `FSEC` file must be a file different from `FNAT`.

   - For a quick installation, use the Natural for VSAM LSR feature and specify the following `NTVLSR` definitions in the Natural parameter module (see also NTVLSR Macro in the Parameter Reference documentation):

         NTVLSR fnat-dd-name,1
         NTVLSR fuser-dd-name,2
         NTVLSR fdic-dd-name,3
         NTVLSR fdicx-dd-name,3

     If you want to use `FSEC` system files:

         NTVLSR fsec-dd-name,4
         NTVLSR fseca-dd-name,4
         NTVLSR fsecb-dd-name,4
         NTVLSR fsecc-dd-name,4

2. Assemble and link the batch parameter module.

### Step 10: Link the Nucleus for Batch Natural

(Job I060, Step 0020)

1. Modify the JCL used to link your environment-dependent nucleus for batch Natural by adding the following `INCLUDE` statements:

        INCLUDE NVSLIB(NVSNUC)
        INCLUDE NVSLIB(NVSFNAT)
        INCLUDE NVSLIB(NVSFSPO)
        INCLUDE NVSLIB(NVSFSEC)
        INCLUDE SMALIB(NVSFLOCK)
        INCLUDE SMALIB(NVSMISC)

   The module `NVSFSPO` is only required if you have Natural Advanced Facilities installed and want your spool file to be installed in a VSAM file system.

   The module `NVSFSEC` is only required if you have Natural Security installed and want your security file to be installed in a VSAM file system.

   The module `NVSFLOCK` is only required if you want to lock source objects contained in an `FUSER` or `FNAT` system file in a VSAM file system.

   If your environment-dependent nucleus is not linked to your environment-independent nucleus, `NVSMISC` must be linked to the Natural parameter module instead.

2. Add the corresponding DD statements to the link step for Natural.

For information on the components and structure of the Natural interface to VSAM, see also Components of Natural for VSAM and Structure of the Natural Interface to VSAM in the Database Management System Interfaces documentation.

### Step 11: Load the Natural Objects

(Job I061, Step 0100)

- Load the Natural objects from the `NATvrs.INPL` data set into the Natural system file by using the Natural INPL utility.

  Ensure that the DD names specified in the Natural parameter module (see Step 9: Build the Natural Parameter Module for Batch Mode for VSAM) are also specified for the load function performed with the Natural INPL utility. In addition, an alternate index DD name (`dd-name-fdicX`) must be specified for `FDIC`.

Note
If you want to install any other Software AG products that require Natural objects to be loaded with the Natural INPL utility, ensure that the corresponding installation steps are adapted according to Job VSAMI061.

### Step 12: Load the Natural Example Objects

(Job I061, Step 0103, and Job VSAMI061, Step 1400)

- Load the Natural example objects from the `NATvrs.EXPL` data set into the Natural system file by using the Natural INPL utility (Job I061, Step 0103).

- Load the Natural example objects specific to Natural for VSAM from the `NVSvrs.EXPL` data set into the Natural system file by using the Natural INPL utility (Job VSAMI061, Step 1400).

Ensure that the DD names specified in the Natural parameter module (see Step 9: Build the Natural Parameter Module for Batch Mode for VSAM) are also specified for the load function performed with the Natural INPL utility. In addition, a path DD name (`dd-name-fdicX`) must be specified for `FDIC`.

### Step 13: Reorganize the FNAT System File

- Reorganize the `FNAT` system file by using the VSAM facility AMS REPRO to unload and reload the file.

### Step 14: Build the Natural for VSAM I/O Module for CICS

(Job VSAMI070, Step 1400)

This step must be performed only if you want to install Natural for VSAM under CICS.

- Assemble and link the module `NVSCICS`.

### Step 15: Link the Nucleus for Natural Under a TP Monitor

(Job VSAMI080)

Proceed with the TP monitor-specific installation steps for base Natural described in the relevant sections in Installation for z/OS, taking into account the following additions:

- Modify your VSAM-specific Natural parameter module according to Step 9: Build the Natural Parameter Module for Batch Mode for VSAM.

- Add the following `INCLUDE` statements to all links of the online nucleus:

       INCLUDE NVSLIB(NVSNUC)
       INCLUDE NVSLIB(NVSFNAT)
       INCLUDE NVSLIB(NVSFSPO)
       INCLUDE NVSLIB(NVSFSEC)
       INCLUDE NVSLIB(NVSFLOCK)

  The module `NVSFSPO` is only required if you have Natural Advanced Facilities installed and want your spool file to be installed in a VSAM file system. The online environment for Natural Advanced Facilities must be a CICS environment, and the spool files installed in a VSAM file system must be defined in the CICS FCT.

  The module `NVSFSEC` is only required if you have Natural Security installed and want your Natural security system file to be installed in a VSAM file system. The VSAM Natural security system files installed in a VSAM file system must be defined in the CICS FCT.

  The module `NVSFLOCK` is only required if you want to lock source objects contained in an FUSER or FNAT system file in a VSAM file system. The locking files installed in a VSAM file system must be defined in the CICS FCT.

- Modify the JCL used to link your environment-dependent nucleus for the Natural CICS Interface by adding the following `INCLUDE` statement:

      INCLUDE SMALIB(NVSCICS)

- Modify the JCL used to link your environment-dependent nucleus for Natural TP monitor interfaces other than the Natural CICS Interface by adding the following `INCLUDE` statement:

      INCLUDE SMALIB(NVSMISC)

- Before starting Natural, ensure that the DD and DSN names of the Natural system files in the VSAM file system are known in your batch and online environments.

### Step 16: Customize your TP Monitor

Customize your TP monitor environment:

TP Monitor | Instruction
--- | ---
Com-plete | Catalog the `FNAT`, `FUSER` and `FDIC` system files in the VSAM file system under Com-plete using the CA function of the Com-plete UFILE utility (described in the Com-plete documentation). If Natural Security is installed, catalog the `FSEC`, `FSECA`, `FSECB` and `FSECC` system files in the VSAM file system under Com-plete using the CA function of the Com-plete UFILE utility. If you want to lock source objects contained in the `FUSER` or `FNAT` system file, catalog the VSAM files `FLOCK`, `FLOCKA`, `FLOCKB` and `FLOCKC` under Com-plete using the CA function of the Com-plete UFILE utility. If you have specified `PATH=CHECK` in `NTVSAM`, catalog your front program to Com-plete using the CA function of the Com-plete ULIB utility (described in the Com-plete documentation) with a region size of 36 KB if you have not changed the first default value for the `WPSIZE` (described in the Parameter Reference documentation) in the Natural parameter module.
CICS | Add the following entries to your FCT: the Natural system files `FNAT`, `FUSER`, `FDIC` and `FDICX` required for VSAM; the Natural example files `EMPLVS` and `EMPLVX` provided for VSAM; the Natural Security files `FSEC`, `FSECA`, `FSECB` and `FSECC` if you have Natural Security installed; the VSAM files `FLOCK`, `FLOCKA`, `FLOCKB` and `FLOCKC` if you want to lock source objects contained in the `FUSER` or `FNAT` system file in the VSAM file system. Refer to Job VSAMI005 for examples. You can add DD statements for these data sets to your CICS startup job, too.
TSO | Add the following statements to the CLIST used to start Natural:
    ALLOCATE F(FNAT)   DATASET('SAGLIB.VSAM.FNAT')        SHR
    ALLOCATE F(FUSER)  DATASET('SAGLIB.VSAM.FUSER')       SHR
    ALLOCATE F(FDIC)   DATASET('SAGLIB.VSAM.FDIC')        SHR
    ALLOCATE F(FDICX)  DATASET('SAGLIB.VSAM.FDIC.PATH')   SHR
    ALLOCATE F(FSEC)   DATASET('SAGLIB.VSAM.FSEC')        SHR
    ALLOCATE F(FSECA)  DATASET('SAGLIB.VSAM.FSEC.AIXA')   SHR
    ALLOCATE F(FSECB)  DATASET('SAGLIB.VSAM.FSEC.AIXB')   SHR
    ALLOCATE F(FSECC)  DATASET('SAGLIB.VSAM.FSEC.AIXC')   SHR
    ALLOCATE F(FLOCK)  DATASET('SAGLIB.VSAM.FLOCK')       SHR
    ALLOCATE F(FLOCKA) DATASET('SAGLIB.VSAM.FLOCK.PATHA') SHR
    ALLOCATE F(FLOCKB) DATASET('SAGLIB.VSAM.FLOCK.PATHB') SHR
    ALLOCATE F(FLOCKC) DATASET('SAGLIB.VSAM.FLOCK.PATHC') SHR
    ALLOCATE F(EMPLVS) DATASET('SAGLIB.VSAM.EMPLVS')      SHR
    ALLOCATE F(EMPLVX) DATASET('SAGLIB.VSAM.EMPLVX.PATH') SHR

## Installation Verification

You can verify the successful installation of Natural for VSAM by performing the following:

- Log on to the Natural system library `SYSEXNVS` and run the following programs:

  - `NVSINST1`

  - `NVSINST2`

  - `NVSINST3`

  - `NVSINST4`

  - `NVSINST5`

  - `NVSINST6`

  If all these programs can be executed successfully, the installation of Natural in a VSAM file system is completed and verified.

#### Note for Batch Mode:

For verification in batch mode, you can run Job VSAMI200 which executes the above programs.

## Restrictions

The Natural `FSEC` and `FSPOOL` system files provided for VSAM file systems cannot be used for record-level sharing (RLS), as the related AIX files cannot be accessed using a path definition. The reason is that null values are not suppressed during VSAM upgrade handling for AIX keys. The record length of AIX files related to `FSEC` and `FSPOOL` would be exceeded for AIX keys filled with blanks or binary zeros. This would cause problems under CICS, as the record length supported is limited to 32 K only. Natural for VSAM supports null-value suppression for AIX keys and the upgrade handling for AIX files.

### On this page

- Installation Medium
- Installation Procedure
- Installation Verification
- Restrictions