VSAM - Parameters for Natural for VSAM

This Natural profile parameter is used to specify the parameters for Natural for VSAM. It corresponds to the NTVSAM macro in the Natural parameter module, where, in addition, the macros NTVEXIT, NTVLSR and NTVTVSD are used.

Possible settings	See VSAM Parameter Syntax.
Default setting	See default values of keyword subparameters.
Dynamic specification	yes	The parameter `VSAM` can only be specified dynamically. In the Natural parameter module, use the macro `NTVSAM` and, in addition, the macros `NTVEXIT`, `NTVLSR` and `NTVTVSD`.
Specification within session	no

The following topics are covered:

VSAM Parameter Syntax
NTVSAM Macro Syntax
NTVEXIT Macro Syntax
NTVLSR Macro Syntax
NTVTVSD Macro Syntax
Keyword Subparameters
Examples of NTVSAM Macro
Examples of VSAM Parameter
PARM - Alternative Natural Parameter Module for VSAM

VSAM Parameter Syntax

The VSAM parameter is specified as follows:

VSAM=(keyword-subparameter=value,keyword-subparameter=,...)

See Keyword Subparameters.

NTVSAM Macro Syntax

The NTVSAM macro is specified as follows:

         NTVSAM BTSUPP=value,                                          *
               CLSUPP=value,                                           *
               DDMCHK=value,                                           *
               DDSWITE=value,                                          *
               DFBE=value,                                             *
               DFBN=value,                                             *
               ENADIS=value,                                           *
               ENAUNE=value,                                           *
               ETSUPP=value,                                           *
               FORMAT=(value1,value2),                                 *
               KEYLGH=value,                                           *
               OPSUPP=value,                                           *
               PATH=value,                                             *
               PSIGNF=value,                                           *
               RETRY=(value1,value2),                                  *
               RLS=value,                                              *
               ROLLSIZ=value,                                          *
               SFILE=value,                                            *
               TAFE=value,                                             *
               TAFN=value,                                             *
               TIMEOUT=value,                                          *
               TSAE=value,                                             *
               TVS=value,                                              *
               UPDL=value

See Keyword Subparameters.

Note:
The keyword subparameters EXIT, LSR and TVSD are not available in the NTVSAM macro. In the Natural parameter module, use the macros NTVSAM, NTVEXIT, NTVLSR and NTVTVSD instead.

NTVEXIT Macro Syntax

The NTVEXIT macro is specified as follows:

         NTVEXIT file-name,exit-name,workarea-size

For details, see EXIT - File User Exits.

NTVLSR Macro Syntax

The NTVLSR macro is specified as follows:

         NTVLSR file-name,subpool

For details, see LSR - Local Shared Resources Subpools.

NTVTVSD Macro Syntax

The NTVTVSD macro is specified as follows:

         NTVTVSD file-name,option

For details, see TVSD – Activate DFSMS Transactional VSAM Services.

Keyword Subparameters

BTSUPP - Support of BACKOUT TRANSACTION Statement

BTSUPP=value specifies whether BACKOUT TRANSACTION statements are executed or not.

Value	Explanation
`ON`	Each `BACKOUT TRANSACTION` is executed and translated into an appropriate `ROLLBACK` command. This is the default value.
`OFF`	`BACKOUT TRANSACTION` statements are ignored.

Note:
This subparameter is applicable only in TP and DFSMStvs environments where VSAM logging is supported.

CLSUPP - Support of CLOSE Call at Session Termination

CLSUPP=value specifies whether or not a CLOSE call is executed at session termination.

Value	Explanation
`ON`	Each `CLOSE` call is executed and translated into an appropriate `SYNCPOINT` command. This is the default value.
`OFF`	Each `CLOSE` call is ignored.

Note:
If a CLOSE is executed, Natural for VSAM forces an END TRANSACTION only in TP and DFSMStvs environments where VSAM logging is supported.

DDMCHK - Support of DDM Integrity

DDMCHK=value checks whether the file layout and, in consequence, the DDM has changed.

Value	Explanation
`ON`	DDM check enabled.
`OFF`	DDM check disabled. This is the default value.

Note:
The check is performed after each program termination at the NEXT level, through the Natural buffer pool. The DDMCHK subparameter 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

