Version 4.2.6 for Mainframes	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

The Natural parameters in a VSAM environment are defined in two locations: the Natural standard parameters, contained in the Natural parameter module NATPARM, and the Natural parameters specific to VSAM, contained in the source member NVSPARM. Both are provided as source members only and can be edited to conform to your site standards, and then assembled and linked using the appropriate jobs (see Installing Natural for VSAM).

In the remainder of this section, Natural for VSAM is also referred to as NVS.

This section covers the following topics:

• Customizing NATPARM

• Assembling the NVSPARM Parameter Module

• Natural I/O Modules for VSAM

Customizing NATPARM

To be able to run Natural in a VSAM environment, you must include the VSIZE parameter and the NTDB macro in your NATPARM parameter source (see the section Installation Procedure for z/OS and z/VSE).

For an Adabas system file:

VSIZE=72,
NTDB VSAM,vsam-dbid

For a VSAM system file:

VSIZE=126,
  
FNAT=(vsam-dbid,fnr,dd-name),
FUSER=(vsam-dbid,fnr,dd-name),
FDIC=(vsam-dbid,fnr,dd-name),
FSPOOL=(vsam-dbid,fnr,dd-name),
FSEC=(vsam-dbid,fnr,dd-name)
  
NTDB VSAM,vsam-dbid

dd-name is the logical name (DD or DLBL) of the system file; see also Installing Natural on VSAM Files (z/OS), Step 9, and Installing Natural on VSAM Files (z/VSE), Step 9.

Note:
If you use VSAM system files with Natural ISPF, see also the Natural ISPF documentation.

Below is information on:

• VSIZE Parameter

• NTDB Macro

VSIZE Parameter

VSIZE is a Natural profile parameter which can also be specified dynamically. It is used to specify the size of the Natural buffer area for VSAM and defines the maximum memory usage for the internal tables of the Natural interface to VSAM; the actual sizes of these tables depend on the values set in NVSPARM (see Assembling the NVSPARM Parameter Module). Possible values are 0 - 512 KB.

If you use the default values specified in NVSPARM, the value of the VSIZE parameter must be at least 72 KB.

If VSIZE is set to 0, Natural for VSAM is not available and a corresponding error message is returned when trying to access VSAM files. Disabling Natural for VSAM leads to slight performance improvements because of skipping the initialization, relocation and roll efforts of the Natural interface to VSAM.

NTDB Macro

The NTDB macro is used to specify the database numbers that relate to VSAM files, which means the logical assignments available for Natural.

The value range of NTDB parameters is described in Parameter Modules in the Natural Parameter Reference documentation.

Note:
Ensure that the DBIDs selected in the NTDB macro for VSAM do not conflict with DBIDs selected for other DBMSs.

Assembling the NVSPARM Parameter Module

NVSPARM is delivered in source form only. If the default values supplied in the NVSPARM source do not meet your requirements, you can change the parameter values to suit your environment. The individual parameters contained in NVSPARM are described in the following section.

The NVSPARM module is created by assembling the macro:

• NVMPARM

and optionally one or more of the following macros:

• NVMLSR

• NVMEXIT

• NVMTVS

If more than one macro is specified, the NVMPARM macro must be specified first; further macros after the NVMPARM macro can be specified in any order.

The individual macros are:

• NVMPARM Macro

• NVMLSR Macro

• NVMEXIT Macro

• NVMTVS Macro

NVMPARM Macro

The NVMPARM macro contains the following parameters:

The individual parameters are described in the following section.

BTSUPP - Support of BACKOUT TRANSACTION Statement

This parameter determines whether BACKOUT TRANSACTION statements are executed or not. It is applicable only in TP and DFSMStvs environments where VSAM logging is supported.

CLSUPP - Support of CLOSE Call at Session Termination

This parameter determines whether or not a CLOSE call is executed at session termination. If a CLOSE is executed, Natural for VSAM forces an END TRANSACTION only in TP and DFSMStvs environments where VSAM logging is supported.

DDMCHECK - Support of DDM Integrity

This parameter checks whether the file layout and, in consequence, the DDM has changed. The check is performed after each program termination at the NEXT level, through the Natural buffer pool. The DDMCHECK parameter is only relevant for development environments where DDMs are modified. In production environments, disable this feature to improve performance.

DDSWITE - Maximum Entries in DD/DLBL Name Switch Buffer

This parameter specifies the maximum number of entries in the DD/DLBL name switch buffer. For details on switching DD names, see the application programming interface USR1047N in the section Operation.

DFBE - Number of Decoded Format Buffer Entries

