Version 4.2.6
 —  Database Management System Interfaces  —

Customizing Natural for VSAM

The Natural parameters in a VSAM environment are defined in two locations:

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

This section covers the following topics:


Customizing NATPARM

To be able to run Natural in a VSAM environment, you must include the profile parameter VSIZE 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

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, 1 - 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 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 database management systems.

Top of page

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:

and optionally one or more of the following macros:

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

The NVMPARM macro contains the following parameters:

Parameter Explanation
BTSUPP Support of BACKOUT TRANSACTION statement.
CLSUPP Support of CLOSE calls at session termination.
DDMCHECK Support of DDM integrity.
DDSWITE Maximum number of entries in DD/DLBL name switch buffer.
DFBE Number of decoded format buffer entries.
DFBN Number of fields in an entry of the decoded format buffer.
ENADIS Enabling disabled files (CICS only).
ENAUNE Enabling "unenabled" files (CICS only).
ETSUPP Support of END TRANSACTION statement.
FORMAT Support of record formatting for STORE and UPDATE statements.
KEYLGH Length of VSAM keys used in I/O statements.
OPSUPP Support of dynamic OPEN calls.
PATH Support of path processing.
PSIGNF Support of compiler option PSIGNF.
RETRY Support of RETRY statement for ON ERROR clause.
RLS Support of VSAM record-level sharing.
ROLLSIZ Size of area for session status information.
SFILE Support of VSAM system files.
TAFE Maximum number of DDMs per Natural transaction.
TAFN Average number of DDM fields.
TSAE Maximum number of nested READ and FIND statements.
TIMEOUT Timeout in minutes for non-RLS processing in a z/OS Parallel Sysplex environment.
TVS Support of DFSMS Transactional VSAM Services (DFSMStvs).
UPDL Size of update table.

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.

Possible value Default value Explanation
ON ON Each BACKOUT TRANSACTION is executed and translated into an appropriate ROLLBACK command.
OFF   BACKOUT TRANSACTION statements are ignored.

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.

Possible value Default value Explanation
ON ON Each CLOSE call is executed and translated into an appropriate SYNCPOINT command.
OFF   Each CLOSE call is ignored.

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.

Possible value Default value Explanation
ON   DDM check enabled.
OFF OFF DDM check disabled.

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.

Possible values Default value
0 up to the value of the TAFE parameter 0

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.

Possible values Default value
1 - 1000 10

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.

Possible values Default value
1 - 1000 50

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.

Possible value Default value Explanation
ON   For all disabled files accessed during the session, an EXEC CICS SET ENABLED command is executed.
OFF OFF All disabled files remain disabled.

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.

Possible value Default value Explanation
ON   For all unenabled files accessed during the session, an EXEC CICS SET ENABLED command is executed.
OFF OFF All unenabled files remain unenabled.

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.

Possible value Default value Explanation
ON ON Each END TRANSACTION is executed and translated into an appropriate SYNCPOINT command.
OFF   END TRANSACTION statements are ignored.

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.

Possible value Default value Explanation
ON ON VSAM records are formatted in accordance with the corresponding DDM definitions.
OFF   VSAM records are not formatted and fields that are not referenced contain binary zeros.

Natural for VSAM 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:

Possible values Default value
1 - 255 (bytes) 32

OPSUPP - Support of Dynamic OPEN Calls

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

Possible value Default value Explanation
ON   Multiple different OPEN calls are supported by calling the application programming interface USR2008N (for further information, see the section Operation).
OFF OFF Multiple different OPEN calls are not supported 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.

Possible value Default value Explanation
ON   All secondary keys defined in a DDM are handled as paths for AIX files.
OFF   All secondary keys are handled as AIX files.
CHECK CHECK Natural for VSAM checks whether the secondary keys are defined as paths or as AIXs in the VSAM catalog.

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.

