How a secondary index is stored

Secondary index databases contain root segments only.

They are stored in a single VSAM KSDS if the key in the pointer segment is unique. If keys are not unique,
an additional data set must be used (an ESDS) to store segments containing duplicate keys. (KSDS data
sets do not allow duplicate keys.) Duplicate keys exist when, for example, a secondary index is used to
retrieve courses based on student name. As shown in the following figure, several source segments could
exist for each student.

Figure 1. Examples of source segments for each student

Each pointer segment in a secondary index is stored in one logical record. A logical record containing a
pointer segment is shown in the following figure.

Figure 2. Example of a logical record containing a pointer segment

Page 1
A HALDB secondary index record is shown in the following figure.

Figure 3. Secondary index entry for HALDB

The format of the logical record is the same in both a KSDS and ESDS data set. The pointer field at the
beginning of the logical record exists only when the key in the data portion of the segment is not unique. If
keys are not unique, some pointer segments will contain duplicate keys. These pointer segments must be
chained together, and this is done using the pointer field at the beginning of the logical record.

Pointer segments containing duplicate keys are stored in the ESDS in LIFO (last in, first out) sequence.
When the first duplicate key segment is inserted, it is written to the ESDS, and the KSDS logical record
containing the segment it is a duplicate of points to it. When the second duplicate is inserted, it is inserted
into the ESDS in the next available location. The KSDS logical record is updated to point to the second
duplicate. The effect of inserting duplicate pointer segments into the ESDS in LIFO sequence is that the
original pointer segment (the one in the KSDS) is retrieved last. This retrieval sequence should not be a
problem, because duplicates, by definition, have no special sequence.

Page 2
VSAM data sets: KSDS, ESDS, RRDS
CICS® supports access to the following types of data set, Key-sequenced data set (KSDS), Entry-
sequenced data set (ESDS) and Relative record data set (RRDS) (both fixed and variable record lengths).

VSAM data sets are held on direct-access storage devices (DASD) auxiliary storage. VSAM divides its data
set storage into control areas (CA), which are further divided into control intervals (CI). Control intervals
are the unit of data transmission between virtual and auxiliary storage. Each one is of fixed size and, in
general, contains a number of records. A KSDS or ESDS can have records that extend over more than one
control interval. These are called spanned records.

Key-sequenced data set (KSDS)

A key-sequenced data set has each of its records identified by a key. (The key of each record is a field
in a predefined position within the record.) Each key must be unique in the data set.

When the data set is initially loaded with data, or when new records are added, the logical order of the
records depends on the collating sequence of the key field. This also fixes the order in which you retrieve
records when you browse through the data set.

To find the physical location of a record in a KSDS, VSAM creates and maintains an index. This relates the
key of each record to the record's relative location in the data set. When you add or delete records, this
index is updated accordingly.

With releases of DFSMS/MVS 1.4 and later, a data set can be greater than 4 GB in size if it is defined as
extended format and extended addressability in the storage class. CICS supports, in both RL and non-RLS
mode, KSDS data sets that are defined with these extended attributes.

Page 3
Entry-sequenced data set (ESDS)

An entry-sequenced data set is one in which each record is identified by its relative byte address
(RBA).

Records are held in an ESDS in the order in which they were first loaded into the data set. New records
added to an ESDS always go after the last record in the data set. You cannot delete records or alter their
lengths. After a record has been stored in an ESDS, its RBA remains constant. When browsing, records are
retrieved in the order in which they were added to the data set.

A standard RBA is an unsigned 32 bit number. The use of a 32 bit RBA means that a standard ESDS cannot
contain more than 4 GB of data. However, there is a different ESDS that supports 64 bit extended
relative byte addresses ( XRBA s) and which is therefore not subject to the 4 GB limit. This type of
ESDS is called an "extended format, extended addressing ESDS data set" . For brevity, we will refer to it as
an "extended addressing ESDS" , or as an " extended ESDS " . From CICS TS for z/OS®, Version 3.2
onwards, CICS supports 64 bit XRBAs and extended ESDS data sets.

Relative record data set (RRDS)

A relative record data set has records that are identified by their relative record number (RRN). The first
record in the data set is RRN 1, the second is RRN 2, and so on.

Records in an RRDS can be fixed or variable length records, and the way in which VSAM handles the data
depends on whether the data set is a fixed or variable RRDS. A fixed RRDS has fixed-length slots
predefined to VSAM, into which records are stored. The length of a record on a fixed RRDS is always equal
to the size of the slot. VSAM locates records in a fixed RRDS by multiplying the slot size by the RRN (which
you supply on the file control request), to calculate the byte offset from the start of the data set.