DDSWITE=value specifies the maximum number of entries in the DD/DLBL name switch buffer.

Value	Explanation
`0` up to `TAFE=value`	Maximum number of entries; that is `0` or a value in the range given by the maximum value specified in the `TAFE` subparameter.
`0`	This is the default value.

Note:
For details on switching DD names, see the application programming interface USR1047N in the SYSEXT Utility documentation.

DFBE - Number of Decoded Format Buffer Entries

DFBE=value specifies the initial number of entries in the table of decoded format buffers.

Value	Explanation
`1 - 1000`	Average number of fields.
`10`	This is the default value.

Notes:

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

DFBN=value specifies the average number of fields contained in an entry of the decoded format buffer table.

Value	Explanation
`1 - 1000`	Average number of fields.
`50`	This is the default value.

Notes:

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

ENADIS=value is used to enable disabled files.

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

Notes:

This subparameter only applies to CICS environments and is only honored by the first file access performed in the current Natural session.
If this subparameter 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

ENAUNE=value is used to enable disabled ("unenabled") files.

Value	Explanation
`ON`	For all "unenabled" files accessed during the session, an `EXEC CICS SET ENABLED` command is executed.
`OFF`	All "unenabled" files remain unenabled. This is the default value.

Notes:

This subparameter only applies to CICS environments and is only honored by the first file access performed in the current Natural session.
If this subparameter 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

ETSUPP=value specifies whether END TRANSACTION statements are executed or not.

Value	Explanation
`ON`	Each `END TRANSACTION` is executed and translated into an appropriate `SYNCPOINT` command. This is the default value.
`OFF`	`END TRANSACTION` statements are ignored.

Note:
ETSUPP is applicable only in TP and DFSMStvs environments where VSAM logging is supported.

EXIT - File User Exits

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 by the subparameter EXIT of profile parameter VSAM or the NTVEXIT macro in the Natural parameter module.

The subparameter EXIT is specified as follows:

EXIT=(dd-name,exit-name,workarea-size)

The macro NTVEXIT is specified as follows:

         NTVEXIT dd-name,exit-name,workarea-size

Where:

Value Explanation

Value	Explanation
`dd-name`	DD/DLBL/FCT name of the VSAM file to be accessed. Note: There is no default value.
`exit-name`	Name of the user exit. Note: There is no default value.
`workarea-size`	Optionally, the size of the user exit work area (in bytes) can be specified. Notes: A minimum size of 72 bytes is required, which corresponds to the size of the IBM standard register saved area; that is, 18 full words. The maximum value is 1024 bytes. The default value is 72.

dd-name

DD/DLBL/FCT name of the VSAM file to be accessed.

Note:
There is no default value.

exit-name

Name of the user exit.

Note:
There is no default value.

workarea-size

Optionally, the size of the user exit work area (in bytes) can be specified.

Notes:

A minimum size of 72 bytes is required, which corresponds to the size of the IBM standard register saved area; that is, 18 full words.
The maximum value is 1024 bytes.
The default value is 72.

Note:
All user exits must be either linked to the Natural parameter module or must be defined by means of CSTATIC or RCA techniques. For each file user exit, a separate definition with subparameter EXIT or macro NTVEXIT is required.

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

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.

FORMAT - Support of Record Formatting for STORE and UPDATE Statements

Note:
This section describes the new (extended) syntax of the FORMAT subparameter and, in addition, the old syntax, which is still supported for compatibility reasons.

New (Extended) Subparameter Syntax:

FORMAT=(value1,value2) 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.

Value		Explanation
`value1`	`ON`	VSAM records are formatted in accordance with the corresponding DDM definitions. This is the default.
`value1`	`OFF`	VSAM records are not formatted and fields that are not referenced contain binary zeros.
`value2`	`KEYS`	All VSAM keys are formatted in accordance with the DDM field type. This is the default.
`value2`	`NOKEYS`	All VSAM keys are not formatted.

Note:
Natural for VSAM system file records are always formatted; this cannot be changed.

The following value combinations are reasonable:

`FORMAT=(ON,NOKEYS)`	All fields are formatted, excepting the keys.
`FORMAT=(OFF,KEYS)`	Only the keys are formatted.