Possible value Default value Explanation
ON   Natural for VSAM supports the compiler option PSIGN for a Natural object, the corresponding DDM description in the field ZONES is ignored.
OFF OFF Natural for VSAM uses the DDM description in field ZONES.

RETRY - Support of RETRY Statement for an ON ERROR Clause

This parameter is used to support the RETRY statement for the following Natural for VSAM 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.

Possible values Default value
(ON/OFF, ON/OFF) (OFF, OFF)

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.

Possible value Default value Explanation
ON   All files are opened in RLS mode.
OFF OFF All files are opened in non-RLS mode (NSR, LSR).
CHECK   All files are checked whether they are defined as SMS-managed datasets with RLS options; if they are, the file is opened in RLS mode, if not in non-RLS mode.

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.

Possible values Default value
0 - 10000 (bytes) 550

SFILE - Support of VSAM system files

This parameter is used to support VSAM system files.

Possible value Default value Explanation
ON   Support of VSAM system files
OFF OFF No support of VSAM system files.
CHECK   Checks whether the Natural system files FNAT, FUSER and FDIC files are defined as Natural for VSAM Version 4.2 VSAM system files with the required key length of 87.

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.

Possible values Default value
0 - 1000 10

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.

Possible values Default value
0 - 1000 50

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 Natural for VSAM 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.

Possible values Default value
0 - 10 0

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.

Possible values Default value
0 - 100 10

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

Possible values Default value Explanation
ON   Support of DFSMStvs.
OFF OFF No support of DFSMStvs.

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.

Possible values Default value
0 - 500000 (bytes) 8192 or 32768 if SFILE=ON is set.

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

Parameter Explanation
DDNAME Logical file name that corresponds to the one in your JCL startup job.
SHRPOOL Specifies a pool number (ID) between 0 and 15 for z/VSE or between 0 and 255 for z/OS; see also the relevant IBM VSAM documentation.

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:

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

Parameter Explanation
DDNAME DD/DLBL/FCT name of the VSAM file to be accessed.
PGM Specifies the name of the user exit.
WORK Specifies the size of the user exit work area (in bytes).

A minimum size of 72 bytes must be specified, which corresponds to the size of the IBM standard register saved area, that is 18 full words. The maximum size possible is 1024 bytes.

The work area is allocated inside the Natural save area for VSAM, which has been previously initialized to X'0' by Natural.

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.

Register Usage
R1 Address pointer to the parameter address list.

The parameter address list provides you with the addresses of the record, of LRECL, of the current function and of the work area.

R3 Address pointer to the VSAM control area (VCA).
R12 Address pointer to the Natural basic control block (BB).
R13 Address of 18-word save area.
R14 Return address.
R15 Entry address/return code.

A return code of 0 indicates a normal return of control. In all other cases, a Natural error message is returned.

The current function (see Register R1 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):

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, Natural for VSAM 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.

Start of instruction set To activate DFSMStvs with NVMTVS

Start of instruction set To activate DFSMStvs in the JCL

Start of instruction set To activate DFSMStvs in Complete

Top of page

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

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

Possible values Default value
0 or 1 0

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:

name NVMMISC
  NONRLS=value
  TIMEOUT=value
  DSECTS=value
  DEFER=value
  COMMIT=value
  ERROR=value
  HFACTOR=value
  READINT=value
  SMARTS=value
  TVS=value

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.

Possible values Default value
YES/NO YES

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.

Possible values Default value
0 - 10 0

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.

Possible values Default value
YES/NO NO

DSECTS - List VSAM System DSECTs

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

Possible values Default value
YES/NO NO

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.

Possible values Default value
YES/NO NO

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

Possible values Default value
YES/NO YES

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.

Possible values Default value
0 - a value where a corresponding Natural error message is returned 100

READINT - Read Integrity for Upgrade Set

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

Possible values Default value
YES/NO NO

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.

Possible values Default value
YES/NO NO

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.

Possible values Default value
YES/NO NO

Top of page