VSAM use of the VSE Lock Manager

To understand this problem, you need to understand a bit about VSE's locking mechanism and how VSAM uses it.

VSE provides two kinds of locks:

1. Internal Locks, used within a single VSE image, for resources not shared among multiple VSE images -- files shared among partitions within a single VSE system, the VTOC of a non-shared volume, etc.
2. External Locks, used across multiple VSE images, for resources which are shared among multiple VSE images -- files on volumes which are shared among multiple VSE systems, library members in libraries which are on volumes which are shared, etc.

VSE's Lock Manager uses an internal lock table for Internal Locks. External Locks are recorded both in the lock table of the owning system and in the VSE Lock File, which (of course) must be located on a DASD volume which is accessible to all the VSE systems sharing resources.

VSAM uses this VSE locking mechanism to implement its integrity features for shared files and other resources.

A standard convention is used by VSAM to create Lock Resource Names. Lock Resource Names are 12 bytes in length, and for file related locks they contain:

• All VSAM lock resource names begin with the character "V".
• All VSAM file related locks contain the 6-character VOLSER of the volume containing the catalog where the file is defined.
• All VSAM file related locks contain a 3-byte CI number referencing the Control Interval number within that catalog where the file is described. This plus the previous (VOLSER) value uniquely define the file.
• All VSAM file related locks contain a 2-byte code for the specific file-related function being locked.

So, what can go wrong?

Well, if that lock resource name really isn't unique, then the VSE Lock Manager may falsely detect that a file has been locked. This is common enough to appear on the Lehigh University VSE-L listserver fairly often.

Simply, if within the scope of a given VSE system or the scope of a group of VSE systems using a VSE Lock File, there are more than one VSAM catalog residing on two different disk volumes, but those different volumes have duplicate VOLSER values, then it is possible for what should have been two different VSAM-created Lock Resource Names to be the same.

This results in VSAM OPEN error x'A8' or 168 error codes being returned to your application. No data is at risk, as your application is prevented from opening the file.

So? What should I do about this? VSAM should be fixed!

No, VSAM is working as you really want it to -- it is protecting your data. You should identify all volumes within the scope of your VSE system and its related VSE Lock File, and insure that they have unique VOLSERs.

If the volumes are not shared (they are really different volumes) then it is permissible for them to have the same VOLSERs, but they MUST be defined in your VSE IPL ADD commands as:

ADD cuu

WITHOUT the ",SHR" parameter.

Note carefully: if the volume is really shared and is not defined as

ADD cuu,SHR

then you are at risk of data and control information being corrupted as the various systems with access to the volume will not post locks to protect your data and system control information on the volume.

Summary

For all disk volumes which are shared among more than one VSE image, you must insure that all the following are true:

• Each volume is defined in each VSE image's IPL ADD commands with ",SHR" specified.
• Each volume has a unique VOLSER.

For all disk volumes which are NOT shared among more than one VSE image, you should ensure that all the following are true:

• Each volume is defined in its (unique) VSE image without ",SHR" specified.
• Each volume within the VSE image has a unique VOLSER.