VSAM Path

A VSAM path is the link between an alternate index (AIX) and its base cluster that lets applications access the base cluster by the alternate key. The path is a catalog entry only—it holds no data. You define it with DEFINE PATH, giving the path a name and specifying which AIX it uses (PATHENTRY). In JCL and in programs you then use the path name when you want to read or update the base cluster by alternate key. This page explains what a path is, how it differs from the AIX itself, how to define and use it, and why you need it for alternate-key access.

What Is a Path?

A path is a catalog object that connects an alternate index to its base cluster for access. When you create an AIX with DEFINE ALTERNATEINDEX, you create the index structure and relate it to a base cluster (RELATE). That tells the system which base cluster the AIX is built from, but it does not by itself let an application open the base cluster "through" the AIX. The path does that. DEFINE PATH creates an entry in the catalog that says: "This path name refers to this AIX." When a program opens the path name, the system opens both the AIX and the base cluster and uses the AIX to resolve alternate-key requests to base cluster records. So the path is the access route: you use the path name in DSN= and in the program, and you get base cluster data in the order or by the key of the alternate index.

The path itself contains no data. It is not a cluster and has no DATA or INDEX components. It is only a name and a pointer to the AIX. The AIX holds the alternate key values and pointers to the base cluster; the base cluster holds the actual records. The path is the catalog entry that ties them together for I/O.

Path vs Alternate Index

It is easy to confuse the path with the AIX. The AIX is a full VSAM object: a cluster with DATA and INDEX components, space on disk, and catalog entries for the cluster and its components. The path is a single catalog entry with a name and a PATHENTRY (the AIX name). DEFINE ALTERNATEINDEX creates the AIX; DEFINE PATH creates the path. You need both to use alternate-key access: the AIX to hold the keys and pointers, and the path to give you a name to open that connects the AIX to the base cluster.

If you only define the AIX and never define a path, the AIX exists and you can run BLDINDEX to fill it, but there is no path name to open. Applications that open the base cluster by its normal name get primary-key or sequential access; they do not use the AIX. To get alternate-key access, you must define a path and then open the path name. So the path is required for using the AIX in applications.

DEFINE PATH Syntax

DEFINE PATH has two main parameters: NAME and PATHENTRY. NAME is the path name—the name you will use in JCL (DSN=) and in the program when you want alternate-key access. PATHENTRY is the name of the alternate index cluster (the AIX name you specified in DEFINE ALTERNATEINDEX). The path name and the AIX name are usually different. A common convention is to use a name like base.cluster.AIXNAME.PATH or base.cluster.PATH.ALTX so that it is clear this is a path and which AIX it uses.

1
2
3
4
  DEFINE PATH -
    NAME(USERID.EMPL.DEPTAIX.PATH) -
    PATHENTRY(USERID.EMPL.DEPTAIX)
 

Here NAME(USERID.EMPL.DEPTAIX.PATH) is the path name that applications will use. PATHENTRY(USERID.EMPL.DEPTAIX) is the AIX cluster name. The path entry in the catalog links the path name to that AIX; the AIX is already related to the base cluster (e.g. USERID.EMPL.KSDS) via the RELATE you used when defining the AIX. So when you open USERID.EMPL.DEPTAIX.PATH, the system knows to use the AIX USERID.EMPL.DEPTAIX to access the base cluster USERID.EMPL.KSDS by the alternate key (e.g. department ID).

When to Define the Path

You define the path after you have defined the AIX and built it with BLDINDEX. The usual order is: (1) DEFINE ALTERNATEINDEX, (2) DEFINE PATH, (3) BLDINDEX. Some documentation shows DEFINE PATH after BLDINDEX; either order can work because the path is only a catalog link. What matters is that the AIX exists and is built before applications use the path. If you define the path first, applications that open the path will use the AIX; if the AIX is empty (BLDINDEX not run yet), alternate-key reads will find no records until BLDINDEX has been run.

Using the Path in JCL and Programs

To use alternate-key access, you allocate the path name in JCL, not the base cluster name and not the AIX name. The following table summarizes how the path is used.

In the program, you treat the file like a keyed file. The key you use for START, READ by key, and READ NEXT is the alternate key (e.g. department ID), not the primary key. The record format is the base cluster record format. So from the program's view, it is reading a keyed file where the key happens to be the alternate key; the system uses the path to find the AIX and the base cluster and returns the correct base records.

Example: Full JCL Using a Path

1
2
3
4
//STEP1    EXEC PGM=YOURPGM
//EMPFILE   DD   DSN=USERID.EMPL.DEPTAIX.PATH,DISP=SHR
//SYSOUT    DD   SYSOUT=*
 

Here EMPFILE is allocated to the path name. The program opens EMPFILE and uses the alternate key (e.g. department ID) to read records. The records returned are the base cluster records (e.g. employee records) in the order or by the key of the alternate index. If the program had used DSN=USERID.EMPL.KSDS (the base cluster name), it would access by primary key (e.g. employee ID) instead. So the choice of path name vs base cluster name in JCL determines whether you get alternate-key or primary-key access.

Deleting a Path

To remove a path, you delete only the path catalog entry. The command is DELETE path-name PATH. This does not delete the AIX or the base cluster; it only removes the path. After that, the path name no longer exists and cannot be used in DSN=. The AIX and base cluster remain. If you want to remove the AIX as well, you delete the AIX cluster (DELETE aix-name ALTERNATEINDEX or CLUSTER, depending on your IDCAMS syntax). Deleting the base cluster typically requires that you first delete any paths and AIXs that reference it, or the delete may fail or require special options.

Multiple Paths for One AIX

You can define more than one path to the same AIX if you want different path names for the same alternate-key access (e.g. for different applications or naming conventions). Each path is a separate catalog entry with its own name and the same PATHENTRY. All of them use the same AIX and thus the same base cluster and alternate key. You cannot have one path point to multiple AIXs; each path has a single PATHENTRY (one AIX).

Key Takeaways

• A path is a catalog entry that links an alternate index (AIX) to the base cluster for access. It holds no data.
• DEFINE PATH NAME(path-name) PATHENTRY(aix-name) creates the path. Applications use the path name in DSN= for alternate-key access.
• Without a path, you cannot open the base cluster by alternate key; the AIX alone is not enough for application access.
• When you open the path, the system opens both the AIX and the base cluster and uses the AIX to resolve alternate-key reads to base records.
• To remove a path, use DELETE path-name PATH; this does not delete the AIX or the base cluster.

Explain Like I'm Five

The base cluster is like a big book, and the AIX is like a list at the back that says "find by color." The path is the sign on the door that says "if you want to use the color list, come in this way." So you have the book (base), the list (AIX), and the sign (path). When you go in through the door (open the path), the grown-up (the system) uses the list to find the right page and gives you the page from the book. The path is just the way in; it doesn't hold any pages or list entries itself.

Test Your Knowledge