This parameter specifies the initial number of entries in the table of decoded format buffers. For each active Natural I/O statement (FIND, READ, UPDATE, STORE) one entry is allocated in this table.

When increasing DFBE or DFBN, take into consideration that the allocated storage area size is obtained by multiplying these values and not by adding them.

DFBN - Number of Fields in Entry of Decoded Format Buffer

This parameter specifies the average number of fields contained in an entry of the decoded format buffer table. One entry is built for each Natural I/O statement (FIND, READ, UPDATE, STORE).

When increasing DFBE or DFBN, take into consideration that the allocated storage area size is obtained by multiplying these values and not by adding them.

ENADIS - Enabling Disabled Files

This parameter only applies to CICS environments and is only honored by the first file access performed in the current Natural session.

ENADIS is used to enable disabled files. If the parameter is set to OFF and the file has not been enabled, the NAT3516 error message must follow the first file access.

ENAUNE - Enabling Unenabled Files

This parameter only applies to CICS environments and is only honored by the first file access performed in the current Natural session.

ENAUNE is used to enable "unenabled" files. If the parameter is set to OFF and the file has not been enabled, the NAT3539 error message must follow the first file access.

ETSUPP - Support of END TRANSACTION Statement

This parameter determines whether END TRANSACTION statements are executed or not. It is applicable only in TP and DFSMStvs environments where VSAM logging is supported.

FORMAT- Support of Record Formatting for STORE and UPDATE Statements

This parameter supports the formatting of VSAM records referenced in a STORE or UPDATE statement. Record fields that are not referenced and, therefore, contain binary zeros are converted into a format that corresponds to the field type and record length defined in the relevant DDM.

NVS system file records are always formatted; this cannot be changed.

KEYLGH - Length of VSAM Keys used in I/O Statements

This parameter specifies the length of VSAM keys used in Natural I/O statements. The maximum key length for a VSAM file is 255 bytes. The value of this parameter is used to calculate the size of the TSA table (Table of Sequential Access).

If you use VSAM system files, specify at least:

• 87 bytes for the FNAT, FUSER, FDIC and FSPOOL files,

• 126 bytes for the FSEC and Natural ISPF system files.

OPSUPP - Support of Dynamic OPEN Calls

This parameter is used to support multiple different OPEN calls within one session.

PATH - Support of Path Processing

This parameter is used to handle a secondary key as a path or as a native AIX file.

If you use the VSAM system files FSEC and/or FSPOOL, you must not specify ON: specify either OFF or CHECK.

Note:
If PATH=CHECK is set under CICS and/or Com-plete in a z/VSE environment, the startup JCL job must contain the corresponding DLBL card(s).

PSIGNF - Support of Compiler Option PSIGNF

This parameter is used to handle the internal representation of positive signs of packed numbers.

RETRY - Support of RETRY Statement for an ON ERROR Clause

This parameter is used to support the RETRY statement for the following NVS error messages:

NAT3541     File :1:, control interval/record held by another user.
  
NAT3520     Held VSAM record modified by another user.

The first value of the RETRY parameter applies to NAT3541, the second to NAT3520.

RLS - Support of Record-Level Sharing

Applies to z/OS only.

This parameter is used to support VSAM record-level sharing (RLS) under z/OS, DFSMS Version 1.6 or higher.

If TVS=ON is set (see TVS below) and no VSAM file has been defined in the NVMTVS macro (see below), set RLS=CHECK to verify that the corresponding VSAM file has been defined as recoverable dataset.

ROLLSIZ - Size of Area for Session Status Information

This parameter is applicable in a thread environment only (CICS, Com-plete, Natural as a Server).

It specifies the size of the area used by Natural to save internal session status information when a Natural transaction is terminated due to the end of a TP-monitor task.

SFILE - Support of VSAM system files

This parameter is used to support VSAM system files.

Note:
If SFILE=CHECK is set under CICS and/or Com-plete in a z/VSE environment, the startup JCL job must contain the corresponding DLBL card(s).

TAFE - Maximum Number of DDMs per Natural Session

This parameter specifies the maximum number of DDMs per Natural session.

Since it is possible to define several descriptors in one DDM, the TAFE parameter has impact on the sizes of the FCT, FWA, OPV and TAF buffers (see Buffers for Memory Management).

When increasing TAFE or TAFN, take into consideration that the allocated storage area size is obtained by multiplying these values and not by adding them.

TAFN - Average Number of DDM Fields

This parameter specifies the average number of DDM fields contained in each entry in the table of accessed VSAM files.

