IMS Secondary Indexing: Complete Guide with Examples

IMS secondary indexes provide alternate access paths to an IMS database — allowing programs to retrieve segments by fields other than the primary root key. Without secondary indexes, every retrieval must start at the root by its primary key. Secondary indexes enable, for example, finding a customer by phone number or retrieving accounts by branch code.

Why Secondary Indexes?

The IMS hierarchical model is optimised for top-down root-key access. But real applications often need to find data by other attributes:

Find a customer by social security number (when your root key is customer ID)
Retrieve all accounts at a specific branch
Look up a transaction by check number

Without secondary indexes, these queries require a full sequential scan of the entire database — unacceptable for high-volume online transactions.

How IMS Secondary Indexes Work

An IMS secondary index is itself a separate IMS database (of type INDEX or HIDAM) containing one entry per occurrence of the indexed field value. Each entry points back to the target segment in the primary database.

The index database contains:

A pointer segment with the index key value and a physical pointer to the target segment
The pointer segments are maintained in sorted order by index key (using VSAM KSDS)

When a program does a GU using an SSA on the secondary index key, IMS:

Looks up the index database for the key value
Follows the pointer to the target segment in the primary database
Returns the target segment to the program as if it were found directly

Defining a Secondary Index in the DBD

Secondary indexes are defined in the primary database DBD using the LCHILD and XDFLD macros:

hlasm

DBD   NAME=CUSTDB,ACCESS=HIDAM
*
DATASET DD1=CUSTDB01,DEVICE=3390,SIZE=4096
*
* Root segment
SEGM  NAME=CUSTOMER,BYTES=200,FREQ=1000
FIELD NAME=(CUST-KEY,SEQ,U),BYTES=10,START=1,TYPE=C
FIELD NAME=CUST-NAME,BYTES=40,START=11,TYPE=C
FIELD NAME=CUST-SSN,BYTES=9,START=51,TYPE=C
FIELD NAME=CUST-PHONE,BYTES=15,START=60,TYPE=C
*
* Define the secondary index on SSN
LCHILD NAME=(CUSTSSNI,CUSTSSNI),POINTER=INDX
XDFLD NAME=SSN-INDEX,SRCH=CUST-SSN,DDATA=(CUST-KEY)

Key macros:

LCHILD — identifies the index database name and type. POINTER=INDX tells IMS this is a secondary index pointer.

XDFLD — defines the indexed field:

NAME — the name of the index field (referenced in SSAs)
SRCH — the source field in the segment to be indexed (CUST-SSN)
DDATA — additional data copied to the index entry (optional, for access without returning to the primary)

The Index Database DBD

The secondary index database has its own DBD:

hlasm

DBD   NAME=CUSTSSNI,ACCESS=INDEX
*
DATASET DD1=CUSTSSNI,DEVICE=3390,SIZE=2048
*
SEGM  NAME=CUSTSSNI,BYTES=9,PARENT=0
FIELD NAME=(SSN-INDEX,SEQ,U),BYTES=9,START=1,TYPE=C
*
DBDGEN
FINISH
END

Accessing via Secondary Index in a Program

To use a secondary index, the program's PSB must reference the index database:

hlasm

PCB TYPE=DB,DBDNAME=CUSTDB,KEYLEN=10,PROCOPT=G,
    SYSSEQ=CUSTSSNI
    SENSEG NAME=CUSTOMER,PARENT=0

The SYSSEQ=CUSTSSNI parameter tells IMS to use the SSN index database as the processing sequence for this PCB.

In the COBOL program, retrieve by SSN:

cobol

MOVE 'SSN-INDEX' TO SSA-SEG-NAME.
MOVE '('         TO SSA-BEGIN.
MOVE 'SSN-INDEX' TO SSA-FIELD-NAME.
MOVE '='         TO SSA-REL-OP.
MOVE '123456789' TO SSA-FIELD-VALUE.
MOVE ')'         TO SSA-END.

CALL 'CBLTDLI' USING GU-FUNC
                     CUSTOMER-PCB
                     CUSTOMER-IO-AREA
                     CUSTOMER-SSA.

IMS navigates through the SSN index database and returns the CUSTOMER segment with SSN '123456789'.

Maintaining Secondary Indexes

Secondary indexes are maintained automatically by IMS. When a program inserts, updates, or deletes a segment containing an indexed field, IMS automatically updates the corresponding index database entries. Programs do not manage index maintenance manually.

This automatic maintenance has a performance cost — every update to an indexed segment requires an additional update to the index database. High-update databases with many secondary indexes can see significant overhead.

Frequently Asked Questions

Q: How many secondary indexes can an IMS database have? There is no fixed IMS limit, but performance degrades with each additional index because every update to the indexed segment must update all index databases. In practice, most IMS databases have 1–5 secondary indexes. More than that is a design smell suggesting the database is being used for query patterns it was not designed for.

Q: Can a secondary index be on a non-root segment? Yes — IMS secondary indexes can be defined on any segment in the hierarchy, not just the root. An index on a dependent segment still returns access from the root, but allows retrieval by the dependent segment's field value. The access path navigates from the indexed segment back up to the root and then presents the hierarchy to the program.

Q: What is a sparse secondary index in IMS? A sparse index only includes entries for segment occurrences where the indexed field meets certain criteria. For example, indexing only ACCOUNT segments with status = 'ACTIVE'. Sparse indexes are defined using the SRCH parameter on XDFLD with qualification. They save index space and maintenance overhead when only a subset of occurrences need alternate-key access.

Part of the IMS Mastery Course — Module 9 of 22.