VSAM

#### Search Results

Search

# VSAM

This document covers the following topics:

- Documenting VSAM

- Generating DDMs from Predict VSAM Objects

- Using Natural for VSAM with Physical VSAM Files

- Using a Record Layout Concept

## Documenting VSAM

VSAM files and userviews can be documented in Predict with four different types of Predict file objects.

- File type V
  Physical VSAM file (master file)

- File type L
  Logical VSAM file (master file). This type can only be applied to VSAM files using KSDS (key-sequenced data set).

- File type W
  Userview of physical VSAM file

- File type R
  Userview of logical VSAM file. This type can only be applied to VSAM files using KSDS (key-sequenced data set).

The different file types are described in detail below.

### Physical VSAM file - Master File, File Type V

File type V is used for the documentation of a physical VSAM file in Predict.

Field definitions of a physical VSAM file have the same structure as definitions of a sequential file: the position of a field cannot be specified directly but is determined by its offset. The offset is calculated from the lengths of the fields already defined. Therefore DUMMY fields must be defined if space is to be left free between two fields (see examples below).

#### Example

    File ID..: EXAMPLE-V

    File-Type: V

    DD name..: EXAMDD

    L  Field-name     F Length   D    Offset   Remark

    ---------------------------------------------------------

    1  DUMMY1         A  10.0            0

    1  PRIM-KEY       A  15.0    P      10     Primary key

    1  DUMMY2         A   8.0           25

    1  ALT-KEY1       A   5.0    A      33     Alternate Key

    1  ALT-KEY2       B   7.0    A      38     Alternate Key

In this physical file definition, only the keys of the VSAM file (DD name: EXAMDD) are defined. This physical VSAM file is to be used in connection with the two logical VSAM files (EXAMPLE-L1 and EXAMPLE-L2) which are shown below.

The primary key field has the length 15.0. In the definition of logical VSAM files EXAMPLE-L1 and EXAMPLE-L2 below, these 15 places are used for the storage of the record type specifying VSAM prefix (length 9.0) and the primary key of the logical file (length 6.0). The DUMMY field (A 10.0) in the beginning ensures that the primary key field position matches the field definitions for the VSAM prefix and primary key in the logical files.

### Logical VSAM File - Master File, File type L

Logical VSAM files can be documented with file type L. A logical VSAM file defines a record layout for use in a physical VSAM file. By using logical VSAM files information objects of different types (and correspondingly different record layouts) can be stored in one physical VSAM file. See also Using a Record Layout Concept.

The following rules apply when defining a logical VSAM file:

- Before a logical VSAM file can be documented in Predict, the physical VSAM file to which the logical file belongs must have been documented.

- Position and length of fields in logical VSAM files are defined in the same way as in physical VSAM files.

- Records in a VSAM data set belonging to a logical file are identified by a VSAM prefix. For use with Natural for VSAM the field for the VSAM prefix has to start at the same position as the primary key in the physical VSAM file.

- Therefore the length of the field for the primary key in a logical file can be calculated as follows (see also examples below):

      length of primary key in logical file =
      length of primary key in physical file - length of VSAM prefix

- The value of the prefix can be specified explicitly for each logical file. If the VSAM prefix is to be specified with trailing blanks, each blank must be replaced with a special VSAM trailing blank character. This special character is defined with the Modify DDM defaults function.

- If no VSAM prefix is specified explicitly, the rightmost three digits of the file number are used as the VSAM prefix. The field defined for the prefix then has to have the length 3.0.

- Alternate keys must be defined with the same offset and length in a logical and the corresponding physical VSAM file.

