DEFINE PATH

DEFINE PATH is the IDCAMS command that creates a path—a catalog entry that links an alternate index (AIX) to its base cluster so that applications can access the base cluster by the alternate key. The path has a name (NAME) and points to an AIX (PATHENTRY). It does not hold any data. When you open the path name in JCL or in a program, the system opens both the AIX and the base cluster and uses the AIX to resolve alternate-key reads to base cluster records. This page explains the DEFINE PATH syntax, every parameter (NAME, PATHENTRY, UPDATE/NOUPDATE, CATALOG, and others), when to run it in the AIX setup sequence, and how it differs from DEFINE ALTERNATEINDEX.

What DEFINE PATH Creates

DEFINE PATH does not create a cluster, a data component, or an index component. It creates a single catalog entry. That entry has a name (the path name) and a pointer to an alternate index (PATHENTRY). When an application opens the path name, the system looks up the path in the catalog, finds the AIX name in PATHENTRY, opens that AIX and the base cluster to which the AIX is related, and uses the AIX to satisfy keyed requests by the alternate key. So the path is the "door" you open to get alternate-key access; the AIX and base cluster do the actual work. Without DEFINE PATH, the AIX exists (after DEFINE ALTERNATEINDEX and BLDINDEX) but there is no path name to open—applications would have to open the base cluster by its primary key or the AIX alone, which does not give you base cluster records by alternate key in the usual way.

General Syntax

The DEFINE PATH command has the following form. Only NAME and PATHENTRY are required; the rest are optional.

1
2
3
4
5
6
7
8
9
10
  DEFINE PATH ( -
    NAME(path-name) -
    PATHENTRY(aix-name) -
    [ MODEL(entryname [catname]) ] -
    [ OWNER(ownerid) ] -
    [ RECATALOG | NORECATALOG ] -
    [ TO(date) | FOR(days) ] -
    [ UPDATE | NOUPDATE ]) -
  [ CATALOG(catname) ]
 

NAME(path-name) is the name you will use in DSN= and in the program. PATHENTRY(aix-name) is the name of the alternate index cluster you defined with DEFINE ALTERNATEINDEX. UPDATE means the AIX is opened for update when the base is updated so the alternate index stays in sync; NOUPDATE means it is not. CATALOG specifies the catalog where the path entry is created; if omitted, the step or job default catalog is used.

Required and Optional Parameters

NAME and PATHENTRY are required. The path name must be unique in the catalog. PATHENTRY must be the name of an existing alternate index cluster; that AIX must already have been created with DEFINE ALTERNATEINDEX and should have been built with BLDINDEX before you use the path for alternate-key reads. UPDATE and NOUPDATE control whether the AIX is maintained when the base is updated; if you do not specify one, your system may default to UPDATE. The other parameters (CATALOG, MODEL, OWNER, TO/FOR, RECATALOG/NORECATALOG) are optional and used for catalog placement, modeling, security, retention, or recatalog behavior.

NAME: The Path Name

NAME(path-name) is the name of the path. This is the name that appears in the catalog and that you use in JCL when you allocate the file for alternate-key access. For example, if you define a path with NAME(MY.EMPL.BY.DEPT), then in your JCL you would use DSN=MY.EMPL.BY.DEPT (and DISP=SHR or appropriate disposition). The program opens the DD name; the system resolves it to the path, then to the AIX and base cluster. The path name and the AIX name are usually different: the path name is the "public" name for alternate-key access, while the AIX name (PATHENTRY) is the internal object that holds the index. A common convention is to use a name that suggests the alternate key, e.g. MY.FILE.BY.DEPT or MY.FILE.AIX.DEPT.PATH.

PATHENTRY: The Alternate Index

PATHENTRY(aix-name) specifies which alternate index this path uses. The aix-name must be the name of a cluster that was created with DEFINE ALTERNATEINDEX. That AIX is already related to a base cluster via the RELATE parameter in DEFINE ALTERNATEINDEX. So the chain is: path name → PATHENTRY (AIX) → base cluster (from RELATE). When you open the path, the system follows this chain. You cannot put a base cluster name or a path name in PATHENTRY; it must be an alternate index cluster name. If the AIX is in a user catalog, ensure the job has access to that catalog (e.g. JOBCAT/STEPCAT) when you run DEFINE PATH and when applications open the path.

UPDATE vs NOUPDATE

UPDATE means that when the base cluster is opened for update (e.g. for insert, delete, or rewrite), the access method will also open the AIX for update so that the alternate index is kept in sync. New records get their alternate key in the AIX; deleted or updated records are reflected. Use UPDATE when the base is read-write and you want the alternate index to always reflect the current data. NOUPDATE means the AIX is not opened for update when the base is updated. The AIX can become stale. Use NOUPDATE when you only need read-only alternate-key access or when you plan to rebuild the AIX periodically with BLDINDEX. In most online or batch applications that update the base and also need alternate-key access, UPDATE is the right choice. If you use NOUPDATE and then update the base, you must run BLDINDEX again (or another refresh mechanism) before alternate-key reads will see the changes.

When to Run DEFINE PATH

