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:
The VSAM
parameter is specified as follows:
VSAM=(keyword-subparameter=value,keyword-subparameter=,...) |
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
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.
The NTVEXIT
macro is specified as follows:
NTVEXIT file-name,exit-name,workarea-size
For details, see EXIT - File User Exits.
The NTVLSR
macro is specified as follows:
NTVLSR file-name,subpool
For details, see LSR - Local Shared Resources Subpools.
The NTVTVSD
macro is specified as follows:
NTVTVSD file-name,option
For details, see TVSD – Activate DFSMS Transactional VSAM Services .
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=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=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=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=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=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:
FIND
, READ
, UPDATE
, STORE
) one entry is allocated in this table.
DFBE
or DFBN
, take into consideration that the
allocated storage area size is obtained by multiplying these values and not by adding
them.
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:
FIND
, READ
, UPDATE
, STORE
).
DFBE
or DFBN
, take into
consideration that the allocated storage area size is obtained by multiplying these
values and not by adding them.
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:
OFF
and the file has not been
enabled, the NAT3516 error message must follow the first file access.
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:
OFF
and the file has not been
enabled, the NAT3539 error message must follow the first file access.
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.
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: |
exit-name |
Name of the user exit.
Note: |
workarea-size |
Optionally, the size of the user exit work area (in bytes)
can be specified.
Notes:
|
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.
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
|
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.
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.
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. |
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:
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:
FNAT
, FUSER
, FDIC
and FSPOOL
files, and 126 bytes for the FSEC
and Natural ISPF system files.
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:
28000
.
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=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=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:
FSEC
and/or FSPOOL
,
you must not specify PATH=ON
; specify either PATH=OFF
or
PATH=CHECK
.
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=(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 |
(OFF,OFF) |
This is the default value. |
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:
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=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=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=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:
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.
TAFE
or TAFN
, take into consideration that the
allocated storage area size is obtained by multiplying these values and not by adding
them.
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=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:
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=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=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:
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
).
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 |
There is no default value. |
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.
NTVSAM RLS=ON,PATH=ON,KEYLGH=66 NTVEXIT FILE1,EXIT1,400 NTVEXIT FILE2,EXIT2
VSAM=(RLS=ON,PATH=ON,KEYLGH=66,EXIT=(FILE1,EXIT1,400),EXIT=(FILE2,EXIT2))
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.