Old Subparameter Syntax:

The old subparameter syntax is still supported for compatibility reasons.

FORMAT=value supports the formatting of VSAM records referenced in a STORE or UPDATE statement.

Value	Explanation
`ON`	VSAM records are formatted in accordance with the corresponding DDM definitions. This is the default value.
`OFF`	VSAM records are not formatted and fields that are not referenced contain binary zeros.

Notes:

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.
Natural for VSAM system file records are always formatted; this cannot be changed.

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

KEYLGH=value specifies the length of VSAM keys used in Natural I/O statements.

Value	Explanation
`1 - 255`	Length of VSAM keys (in bytes) used in Natural I/O statements.
`32`	This is the default value.

Notes:

The maximum key length for a VSAM file is 255 bytes.
The value of this subparameter 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, and 126 bytes for the FSEC and Natural ISPF system files.

LSR - Local Shared Resources Subpools

This subparameter is only required if VSAM files are used as local shared resources.

Note:
This method results in a substantial increase of the performance of TSO and batch runs, and, at the same time, decrease the VSAM I/O rate. The definition of the usage of a local shared resources subpool per file is done by using by the subparameter LSR of profile parameter VSAM or the NTVLSR macro in the Natural parameter module.

The subparameter LSR is specified as follows:

LSR=(dd-name,subpool-number)

The macro NTVLSR is specified as follows:

         NTVLSR dd-name,subpool-number

Value	Explanation
`dd-name`	DD/DLBL/FCT name of the VSAM file to be accessed. There is no default value.
`subpool-number`	Subpool number (ID) between `0` and `15` for z/VSE or between `0` and `255` for z/OS; see also the relevant IBM VSAM documentation. There is no default value.

Up to 200 logical files are possible. For each file a separate definition with subparameter LSR or macro NTVLSR is required.

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

If you have defined base clusters with subparameter LSR or macro NTVLSR which contain path entries, all paths must also be defined with subparameter LSR or macro NTVLSR.

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 subparameter LSR or macro NTVLSR and contains references to an alternate index (AIX), all AIX files must also be defined with subparameter LSR or macro NTVLSR.

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-swappable, which is a prerequisite for ESO Hiperspaces.

OPSUPP - Support of Dynamic Open Calls

OPSUPP=value enables or disables the support of multiple different open calls within one session.

Value	Explanation
`ON`	Multiple different open calls are supported by calling the application programming interface `USR2008N`.
`OFF`	Multiple different open calls are not supported within one session. This is the default value.

Note:
For further information on application programming interfaces, see the SYSEXT Utility documentation.

PATH - Support of Path Processing

PATH=value is used to handle a secondary key as a path or as a native AIX file.

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`	Natural for VSAM checks whether the secondary keys are defined as paths or as AIXs in the VSAM catalog. This is the default value.

Notes:

If you use the VSAM system files FSEC and/or FSPOOL, you must not specify PATH=ON; specify either PATH=OFF or PATH=CHECK.
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

PSIGNF=value is used to handle the internal representation of positive signs of packed numbers.

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`	Natural for VSAM uses the DDM description in field `ZONES`. This is the default value.

RETRY - Support of RETRY Statement for an ON ERROR Clause

RETRY=(value1,value2) 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

Where:

Value	Explanation
`(value1,value2)`	`value1` applies to NAT3541, `value2` applies to NAT3520. Each value can be either `ON` or `OFF`.
`(OFF,OFF)`	This is the default value.

RLS - Support of Record-Level Sharing

RLS=value is used to enable, disable or check for the support VSAM record-level sharing (RLS) under z/OS, DFSMS Version 1.6 or higher.

Value	Explanation
`ON`	All files are opened in RLS mode.
`OFF`	All files are opened in non-RLS mode (NSR, LSR). This is the default value.
`CHECK`	All files are checked whether they are defined as SMS-managed data sets with RLS options; if they are, the file is opened in RLS mode, if not in non-RLS mode.

Notes:

This subparameter applies to z/OS only.
If TVS=ON is set (see subparameter TVS below) and no VSAM file has been defined in the NTVTVSD macro (see above), set RLS=CHECK to verify that the corresponding VSAM file has been defined as recoverable data set.

