VSAM SHAREOPTIONS

SHAREOPTIONS(crossregion crosssystem) in DEFINE CLUSTER (abbreviation SHR) controls how a VSAM dataset can be shared among address spaces and systems. The first value (crossregion) applies when multiple regions or jobs on the same system open the file—for example batch and CICS. The second value (crosssystem) applies when the file is opened from more than one system (e.g. LPARs in a sysplex). Each value is 1, 2, 3, or 4 and determines whether multiple users can read only, or read and write, and whether the application must use ENQ/DEQ for integrity. Choosing the right SHAREOPTIONS is important for batch and online coexistence and for avoiding file corruption. This page explains the four values for cross-region and cross-system, when to use (2 3) vs (3 3), and the role of ENQ/DEQ when multiple programs update the file.

What SHAREOPTIONS Does

When you define a cluster, SHAREOPTIONS is stored in the catalog and enforced when the file is opened. It answers: can more than one job or region open this file at the same time, and can more than one of them update it? Option 1 is the most restrictive (one reader/writer at a time for update). Option 2 allows many readers and one writer. Options 3 and 4 allow multiple readers and writers; with 3 and 4, VSAM does not serialize updates, so the application must use ENQ/DEQ (or similar) to protect critical sections or the file can be corrupted. So SHAREOPTIONS sets the “rules of the game”; your programs must then follow those rules (e.g. ENQ before update, DEQ after) when you use 3 or 4.

Cross-Region Options (First Value)

Cross-region sharing applies to multiple address spaces on the same system (e.g. multiple batch jobs, or batch and CICS regions). The first number in SHAREOPTIONS(crossregion crosssystem) is the cross-region value.

Option 1 means only one user can have the file open for update at a time; others can read. Option 2 allows multiple readers and one writer—often used when one batch job or one CICS region updates and others only read. Option 3 and 4 allow multiple updaters; your programs must use ENQ/DEQ to avoid concurrent updates to the same records or control intervals. Option 4 is like 3 but with buffer-refresh behavior (VSAM refreshes buffers before each request in certain cases); see your IBM documentation for the exact difference on your release.

Cross-System Options (Second Value)

Cross-system sharing applies when the dataset is opened from more than one system (e.g. different LPARs or members of a sysplex). The second number in SHAREOPTIONS is the cross-system value. Values 1 and 2 are reserved; you use 3 or 4 for cross-system sharing.

So for cross-system you typically specify 3 or 4. (2 3) means: cross-region, one writer and many readers; cross-system, multiple readers and writers with application-managed integrity. (3 3) means: cross-region and cross-system, multiple readers and writers; the application must use ENQ/DEQ to protect updates.

Choosing (2 3) vs (3 3)

(2 3) is often used when only one address space (or one type of job) updates the file and others only read. For example: CICS reads the file and a batch job runs at night to update it; or one batch job updates and others only read. (2 3) avoids the need for ENQ/DEQ as long as you truly have only one updater at a time. (3 3) is used when multiple jobs or regions need to update the same file—for example multiple CICS regions or batch and CICS both updating. With (3 3), you must implement ENQ/DEQ (or equivalent) in all programs that update the file; otherwise concurrent updates can corrupt the dataset. The VSAM Demystified Redbook and IBM documentation recommend using ENQ/DEQ whenever (3 3) is used and multiple writers are possible. DB2-defined VSAM datasets often default to (3 3) with DB2 handling serialization.

Syntax and Where to Specify

In DEFINE CLUSTER you specify SHAREOPTIONS(crossregion crosssystem) or the abbreviation SHR(crossregion crosssystem). Both numbers must be in the range 1–4. Example:

1
2
3
4
5
6
7
8
9
10
  DEFINE CLUSTER ( -
    NAME(MY.APPL.FILE.KSDS) -
    INDEXED -
    RECORDSIZE(100 200) -
    KEYS(10 0) -
    SHAREOPTIONS(2 3) -
    CYLINDERS(20 10)) -
  DATA (NAME(MY.APPL.FILE.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.FILE.KSDS.INDEX))
 

SHAREOPTIONS(2 3) allows one writer and many readers cross-region, and full read/write sharing cross-system (with application integrity). You can change SHAREOPTIONS later with IDCAMS ALTER; the new values take effect the next time the file is opened.

ENQ/DEQ and Data Integrity

With options 3 or 4, VSAM does not serialize read and write operations. If two programs update the same record (or the same CI) at the same time, the result can be lost updates or corrupted data. To prevent that, programs that update the file must use ENQ (enqueue) and DEQ (dequeue) on a common resource (e.g. dataset name or a key) so that only one program at a time can update a given record or set of records. ENQ/DEQ are system services (e.g. via the ENQ macro or equivalent); the program issues ENQ before the update and DEQ after. So SHAREOPTIONS(3 3) or (3 4) gives you the ability to share; ENQ/DEQ gives you the integrity. Without ENQ/DEQ, (3 3) is risky for update access.

Key Takeaways

• SHAREOPTIONS(crossregion crosssystem) controls sharing. First value = cross-region (same system); second = cross-system (multiple systems).
• 1 = minimal sharing; 2 = many readers, one writer; 3 and 4 = multiple readers and writers (application must use ENQ/DEQ for integrity with 3/4).
• (2 3) is common for one updater and many readers. (3 3) is used when multiple updaters share the file and the application implements ENQ/DEQ.
• SHAREOPTIONS can be changed with IDCAMS ALTER. New values apply on the next open.

Explain Like I'm Five

Imagine a shared whiteboard. SHAREOPTIONS says who can use it at the same time. Option 1: only one person can write, others can look. Option 2: many people can look, one person can write. Option 3 and 4: many people can look and write, but then you need a rule like “raise your hand before you write” (ENQ/DEQ) so two people don’t write on the same spot and make a mess. The first number is the rule for people in the same room (cross-region); the second is the rule for people in different rooms (cross-system).

Test Your Knowledge