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)

Define the VSAM cluster and files to contain the Employees example file.
Load the NVSvrs.EMPL data set into the first of these files (suffix .EMPL).
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)

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
```
Assemble and link the batch parameter module.

Step 10: Link the Nucleus for Batch Natural

(Job I060, Step 0020)

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.
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

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

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.