ROLLSIZ - Size of Area for Session Status Information

ROLLSIZ=value 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.

Value	Explanation
`0` or `1 - 10000`	Size of the area in bytes.
`550`	This is the default value.

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

SFILE - Support of VSAM System Files

SFILE=value is used to enable, disable or check for the support VSAM system files.

Value	Explanation
`ON`	Support of VSAM system files.
`OFF`	No support of VSAM system files. This is the default value.
`CHECK`	Checks whether the Natural system files `FNAT`, `FUSER` and `FDIC` are defined as Natural for VSAM Version 8.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

TAFE=value specifies the maximum number of DDMs per Natural session.

Value	Explanation
`0` or `1 - 1000`	Maximum number of DDMs.
`10`	This is the default value.

Notes:

Since it is possible to define several descriptors in one DDM, the TAFE subparameter has impact on the sizes of the FCT, FWA, OPV and TAF buffers (see Buffers for Memory Management) in the Natural for VSAM documentation.
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

TAFN=value specifies the average number of DDM fields contained in each entry in the table of accessed VSAM files.

Value	Explanation
`0` or `1 - 1000`	Maximum number of DDM fields.
`50`	This is the default value.

Note:
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

TIMEOUT=value 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.

Value	Explanation
`0` or `1 - 30`	Timeout period in seconds.
`0`	This is the default value.

Notes:

This subparameter only applies to z/OS CICS Version 5.3 or higher.
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 subparameter, 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.

TSAE - Maximum Number of Nested READ and FIND Statements

TSAE=value is used to set the maximum number of all nested READ and FIND statements.

Value	Explanation
`0` or `1 - 100`	Maximum number of all nested `READ` and `FIND` statements.
`10`	This is the default value.

TVS - Support of DFSMStvs

TVS=value is used to support DFSMS Transactional VSAM Services (DFSMStvs).

Value	Explanation
`ON`	Support of DFSMStvs.
`OFF`	No support of DFSMStvs. This is the default value.

Notes:

This subparameter applies to z/OS only.
If TVS is set to ON, the subparameters BTSUPP and ETSUPP are forced to ON. The subparameter RLS is only forced to ON if RLS has been set to OFF (RLS=CHECK is not forced to ON).

TVSD – Activate DFSMS Transactional VSAM Services

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.

This subparameter activates DFSMStvs by specifying the read integrity value of the ACB parameter RLSREAD. If specifying RSLREAD in subparameter TVSD or macro NTVTVSD, you do not have to adapt the JCL to activate DFSMStvs.

If you only set VSAM subparameter TVS=ON without specifying the corresponding VSAM file definition with TVSD or macro NTVTVSD, to activate DFSMStvs, you need to modify the JCL as described below. In this case, you must specify VSAM subparameter RLS=CHECK.

The subparameter TVSD is specified as follows:

TVSD=(dd-name,option)

The macro NTVTVSD is specified as follows:

         NTVTVSD dd-name,option

Where:

Value Explanation

dd-name

DD/DLBL/FCT name of the VSAM file to be accessed.

There is no default value.

option

NRI - No read integrity (dirty read).
CR - Consistent read.
CRE - Consistent read explicit.

There is no default value.

UPDL - Size of Update Table

UPDL=value specifies the size of the table used by the Natural interface to VSAM to save the fields of records read for subsequent updating.

Value	Explanation
`0` or `1 - 500000`	Size of table in bytes.
`8192`	Or `32768` if `SFILE=ON` is set. This is the default value.

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

Examples of NTVSAM Macro

         NTVSAM  RLS=ON,PATH=ON,KEYLGH=66
         NTVEXIT FILE1,EXIT1,400
         NTVEXIT FILE2,EXIT2

Examples of VSAM Parameter

VSAM=(RLS=ON,PATH=ON,KEYLGH=66,EXIT=(FILE1,EXIT1,400),EXIT=(FILE2,EXIT2))

PARM - Alternative Natural Parameter Module for VSAM

If you want to use an alternative Natural parameter module for Natural for VSAM, specify the name of this module with the PARM profile parameter and link the Natural I/O module for VSAM to this module. In addition, link all Natural for VSAM user exits defined in the NTVEXIT macro to this Natural parameter module.