When increasing TAFE or TAFN, take into consideration that the allocated storage area size is obtained by multiplying these values and not by adding them.

TIMEOUT - Timeout in Seconds for an RLS Request

This parameter only applies to z/OS CICS Version 5.3 or higher.

This parameter is used to support an RLS/non-RLS-file mixed environment under z/OS CICS Version 5.3 or higher in a Natural for VSAM session. Natural and Natural for VSAM Version 6.2 are plex-enabled, that is, after a terminal I/O the Natural session can be continued by the workload manager on a different z/OS in a different CICS 5.3, provided the resources are plex-enabled. Since this is not the case with non-RLS files, the session must be run in conversational mode as soon as a VSAM file is opened in non-RLS mode.

With the TIMEOUT parameter, you can determine that non-RLS files are to be deleted from the NVS FCT queue. When there are no further non-RLS FCT entries for the particular Natural for VSAM session, Natural for VSAM switches to non-conversational mode, which means that z/OS Parallel Sysplex processing is possible again.

TSAE - Maximum Number of Nested READ and FIND Statements

This parameter is used to set the maximum number of all nested READ and FIND statements.

TVS - Support of DFSMStvs

Applies to z/OS only.

This parameter is used to support DFSMS Transactional VSAM Services (DFSMStvs). If TVS is set to ON, the parameters BTSUPP and ETSUPP are forced to ON. The parameter RLS is only forced to ON if RLS has been set to OFF (RLS=CHECK is not forced to ON).

UPDL - Size of Update Table

This parameter indicates the size of the table used by the Natural interface to VSAM to save the fields of records read for subsequent updating. Because these records are not read with hold by Natural to avoid deadlock conditions, the content of the UPDL table is used to check if any changes have been made before the update request by another user.

NVMLSR Macro

The NVMLSR macro is only required if VSAM files are used as local shared resources. Its purpose is to substantially increase the performance of TSO and batch runs, and, at the same time, decrease the VSAM I/O rate.

The NVMLSR macro is specified as follows:

NVMLSR DDNAME= dd-name,SHRPOOL= nn

Up to 200 logical files are possible.

If ERROR=YES is set in NVSMISC, all files defined with the NVMLSR macro must be defined via JCL at runtime; otherwise, an appropriate Natural initialization error message is returned.

If you have defined base clusters with NVMLSR which contain path entries, all paths must also be defined with NVMLSR.

For non-path environments the following applies: If the upgrade option is active in the VSAM catalog and if a VSAM file is defined with NVMLSR and contains references to an alternate index (AIX), all AIX files must also be defined with NVMLSR.

Natural for VSAM automatically calculates the optimum pool size by using the corresponding VSAM catalog information on the files involved, and then creates separate subpools for data and index components.

In batch mode under z/OS, Natural for VSAM allocates the pools as ESO hiperspace if the following conditions are met:

• All sizes in the VSAM catalog are at least specified as 4 KB or a multiple of this value (this is valid for both data and index components).

• The library from which Natural for VSAM was loaded is an APF-authorized library.

• This condition is necessary to define the address space as "non-swapable", which is a prerequisite for ESO hiperspaces.

NVMEXIT Macro

Natural for VSAM provides the facility to define one or more user exits. For each VSAM file to be accessed, one user exit can be defined. The definition of a user exit is done by using the NVMEXIT macro.

NVMEXIT is specified as follows:

NVMEXIT DDNAME=dd-name,PGM=exit-name,WORK=nnnn

All user exits must be linked to the front-end.

User Exit Linkage Conventions

When passing control to and from the user exit, standard IBM linkage conventions and standard linkage register notations are used.

The current function (see Register 1 above) indicates the way control has been passed to the user exit. Control can be passed either before or after a Natural call for VSAM (see also the DCRREQCD field in the NVMDCR macro delivered):

• With the STORE and UPDATE statements, control is passed before the call.

• With the FIND, GET, and READ statements, control is passed after the call.

Sample User Exit

A sample user exit NVSEX01 is provided on the installation tape.

NVMTVS Macro

DFSMS Transactional VSAM Services (DFSMStvs) is activated by setting either the ACB parameter RLSREAD or the JCL parameter RLS. In general, NVS opens all VSAM files for output by default.

The NVMTVS macro activates DFSMStvs by specifying the read integrity value of the ACB parameter RLSREAD. Specifying RSLREAD in NVMTVS, you do not have to adapt the JCL to activate DFSMStvs.

If you only set TVS=ON in the NVSPARM module without specifying the corresponding VSAM file in NVMTVS, to activate DFSMStvs, you need to modify the JCL as described below. In this case, you must specify RLS=CHECK in the NVMPARM module.