You run DEFINE PATH after you have created the alternate index with DEFINE ALTERNATEINDEX. You can run DEFINE PATH before or after BLDINDEX. The path is only a catalog link; it does not depend on the AIX being filled. However, if applications open the path before BLDINDEX has been run, alternate-key reads will find no (or incomplete) data until the AIX is built. So the typical order is: (1) DEFINE ALTERNATEINDEX, (2) DEFINE PATH, (3) BLDINDEX. After BLDINDEX, the path is ready for use. Some sites run DEFINE PATH after BLDINDEX so that the path is not visible until the AIX is ready; either order is valid.

DEFINE PATH vs DEFINE ALTERNATEINDEX

DEFINE ALTERNATEINDEX creates the alternate index cluster: a VSAM object with data and index components that will hold alternate key values and pointers to the base cluster. DEFINE PATH creates only a catalog entry that associates a path name with that AIX. So DEFINE ALTERNATEINDEX allocates space and structure; DEFINE PATH allocates a name that applications use to open the base by alternate key. You need both: the AIX to hold the keys and pointers, and the path to provide the name that ties the AIX to the base for I/O. If you only run DEFINE ALTERNATEINDEX and BLDINDEX but never DEFINE PATH, there is no path name to put in DSN= for alternate-key access.

Example: Defining a Path

Suppose the base cluster is MY.EMPL.KSDS and you have defined an alternate index MY.EMPL.AIX.DEPT (by department code) with DEFINE ALTERNATEINDEX and built it with BLDINDEX. To allow applications to open the file by department code, define a path:

1
2
3
4
5
6
  DEFINE PATH ( -
    NAME(MY.EMPL.BY.DEPT) -
    PATHENTRY(MY.EMPL.AIX.DEPT) -
    UPDATE) -
  CATALOG(MYCAT)
 

Here the path name is MY.EMPL.BY.DEPT. Applications use DSN=MY.EMPL.BY.DEPT when they want to read or update by department code. PATHENTRY(MY.EMPL.AIX.DEPT) points to the AIX. UPDATE keeps the AIX in sync when the base is updated. CATALOG(MYCAT) places the path entry in MYCAT; omit it to use the default catalog.

Example: Minimal DEFINE PATH

The simplest form uses only the required parameters:

1
2
3
4
  DEFINE PATH -
    NAME(USERID.FILE.BY.ALTKEY) -
    PATHENTRY(USERID.FILE.AIX.ALTKEY)
 

No CATALOG, UPDATE, or other options are specified. The path is created in the default catalog. The system default for UPDATE/NOUPDATE will apply (often UPDATE). This is enough to use the path name in JCL and in the program for alternate-key access once the AIX has been built with BLDINDEX.

Using the Path in JCL

In JCL, you allocate the path name, not the base cluster name and not the AIX name. For example:

1
2
3
4
//STEP1    EXEC PGM=YOURPGM
//EMPFILE   DD   DSN=MY.EMPL.BY.DEPT,DISP=SHR
//SYSOUT    DD   SYSOUT=*
 

EMPFILE points to the path MY.EMPL.BY.DEPT. The program opens EMPFILE and uses the alternate key (e.g. department code) for START, READ by key, and READ NEXT. The records returned are the base cluster records (e.g. employee records). If the program had used the base cluster name (MY.EMPL.KSDS) instead, it would access by primary key. So the name in DSN= decides whether you get alternate-key access (path name) or primary-key access (base cluster name).

Multiple Paths for One AIX

You can define more than one path that points to the same AIX. Each path has a different NAME but the same PATHENTRY. That is useful when different applications or naming standards require different path names for the same alternate-key access. All such paths use the same AIX and the same base cluster; only the catalog name (the path name) differs. You cannot define one path that points to more than one AIX; each path has a single PATHENTRY.

Deleting a Path

To remove a path, delete only the path catalog entry. The IDCAMS command is DELETE path-name PATH (or the equivalent on your system). Deleting the path does not delete the AIX or the base cluster. After the path is deleted, 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 must delete the AIX cluster separately. If you delete the base cluster, you typically must first delete all paths and AIXs that reference it, or the delete may fail or require special options.

Key Takeaways

• DEFINE PATH creates a catalog entry (a path) that links an AIX to the base cluster for access. It does not create data or index components.
• NAME(path-name) is the name you use in DSN= for alternate-key access. PATHENTRY(aix-name) is the name of the AIX cluster. Both are required.
• UPDATE keeps the AIX in sync when the base is updated; NOUPDATE does not. Default is often UPDATE.
• Run DEFINE PATH after DEFINE ALTERNATEINDEX; you can run it before or after BLDINDEX. BLDINDEX must be run before the path is used for alternate-key reads.
• You can define multiple paths with the same PATHENTRY (same AIX) to give different names for the same alternate-key access.

Explain Like I'm Five

The base cluster is like a big book of names in order by employee number. The alternate index is like a second list that says "find by department." DEFINE PATH is like putting a sign on the door that says: "To use the department list, come in here." The sign (path) does not hold any names or lists; it just tells you where to go. When you go in through that door (open the path name), the grown-up (the system) uses the department list to find the right page in the big book and gives you that page. So you need the book (base), the list (AIX), and the sign (path). DEFINE PATH is the command that puts up the sign.

Test Your Knowledge