VSAM - Parameters for Natural for VSAM

#### Search Results

Search

# 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,                                           *
                   MF=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` | `CLSUPP` | `DDMCHK` | `DDSWITE` | `DFBE` | `DFBN` | `ENADIS` | `ENAUNE` | `ETSUPP` | `EXIT` | `FORMAT` | `KEYLGH` | `MF` |`LSR` | `OPSUPP` | `PATH` | `PSIGNF` | `RETRY` | `RLS` | `ROLLSIZ` | `SFILE` | `TAFE` | `TAFN` | `TIMEOUT` | `TSAE` | `TVS` | `TVSD` | `UPDL`

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

1. For each active Natural I/O statement (`FIND`, `READ`, `UPDATE`, `STORE`) one entry is allocated in this table.
2. 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:

1. One entry is built for each Natural I/O statement (`FIND`, `READ`, `UPDATE`, `STORE`).
2. 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:

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

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

1. 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.
2. 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:

1. The maximum key length for a VSAM file is 255 bytes.
2. The value of this subparameter is used to calculate the size of the TSA table (Table of Sequential Access).
3. 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.

### MF - Multi-Fetch Factor

`MF=value` specifies the multi-fetch factor for VSAM I/O through Natural statements.

Value | Explanation
--- | ---
`1-28000` | Multi-fetch factor used during Natural I/O statements.
`0` | This is the default value.

Notes:

1. The multi-fetch factor is only applicable for batch processing.
2. The multi-fetch factor is only applicable to L1, L2, L3, and L9 calls.
3. The maximum value for a multi-fetch factor for a VSAM file is `28000`.

### 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 `255`. 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:

1. If you use the VSAM system files `FSEC` and/or `FSPOOL`, you must not specify `PATH=ON`; specify either `PATH=OFF` or `PATH=CHECK`.

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

1. This subparameter applies to z/OS only.
2. 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.

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

1. 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.
2. 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:

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

1. This subparameter applies to z/OS only.
2. 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.

### On this page

- 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