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, * 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
|
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.
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=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
.
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=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.
|
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=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.