The Natural parameters in a VSAM environment are defined in two locations:
the Natural standard parameters, contained in the Natural parameter
module NATPARM
; see Using a Natural Parameter
Module in the Natural Operations
documentation,
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).
This section covers the following topics:
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).
VSIZE=72, NTDB VSAM,vsam-dbid
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
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.
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.
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:
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. |
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.
|
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.
|
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. |
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 |
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 |
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 |
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. |
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. |
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.
|
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.
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.
Possible values | Default value |
---|---|
1 - 255 (bytes)
|
32 |
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.
|
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).
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 .
|
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) |
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. |
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 |
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).
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 |
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 |
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 |
This parameter is used to set the maximum number of all nested
READ
and
FIND
statements.
Possible values | Default value |
---|---|
0 - 100 |
10 |
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. |
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.
|
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:
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.
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 |
All user exits must be linked to the front-end.
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.
A sample user exit NVSEX01
is provided on the
installation tape.
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.
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 |
|
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
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:
The NVSCICS
module is required for CICS under z/OS or
z/VSE. The module contains the following parameter:
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.
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.
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 |
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 |
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 |
The DSECTS
parameter specifies whether the VSAM
system DSECTs are to be listed or not.
Possible values | Default value |
---|---|
YES /NO |
NO |
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.
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.
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 |
The READINT
parameter specifies whether read
integrity for an upgrade set should be granted or not.
Possible values | Default value |
---|---|
YES /NO |
NO |
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 |
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 |