To activate DFSMStvs with NVMTVS

• Use the following specification:

  NVMTVS DDNAME=dd-name,RLSREAD=[NRI/CR/CRE]

  Parameter	Explanation
  DDNAME	Logical file name that corresponds to the one in your JCL startup job.
  RLSREAD	NRI No read integrity (dirty read). CR Consistent read. CRE Consistent read explicit.

To activate DFSMStvs in the JCL

• Set the RLS parameter to

  RLS=NRI/CR/CRE

To activate DFSMStvs in Complete

• Set the RLSREAD parameter in the nFile utility to

  RLSREAD=NRI/CR/CRE

Natural I/O Modules for VSAM

The Natural I/O module for VSAM depends on the actual environment in use.

All available I/O modules are delivered in source form so you can make site-specific modifications and use environment-specific macros and/or precompilers.

The I/O modules available are:

• NVSCICS Module

• NVSMISC Module

NVSCICS Module

The NVSCICS module is required for CICS under z/OS or z/VSE. The module contains the following parameter:

&FCTRELI - Indicator of Reliable Remote FCT Entries

The &FCTRELI parameter indicates whether the key length and record size of a remote file are correctly defined in the FCT entry of the Application Owning Region (AOR).

When this parameter is set to 1, NVSCICS assumes a correct FCT entry.

When this parameter is set to 0, NVSCICS issues dummy commands to force opening of the file in the File Owning Region (FOR) region and then repeats inquiring for the real values.

If the FCT entry does not contain a key length definition, NVSCICS uses the key length of the corresponding VSAM DDM.

NVSMISC Module

The NVSMISC module is required in all environments except for CICS. The module mainly consists of the name of the relocatable module for z/VSE and the NVMMISC macro, which is used to generate the NVSMISC I/O interface according to your operating system and/or TP-monitor environment.

NVSMISC is specified as follows:

The name of the relocatable module must be 8 characters long; the default name is NVSMISCD (z/VSE only).

The individual parameters are described in the following section; specify these parameters according to your requirements.

NONRLS - Switch from RLS to Non-RLS Mode

This parameter is ignored under z/VSE.

When Natural for VSAM issues an RLS-OPEN for an RLS file and this file has already been opened in non-RLS mode in this z/OS session, this parameter specifies whether Natural for VSAM issues an open retry in a non-RLS mode, or whether an open error occurs.

TIMEOUT - Timeout in Seconds for an RLS Request

This parameter is ignored under z/VSE.

This parameter specifies the time in seconds Natural for VSAM is waiting to obtain a lock on a Natural for VSAM record when a lock on the record is already held by another user. For further details refer to the IBM manual z/OS DFSMS Version 1.6 or higher, Macro Instructions for Datasets.

DEFER - Defer Writes in LSR Pools

This parameter only applies in batch mode and under TSO.

This parameter specifies whether write operations to disk are to be deferred in the LSR pool. If so and if the LSR pool becomes full, Natural for VSAM writes to disk those 5% of the pool area which have not been used for the longest time.

DSECTS - List VSAM System DSECTs

The DSECTS parameter specifies whether the VSAM system DSECTs are to be listed or not.

COMMIT - Support of Buffer Flush for LSR Pools

This parameter only applies in batch mode and under TSO.

The COMMIT parameter specifies whether all non-committed updates in any LSR pool are to be written to disk with each END TRANSACTION statement of a user program.

Note:
The specification of COMMIT=YES increases the I/O rate considerably.

ERROR - Issue Initialization Error

This parameter issues a Natural initialization error if any DD or DLBL card is omitted in the runtime JCL (see also the macro NVMLSR).

If set to NO, processing is continued and Natural for VSAM will be initialized.

HFACTOR - Factor for Hiperspace Buffers

The HFACTOR parameter specifies a factor for the creation of ESO hiperspace buffers. When initializing such a hiperspace, the corresponding BLDVRP request may lead to a Natural error message, in which case the value of HFACTOR must be reduced.

READINT - Read Integrity for Upgrade Set

The READINT parameter specifies whether read integrity for an upgrade set should be granted or not.

SMARTS - Support of SMARTS and Com-plete

The SMARTS parameter is required if installing Natural for VSAM under SMARTS and/or in a Complete environment.

TVS - Support of DFSMS Transactional VSAM Services (DFSMStvs)

This parameter is ignored under z/VSE. The TVS parameter specifies the support of DFSMStvs in a z/OS environment.

www.softwareag.com

Copyright © Software AG 1979-2009. All rights reserved.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT