PDS Directory

The directory of a PDS occupies the beginning of the area allocated to the data set on a direct access volume. It is searched and maintained by the BLDL, FIND, and STOW macros. The directory consists of member entries arranged in ascending order according to the binary value of the member name or alias.

PDS member entries vary in length and are blocked into 256-byte blocks. Each block contains as many complete entries as will fit in a maximum of 254 bytes. Any remaining bytes are left unused and are ignored. Each directory block contains a 2-byte count field that specifies the number of active bytes in a block (including the count field). In Figure 1, each block is preceded by a hardware-defined key field containing the name of the last member entry in the block, that is, the member name with the highest binary value. Figure 1 shows the format of the block returned when using BSAM to read the directory.

Figure 1. A PDS Directory Block

Each member entry contains a member name or an alias. As shown in Figure 2, each entry also contains the relative track address of the member and a count field. It can also contain a user data field. The last entry in the last used directory block has a name field of maximum binary value (all 1s), a TTR field of zeros, and a zero-length user data field.

Figure 2. A PDS Directory Entry

Figure 2 shows the following fields:

Member Name—Specifies the member name or alias. It contains as many as 8 alphanumeric characters, left justified, and padded with blanks if necessary.

TTR—Is a pointer to the first block of the member. TT is the number of the track, starting from 0 for the beginning of the data set, and R is the number of the block, starting from 1 for the beginning of that track.

C—Specifies the number of halfwords contained in the user data field. It can also contain additional information about the user data field, as shown below:

0—When set to 1, indicates that the NAME field contains an alias.

1-2—Specifies the number of pointers to locations within the member.

The operating system supports a maximum of three pointers in the user data field. Additional pointers can be contained in a record called a note list discussed in the following note. The pointers can be updated automatically if the data set is moved or copied by a utility program such as IEHMOVE. The data set must be marked unmovable under any of the following conditions:

More than three pointers are used in the user data field.
The pointers in the user data field or note list do not conform to the standard format.
A note list for a PDS containing variable length records does not conform to standard format. Variable-length records contain BDWs and RDWs that are treated as TTRXs by IEHMOVE.
The pointers are not placed first in the user data field.
Any direct access address (absolute or relative) is embedded in any data blocks or in another data set that refers to the data set being processed.

3-7—Contains a binary value indicating the number of halfwords of user data. This number must include the space used by pointers in the user data field.

You can use the user data field to provide variable data as input to the STOW macro. If pointers to locations within the member are provided, they must be 4 bytes long and placed first in the user data field. The user data field format is as follows:

TT—Is the relative track address of the note list or the area to which you are pointing.

R—Is the relative block number on that track.

N—Is a binary value that shows the number of additional pointers contained in a note list pointed to by the TTR. If the pointer is not to a note list, N=0.

A note list consists of additional pointers to blocks within the same member of a PDS. You can divide a member into subgroups and store a pointer to the beginning of each subgroup in the note list. The member can be a load module containing many control sections (CSECTs), each CSECT being a subgroup pointed to by an entry in the note list. Use the NOTE macro to point to the beginning of the subgroup after writing the first record of the subgroup. Remember that the pointer to the first record of the member is stored in the directory entry by the system.

If a note list exists, as shown above, the list can be updated automatically when the data set is moved or copied by a utility program such as IEHMOVE. Each 4-byte entry in the note list has the following format:

TT—Is the relative track address of the area to which you are pointing.

R—Is the relative block number on that track.

X—Is available for any use.

To place the note list in the PDS, you must use the WRITE macro. After checking the write operation, use the NOTE macro to determine the address of the list and place that address in the user data field of the directory entry.

The linkage editor builds a note list for the load modules in overlay format. The addresses in the note list point to the overlay segments that are read into the system separately.

Restriction: Note lists are not supported for PDSEs. If a PDS is to be converted to a PDSE, the PDS should not use note lists.