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.
Below is information on:
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 |
This variable contains the relative byte address of the record
currently being processed (ESDS files only).
This variable is not available for the FIND NUMBER and FIND FIRST statements. |
*NUMBER |
This variable contains the number of records which satisfied the
basic search criterion specified in the WITH clause, and before evaluation of
any WHERE criterion.
*NUMBER only contains a meaningful value if the EQUAL TO operator is used in the search criterion. With any other operator, *NUMBER will be 0 if no records have been found; any other value indicates that records have been found, but the value will have no relation to the number of records actually found. The same applies to *NUMBER with the FIND NUMBER statement. |
*COUNTER |
The number of times the processing loop has been entered.
This system variable is not available for the FIND FIRST statement. |
The FIND statement is only valid for key-sequenced (KSDS) and entry-sequenced (ESDS) VSAM datasets. For ESDS, an alternate index or a path for an alternate index must be defined. Relative record datasets (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 datasets. 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 |
This system variable 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 dataset 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.
