This section describes special considerations on Natural statements and Natural transaction logic when used with VSAM.
The Natural statements used to access VSAM files are a subset of those provided with the Natural language. No new statements are needed to access a VSAM file, since each Natural statement performs the same function regardless of the database management system or access method used. Therefore, programs written for VSAM files can also be used to access Adabas databases.
The Natural interface to VSAM has no built-in transaction logic and uses the one of the environment it is running in. This leads to different results depending on the environment.
This section covers the following topics:
This section mainly consists of information also contained in the Natural Statements documentation, where each Natural statement is described in detail, including notes on VSAM usage where applicable. Summarized below are the particular points a programmer has to bear in mind when using Natural statements with VSAM.
Note
Since the Natural compiler does not check if a program adheres to the restrictions
imposed by the Natural interface to VSAM, VSAM-specific programming errors concerning the
use of Natural statements only occur when the program is executed.
Any Natural statement not mentioned in this section can be used with VSAM without restrictions.
The BACKOUT TRANSACTION
statement is used to back out all database updates performed during the current user
logical transaction. This statement also releases all records held during the
transaction.
If used with Natural for VSAM, the BACKOUT TRANSACTION statement releases
records held in the UPD table. It does not back out transactions unless Natural is
running under a TP monitor or DFSMStvs which supports dynamic transaction backout (for
example, CICS). In this case, a ROLLBACK to the last
SYNCPOINT is issued.
The DELETE statement is used
to delete a record from a VSAM file.
The use of the DELETE statement places each record selected in the
corresponding FIND or READ statement in hold status.
The DELETE statement is not valid for VSAM entry-sequenced data sets
(ESDS).
The END TRANSACTION
statement is used to indicate the end of a logical transaction. A logical transaction is
the smallest logical unit of work (as defined by the user) which must be performed in
its entirety to ensure that the information contained in the VSAM file is logically
consistent.
The END TRANSACTION statement also releases all records placed in hold
status during the transaction.
An END TRANSACTION only releases records held in the UPD table unless
Natural is running under a TP monitor or DFSMStvs which supports dynamic transaction
backout (for example, CICS). In this case, an END TRANSACTION statement
causes a SYNCPOINT to be issued.
The FIND statement is used to
select a set of records from the VSAM file based on a search criterion consisting of
fields defined as descriptors (keys).
The WITH clause is used to specify the search criterion consisting of key
fields (descriptors) defined in the VSAM file.
Only VSAM key fields can be used.
The number of records to be selected as a result of a WITH clause can be limited by
specifying the keyword LIMIT together with a limit value (operand
1) expressed as a numeric constant or a user-defined variable.
The limit value is enclosed within parentheses. If the number of records selected
exceeds the limit value, the program is terminated with an error message.
The descriptor must be defined in a VSAM file as a VSAM key field. In a DDM, it is
marked with P for primary key, S for primary
sub/superdescriptor, X for alternate sub/superdescriptor or A
for alternate key (see Edit
DDM in the section Operation, and the
SYSDDM Utility as
described in the Natural Editors documentation).
The formats of the descriptor and the search value must be compatible.
The following Natural system variables are available with the FIND
statement:
| Variable | Content |
|---|---|
*ISN |
The system variable *ISN contains the relative byte
address of the record currently being processed (ESDS files only).
This
variable is not available for the |
*NUMBER |
The system variable *NUMBER contains the number of
records which satisfied the basic search criterion specified in the WITH clause, and
before evaluation of any WHERE criterion.
The same applies to |
*COUNTER |
The system variable *COUNTER contains the number of
times the processing loop has been entered.
This system variable is not
available for the |
The FIND statement is only valid for key-sequenced (KSDS) and
entry-sequenced (ESDS) VSAM data sets. For ESDS, an alternate index or a path for an
alternate index must be defined. Relative record data sets (RRDS) are not allowed, since
they do not contain any key fields (descriptors).
The GET statement is used to read
a record with a given VSAM record number. For an ESDS file, the record number (ISN)
would be the relative byte address (RBA); for RRDS and VRDS files, it would be the
relative record number (RRN). The GET statement does not initiate a
processing loop. As a result, a subsequent UPDATE or DELETE statement will not be processed and Natural returns
a corresponding error message.
For ESDS, the RBA must be contained in a user-defined variable (numeric format) or specified as an integer constant. The same rules apply for RRDS and VRDS with the exception that the RRN must be provided instead of the RBA.
The GET SAME statement
applies to VSAM ESDS, RRDS, and VRDS only (see also the GET statement
above).
The GET TRANSACTION DATA
statement is not applicable to the Natural interface to VSAM.
The HISTOGRAM statement is
used to read the values of a field which is defined as a descriptor, subdescriptor, or
superdescriptor.
The HISTOGRAM statement initiates a processing loop, but does not provide
access to any fields other than the field specified in the statement.
Only VSAM key fields can be used as descriptors.
The following Natural system variable is available with the HISTOGRAM
statement:
| Variable | Content |
|---|---|
*NUMBER |
When used in conjunction with a KSDS primary key or a unique alternate
index, *NUMBER is always 1.
|
Note
The *ISN system variable is not available for the
Natural interface to VSAM.
When used with VSAM, the HISTOGRAM statement is only valid for KSDS and
ESDS data sets. For ESDS, an alternate index or a path for an alternate index must be
defined.
The values are read directly from the VSAM index and are returned in ascending or descending value sequence.
The READ statement is used to
read records from a VSAM file. The records can be retrieved in the value sequence
(ascending or descending) of a descriptor (key) field. The READ sequence
initiates a processing loop.
IN LOGICAL SEQUENCE is
used to read records in the order of the values of a descriptor (key). If
LOGICAL is specified with a descriptor, the records are read in the value
sequence of the descriptor. A descriptor can be used for sequence control. A descriptor
within a periodic group cannot be used. If LOGICAL is specified without a
descriptor, the records are read in the default descriptor sequence, as defined in the
DDM.
WITH REPOSITION
can be used for skip-sequential processing inside the active loop, the new position must
be defined as the new start value for the loop and must reset the system variable
*COUNTER.
IN LOGICAL SEQUENCE is only valid for KSDS with primary and alternate keys
defined and ESDS with alternate keys defined. A subdescriptor or superdescriptor can be
used for sequence control, too.
The following Natural system variables are available with the READ
statement:
| Variable | Content |
|---|---|
*ISN |
The system variable *ISN contains either the RRN (for
RRDS or VRDS) or the RBA (for ESDS) of the current record.
|
*COUNTER |
This system variable contains the number of times the processing loop has been entered. |
Records can also be retrieved IN
PHYSICAL SEQUENCE, which is used to read records in the order in
which they are physically stored in a database. It is only valid for VSAM ESDS, RRDS and
VRDS. This is the default sequence.
STARTING WITH ISN
can be used as start value for the loop in ascending or descending physical
sequence.
BY ISN is used to read
records in RBA and RRN order for ESDS, RRDS and VRDS files, respectively.
The STORE statement is used to
add a record to a database.
A unique value for the primary-key field or the alternate-index field must be provided if the data set is defined with a primary key or a unique alternate index.
The USING/GIVING
NUMBER clause is only valid for RRDS or VRDS, in which case the
ISN corresponds to the relative record number.
USING/GIVING NUMBER is used to store a record with a user-supplied RRN. If
a record with the specified RRN already exists, an error message is returned and the
execution of the program is terminated, unless ON ERROR processing was specified.
The Natural system variable *ISN contains the RRN assigned to the new
record as a result of the STORE
statement execution. A subsequent reference to *ISN must
include the statement number of the related STORE statement.
*ISN is available for RRDS or VRDS files only.
The UPDATE statement is used
to update one or more fields of a record in a database. The record to be updated must
have been previously selected using a FIND or READ statement.
The primary key cannot be updated.
Natural for VSAM uses the transaction logic of the environment it is running in. Thus,
the results of the Natural END
TRANSACTION and BACKOUT TRANSACTION statements (see also the relevant
sections in Natural Statements with VSAM) differ depending on the actual environment:
Since VSAM itself has no transaction logic, there is no transaction logic available if
Natural is working in a native VSAM environment. This is the case under Com-plete, TSO,
and in batch mode, which means when NVSMISC is the I/O module in use.
With NVSMISC, END
TRANSACTION and BACKOUT
TRANSACTION statements do not return any error messages, but are
ignored by the Natural interface to VSAM.
Under CICS, VSAM files can be defined as "recoverable resources" or for
RLS as "recoverable sphere", all of which are synchronized by CICS using
the concept of "logical units of work" (LUWs). An LUW ends if a
SYNCPOINT command is issued or if the CICS task is
terminated. For details, refer to the relevant IBM literature on CICS.
Below is information on:
For CICS, the I/O module NVSCICS is a normal command-level application
program. It transfers END
TRANSACTION and BACKOUT
TRANSACTION statements to the NATCICS driver which
issues the EXEC CICS SYNCPOINT and EXEC CICS
ROLLBACK commands. If an error occurs in a Natural session with
uncommitted updates and no error transaction is supplied, Natural itself triggers the
interface to VSAM to issue a ROLLBACK command.
If a SYNCPOINT or ROLLBACK
command fails (for example, when CICS answers with a ROLLEDBACK condition
to a SYNCPOINT request), error messages NAT3544 or NAT3545 are
returned.
If the Natural session runs in CICS conversational mode, the LUW is not ended by a
terminal I/O. Natural runs in conversational mode if either the Natural parameter
PSEUDO=OFF has been
specified or Natural itself has determined that pseudo-conversational processing is
not possible.
Since terminal I/Os do not disturb the transaction logic of an application as long as Natural is running in conversational mode, a program like the following one would work without problems:
READ vsam-file UPDATE INPUT ... END-READ BACKOUT TRANSACTION
If the Natural session is running in pseudo-conversational mode, each terminal I/O
terminates the CICS task, thus implicitly performing a
SYNCPOINT. Therefore, the impact of a BACKOUT TRANSACTION statement, that
is of an EXEC CICS SYNCPOINT ROLLBACK command, only goes
back to the most recent terminal I/O. The example program above would, therefore, end
with error message NAT3548, because it is not possible to roll back all the
updates.
Note
Keep in mind that all messages of the Natural interface to VSAM are issued at
runtime only, since the Natural compiler is not able to detect this kind of logical
error.
DFSMS Transactional VSAM Services (DFSMStvs) provides the same features CICS provides:
forward and backward recovery logging, backout processing and a two-phase commit
process. An LUW ends if the RRS (Resource Recovery Service) call
SRRCMIT or SRRBACK is issued
(END TRANSACTION or
BACKOUT TRANSACTION). For
details, refer to the relevant IBM literature on DFSMStvs and RRS.