#### Examples

    File ID.....: EXAMPLE-L1

    File-Type...: L

    Related file: EXAMPLE-V

    VSAM prefix.: RECTYPE-A

    L  Field-name     F Length   D   Offset   Remark

    -------------------------------------------------------

    1  FIELD-A-1      A   2.0           0

    1  FIELD-A-2      A   8.0           2

    1  VSAM-PREFIX    A   9.0          10     VSAM prefix

    1  PRIMKEY-A      A   6.0    P     19     Primary key

    1  FIELD-A-3      A   1.0          25

    1  FIELD-A-4      A   2.0          26

    1  FIELD-A-5      A   5.0          28

    1  ALT-KEY1       A   5.0    A     33     Alternate Key

    1  ALT-KEY2       B   7.0    A     38     Alternate Key

    1  FIELD-A-6      P   2.5          45

    1  FIELD-A-7      N   8.2          49

    File ID.....: EXAMPLE-L2

    File-Type...: L

    Related file: EXAMPLE-V

    VSAM prefix.: RECTYPE-B

    L  Field-name     F Length   D   Offset   Remark

    -------------------------------------------------------

    1  FIELD-B-1      B   6.0           0

    1  FIELD-B-2      A   4.0           2

    1  VSAM-PREFIX    A   9.0          10     VSAM prefix

    1  PRIMKEY-B      A   6.0    P     19     Primary key

    1  FIELD-B-3      A   3.0          25

    1  FIELD-B-5      A   5.0          28

    1  ALT-KEY1       A   5.0    A     33     Alternate Key

    1  ALT-KEY2       B   7.0    A     38     Alternate Key

    1  FIELD-B-6      N   5.3          45

    1  FIELD-B-7      B  18.0          53

The fields for storage of the VSAM prefix identifying the record type starts in the same position as the primary key in the corresponding physical VSAM file EXAMPLE-V above. The length of the fields VSAM-PREFIX and PRIMKEY-A (or PRIMKEY-B) together is 15.0 as is the length of the primary key in EXAMPLE-V above.

### File Type W and R - Userview of Physical / Logical VSAM File

File types W (userview of physical VSAM file) and R (userview of logical VSAM files) are used to document DDMs for Natural for VSAM. DDMs documented with Predict objects of this type are used to access parts of the VSAM file record structure defined in the related physical/logical VSAM file.

The following rules apply:

- The relationship between a userview and physical VSAM fields is established by the two-character field attribute short name. Therefore field names can be changed in userviews and the connection to the corresponding field definition of a file remains.

- Only fields which are defined in the physical/logical VSAM file may be defined in the userview.

- The position of the field in the userview is independent from the VSAM file layout.

- Before a DDM can be generated from a file object of type W or R, the DDM of the corresponding physical/logical VSAM file must have been generated.

## Generating DDMs from Predict VSAM Objects

When generating a DDM from a Predict object documenting a VSAM file, the file must already have been linked to a Predict database object of type V via "Contains FI". The database number is included in the DDM. The database number of this database must have been specified as a VSAM database in the Natural parameter module by the NTDB macro (e.g. NTDB VSAM,254).

## Using Natural for VSAM with Physical VSAM Files

When a DDM generated from a VSAM file layout is used by Natural for VSAM, this DDM must always be available at runtime (it is not incorporated into the program at compile time).

## Using a Record Layout Concept

Predict enables the use of different record layouts within a physical file (record layout concept) by the concept of logical VSAM files. When Natural for VSAM uses a DDM generated from a logical VSAM file only records with the VSAM prefix identifying that logical file will be returned.

When a logical VSAM file is used it is not necessary to define all fields in the physical VSAM file. Only the primary and alternate keys must be entered. The correct position of fields for keys must be ensured by insertion of DUMMY fields.

If Natural for VSAM is used in connection with logical VSAM files the rules outlined above have to be followed. This is especially true for the following point:

- The VSAM prefix must be a fixed-length constant and it must precede the primary key in the logical file. Therefore the VSAM prefix plus primary key together in the logical file must have the same position and length as the primary key in the physical file.

### Using a Record Layout Concept Without Logical VSAM Files

If the record type is not a constant or not the first part of the primary key, the logical VSAM files may not be used to generate DDMs for Natural for VSAM. In this case the following actions have to be taken if different record layouts are to be used in the same VSAM data set:

- The layout of the different record type structures must be specified as multiple physical VSAM files containing the same DD name and therefore pointing to the same VSAM data set.

- Check in the Natural program after the `FIND/READ` statement that the DDM corresponds to the record type. When a record does not correspond to the DDM, the record can be read again using the correct DDM. In these circumstances it is sometimes helpful to know the current record length. Natural for VSAM offers a subprogram which returns the record length.

### On this page

- Documenting VSAM
- Generating DDMs from Predict VSAM Objects
- Using Natural for VSAM with Physical VSAM Files
- Using a Record Layout Concept