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

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

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

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.LIBR Source modules, macros, phases and object modules
NATvrs.JOBS Sample installation jobs
NATvrs.INPL Natural objects
NATvrs.EXPL Natural example objects
NVSvrs.LIBJ Sample installation jobs
NVSvrs.LIBR Source modules, macros, phases and object modules
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/VSE 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

(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) and a path 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,dlbl-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,dlbl-name-source-locking-file,,PATH
SLOCK=PRE

    The default DLBL name (dlbl-name) is FLOCK, the related default paths are FLOCKA, FLOCKB and FLOCKC.

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

(Job VSAMI055, Step 1410)

  • 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/VSE batch interface:
      Modify the settings of the parameters supplied with the NTVSEP macro to meet your requirements.

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

      VSIZE=160,
FNAT=(vsam-dbid,fnr-fnat,dlbl-name-fnat),
FUSER=(vsam-dbid,fnr-fuser,dlbl-name-fuser),
FDIC=(vsam-dbid,fnr-fdic,dlbl-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 DLBL names (dlbl-name) are the logical names of the Natural system files; each DLBL name can be up to seven characters long. The DLBL name for the FDIC path is created by appending an X to the DLBL 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,dlbl-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,dlbl-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-dlbl-name,1
NTVLSR fuser-dlbl-name,2
NTVLSR fdic-dlbl-name,3
NTVLSR fdicx-dlbl-name,3

      If you want to use FSEC system files: 

      NTVLSR fsec-dlbl-name,4
NTVLSR fseca-dlbl-name,4
NTVLSR fsecb-dlbl-name,4
NTVLSR fsecc-dlbl-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 NVSNUC
INCLUDE NVSFNAT
INCLUDE NVSFSPO
INCLUDE NVSFSEC
INCLUDE NVSFLOCK
INCLUDE NVSMISCD

    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, NVSMISCD must be linked to the Natural parameter module instead.

  2. Add the corresponding sublibrary for Natural for VSAM to the search chain for the linkage editor.

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 DLBL 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 DLBL name (dlbl-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 0103)

  • 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 0103).

Ensure that the DLBL 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 DLBL name (dlbl-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/VSE, 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 NVSNUC
INCLUDE NVSFNAT
INCLUDE NVSFSPO
INCLUDE NVSFSEC
INCLUDE 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 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 NVSMISCD

  • Add the corresponding sublibrary for Natural for VSAM to the search chain for the linkage editor. Before starting Natural, ensure that the DLBL 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

Add the following DLBL statements to your Com-plete startup job: 

// DLBL FNAT,'DSN=SAGLIB.VSAM.FNAT',,VSAM,CAT=xxxx
// DLBL FUSER,'DSN=SAGLIB.VSAM.FUSER',,VSAM,CAT=xxxx
// DLBL FDIC,'DSN=SAGLIB.VSAM.FDIC',,VSAM,CAT=xxxx
// DLBL FDICX,'DSN=SAGLIB.VSAM.FDIC.PATH',,VSAM,CAT=xxxx
// DLBL EMPLVS,'DSN=SAGLIB.VSAM.EMPLVS',,VSAM,CAT=xxxx
// DLBL EMPLVX,'DSN=SAGLIB.VSAM.EMPLVX.PATH',,VSAM,CAT=xxxx

If Natural Security is installed, add the following DLBL statements to your Com-plete startup job: 

// DLBL FSEC,'DSN=SAGLIB.VSAM.FSEC',,VSAM,CAT=xxxx
// DLBL FSECA,'DSN=SAGLIB.VSAM.FSEC.AIXA',,VSAM,CAT=xxxx
// DLBL FSECB,'DSN=SAGLIB.VSAM.FSEC.AIXB',,VSAM,CAT=xxxx
// DLBL FSECC,'DSN=SAGLIB.VSAM.FSEC.AIXC',,VSAM,CAT=xxxx

If you want to lock source objects contained in the FUSER or FNAT system file in the VSAM file system, add the following DLBL statements to your Com-plete startup job: 

// DLBL FLOCK,'DSN=SAGLIB.VSAM.FLOCK',,VSAM,CAT=xxxx
// DLBL FLOCKA,'DSN=SAGLIB.VSAM.FLOCK.PATHA',,VSAM,CAT=xxxx
// DLBL FLOCKB,'DSN=SAGLIB.VSAM.FLOCK.PATHB',,VSAM,CAT=xxxx
// DLBL FLOCKC,'DSN=SAGLIB.VSAM.FLOCK.PATHC',,VSAM,CAT=xxxx

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 DLBL statements for these data sets to your CICS startup job, too.

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 AIX files that relate to the Natural FSEC and FSPOOL system files provided for a VSAM file system 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.