A variable RRDS, can accept records of any length up to the maximum for the data set. In a variable RRDS
VSAM locates the records with an index.

A fixed RRDS generally offers better performance. A variable RRDS offers greater function.

Page 4
With releases of DFSMS/MVS 1.5 and later, a data set can be greater than 4 GB in size if it is defined as
extended format and extended addressability in the storage class. CICS supports access to extended RRDS
or VRRDS data sets if you use an RRN that can be specified in a four byte RRN field to access the records
that reside beyond the 4 GB boundary.

Empty data sets

An empty data set is a data set that has not yet had any records written to it. VSAM imposes several
restrictions on an empty data set that is opened in non-RLS access mode. However, CICS hides all these
restrictions from you, allowing you to use an empty data set in the same way as a data set that contains
data, regardless of the access mode.

VSAM alternate indexes

Sometimes you want to access the same set of records in different ways. For example, you can have
records in a personnel data set that have as their key an employee number. No matter how many Smiths
you have, each of them has a unique employee number. Think of this as the primary key.

If you were producing a telephone directory from the data set, you would want to list people by name
rather than by employee number. You can identify records in a data set with a secondary (alternate) key
instead of the primary key described previously. So the primary key is the employee number, and the
employee name is the alternate key. Alternate keys are just like the primary key in a KSDS—fields of
fixed length and fixed position within the record. You can have any number of alternate keys per base file
and, unlike the primary or base key, alternate keys need not be unique.

To continue the personnel example, the employee's department code might be defined as a further
alternate key.

VSAM allows KSDS and ESDS (but not RRDS or extended ESDS ) data sets to have alternate keys. When
the data set is created, one secondary or alternate index is built for each alternate key in the record and
is related to the primary or base key. To access records using an alternate key, you must define a further
VSAM object, an alternate index path . The path then behaves as if it were a KSDS in which records are
accessed using the alternate key.

Page 5
When you update a record by way of a path, the corresponding alternate index is updated to reflect the
change. However, if you update the record directly by way of the base, or by a different path, the alternate
index is only updated if it has been defined to VSAM (when created) to belong to the upgrade set of the
base data set. For most applications, you probably want your alternate index to be in the upgrade set.

A CICS application program disregards whether the file it is accessing is a path or the base. In a running
CICS system, access to a single base data set can be made by way of the base and by any of the paths
defined to it, if each access route is defined to CICS.

It is also possible for a CICS application program to access a file that has been directly defined as an
alternate index rather than a path. This results in index data being returned to the application program
rather than file data. This operation is not supported for files opened in record-level sharing (RLS) mode.

 Accessing files in RLS mode

Record-level sharing (RLS) is a VSAM function, provided by DFSMS Version 1 Release 3 and later releases,
that enables VSAM data to be shared, with full update capability, between many applications running in
many CICS regions.

Creating table spaces for full-function databases

When defining a new table space (data set group), use the CREATE TABLESPACE statement. Some full-
function databases require that you define table spaces, some full-function databases do not require it. For
example, this is true for the DBs that are defined using the Gen utilities.

The following rules apply depending on the database access type you are defining.

For HSAM and SHSAM:

 You can define only one table space (data set group).
 The ddname of an input data set, which is the table space name provided on the CREATE
TABLESPACE statement, is used by the application to retrieve data from the database.
 The ddname of an output data set, which is the name provided on the OUTPUT keyword on the
CREATE TABLESPACE statement, is used when loading the database.

Page 6
For HISAM and SHISAM:
 You can define only one table space (data set group).
 The ddname of one VSAM key sequenced data set (KSDS) and one VSAM entry sequenced data set
(ESDS).
For HDAM and HIDAM:
 One to 10 data set groups.
 You can define how free space is to be distributed in each data set group.
 The ddname of an OSAM or ESDS data set, which is the name provided on the CREATE TABLESPACE
statement, represents the data set group.
For index, a primary HIDAM index must specify:
 One table space (data set group). You must specify the ddname of one KSDS as the name on the
CREATE TABLESPACE statement.
A full-function secondary index must specify:
 One data set group. If all index pointer table keys are unique, you must specify the ddname of one
KSDS. If index pointer table keys are non-unique you must specify the ddnames of one KSDS and one
ESDS.

For logical, there are no physical table spaces or data set groups for a logical database. The CREATE
TABLESPACE statement is invalid when defining a logical database

Page 7