Home /Mainframe /Products, Manuals, and Procedures /CICS/TS /VSAM Issues

VSAM Issues

If you have any questions about the content of this page, please contact CICS Request for  clarification

This section discusses these VSAM considerations and  issues:

Control Interval Size 
Conventional wisdom dictates that VSAM CIs be defined so as to minimize disk space. So half track blocking seems attractive. However, because  performance is so important in the online environment, it may be necessary to  waste some disk space when allocating VSAM files that will be accessed by CICS.  The correct choice of CI depends on how the file is to be accessed.

  • Files that are primarily browsed, can have a fairly large CI.
  • Files that are primarily updated, should have a fairly small CI.
  • Files that are heavily updated, MUST have a small CI.

This is due to how CICS locks all records in a CI while one  record in that CI has an outstanding read-for-update. No other CICS task can  access any record in such a CI. CICS will wait for the rewrite or unlock to  complete, and then allow the waited task(s) to finish. For actively updated  files, it is therefore beneficial to allocate CI's so they will contain few  records.

Alternate Index Paths
Alternate  index paths to VSAM data sets will be supported in the following manner:

  • All alternate index data sets should be defined with the  "UPGRADE" option to force VSAM to maintain all pointers to new records and keys.
  • Online updates (adds, deletes, and changes) can be made through  either the base cluster or the alternate index path..
  • Note: CICS reads the PATH not the actual alternate index (AIX).

ENDBR and Reads for Update
If a VSAM data set is to be  read for update following one or more browse requests, be sure to include an  "end browse" command (EXEC CICS ENDBR....) before the read for update. Failure  to do so will hang your program on the read for update.

VSAM SHAREOPTION
It is recommended that VSAM  data sets be defined with "SHAREOPTION ( 2 )". It allows one facility (CICS, or  BATCH) to have a given data set open for update at a time; it allows any number  of facilities to read a given data set simultaneously.

CICS File Integrity Options and Features
The  following features are implemented on behalf of all updateable VSAM files unless  specifically requested.

Dynamic Transaction  Backout
Dynamic transaction backout (DTB) reverses updates to VSAM files  by tasks that ABEND or execute SYNCPOINT ROLLBACK commands. CICS will undo all  VSAM updates made by such a task. Records will be restored to their state at  "task start" or the last SYNCPOINT command. The SYNCPOINT (no rollback) command  commits a task's updates; a SYNCPOINT ROLLBACK reverses such updates.

VSAM ESDS and DATA  Backout

There is a little known  fact about CICS and VSAM ESDS files. As an ESDS file is written to, the new  records are added at the end of the file, as one would expect. If the CICS task  abends (or executes a SYNCPOINT ROLLBACK), then the DTB (dynamic transaction  backout) process tries to delete any added records. ESDS records cannot be  deleted because VSAM ESDS does not (will never) support the delete process.  These records remain in the ESDS data set.

CICS can not delete  records from an ESDS file, but it can "flag" the "should have been backed out"  records to indicate their "should have been backed out" status.

The industry standard is  be to place a single HEX FF (high value) as the first byte of the "should have  been backed out" records.

Our Customers have an  opportunity to choose.

  1. Use the industry standard to flag the first byte with high  values.
  2. Do something else to the appropriate records -- you tell us.
  3. Leave things alone -- no changes, no "should have been backed  out" flags.

One of these choices must  be made on behalf of your CICS regions. One choice per institution, please.

Unless we hear from you,  3 will be in effect.

If you chose 1 (or 2) of the above choices, you will need to  modify all batch and online programs that read ESDS files maintained by CICS.  Code must be added to completely ignore records with a hex FF in the first  position of the record. Such a record should not have been added to the file in  the first place, and therefore all readers of the file must treat these records  as if they did not exist.

File Recovery Logging 
All updateable VSAM files in CICS are set up to produce VSAM Forward  Recovery records. These recovery records are collected and kept for 60 days.  With the Forward Recovery records and a product called CA-Filesave/RCS, lost  updates can be reapplied or activity reports can be produced.

For instance, if your  backup failed, but your delete didn't, we can recover the file from any backup  within the 60 days and reapply the CICS change activity from the backup date to  the current date. Any batch updates would need to be regenerated individually,  since batch activity is not collected in Forward Recovery records.

Forward Recovery records  can also be printed. Sometimes it may be useful to see who updated or inserted a  particular record, or what time a specific record was changed/added. The   Filesave/RCS report shows the date, the time, the transaction id, the record  contents and the terminal id of the operator. If it is necessary to know the  user id of the person at that terminal, that information is usually available  through other methods.

It is not expected that these facilities will be used for  files in the CICS test region. The CICS support of the features is present in  the test region to properly emulate the eventual production environment. 

SYNCPOINT Commands
Programs that update  multiple records (one or more files) should consider using SYNCPOINT commands to  minimize system (DTB) over head and contention between other CICS tasks  accessing those files.>

Long-Running CICS  Tasks
While never recommended, it is sometimes required to allow a CICS  task to run for a long time. Extreme care must be employed when this situation  cannot be avoided. The overall performance of CICS can easily be degraded (read  destroyed) if the following guidelines are not followed. Read for updates must  not be held for any length of time. Other CICS tasks will stop if they attempt  to read records in the same VSAM CI as the one you've read for update. SYNCPOINT  command must be used to commit the updates, so as to get out of the way of other  CICS users.

Sharing CICS Data Sets with Batch  Jobs
Most user data sets are allocated to CICS with the "DISP=SHR" JCL  option. This directs the operating system to allow simultaneous access to such  data sets. Whether or not such concurrent access is allowed by an access method  (VSAM) is another matter and depends in part on the following considerations:

  • If a data set is restricted to "read only" access within CICS,  it may be updated by a batch job while CICS is active.
  • If a data set is "updateable" within CICS, it can not be opened  for update by a batch job. Such data sets may be closed (NWFM transaction)  online and then the batch update may proceed.
  • If a data set is "updateable" within CICS it may be read by a  batch job.

WARNING: It should be noted that files that have been updated  online may not be correctly accessed by batch jobs due to the new data remaining  in online buffers. The same thing applies to CICS reading a data set that has  been updated in batch. Until the updating job closes the data set and CICS  closes and opens the dataset, CICS may not provide the most current data. 

How to Avoid this Situation
Before any  batch job accesses a data set that is open for update under CICS, that file  should be closed online for the duration of the batch job. See documentation on the CICS/Batch File Control  System for details.

CICS User File  Availability Summary

User VSAM files are available to the CICS system based on the day of the week  and the time of day. At an institution's discretion, files may be:

  • Under a simple prescribed schedule.
  • Always online (24/7 - anytime CICS is available).
  • In either case, manipulated by the batch close/open facility.

Schedule

(Note: All schedules are Eastern Time.)
Open Processing: Most VSAM files  are opened as they are first referenced. We can tell CICS to open files at  startup, if that is something you want. Just let us know.
Close Processing:  For each day of the week (Monday through Sunday), plus holidays, an individual  file may or may not be automatically closed at 8 P.M. Each CICS region has a  default or "normal" schedule which is different for each CICS region. Some  regions default to their files being available from 7:00 A.M. to 8:00 P.M., on  the five working days of the week. Others want to maintain their own schedule,  so we do little or no automatic 8 P.M. closes. Each file in CICS has its own  individual schedule. What is "normal" for a region is applied to new file  definitions unless additional details are provided. The online scheduling system  is not as flexible as that which may be implemented by scheduling batch closes  (described next).

Making Your Own Schedule

We offer a facility for batch jobs to close and then open CICS VSAM files as  needed. Due to MVS dataset disposition issues, this usually means one job closes  some number of files, the next job(s) run against those files, and eventually  the last job reopens them. Perhaps the easiest (once it's set up) option is for  an institution to have all their files, marked 24-7 (all shifts) and bracket  production jobs with appropriate close and open jobs. Due to complex scheduling  issues, an institution may chose to mark their files 24-7 (all shifts) and run a  job (or several) to close all files not appropriate for a particular late  evening/night's online processing. The files will automatically revert to an  online status the next day.

Determining Availability

The NWFM utility transaction is used to determine a VSAM file's availability  (Note: General documentation for NWFM is available under CICS. Invoke NWFM, hit  PF1 twice and the full documentation is displayed.).

One must know the CICS file-ID (eight characters) of the file(s) in question.  Type into a clear screen, "NWFM,xxxxxxxx" where xxxxxxxx is the file-ID, and hit  Enter. Then hit PF10 to display the Schedule screen:

 

Note "The Rule" and the "Exception to the rule" columns. They describe the  availability of each file for the days of the week. The codes for availability  are: B - both shifts, D - day shift, X -no shifts. DDNAMEs of files with active  (current or in the future) "Exceptions" are displayed in pink (or bright).

Changing The Prescribed Schedule

Those individuals who are authorized (as identified by ACF2) to modify the  schedule will have "s" and "p" as available line commands listed on the third  line of the display. Type the schedule "s" line command to the left of the  DDNAME whose schedule you wish to modify. You may mark as many ddnames as  appropriate. If you know you wish to make the same schedule change to additional  ddnames, the paste schedule "p" line command can be used. A "schedule "S" line  command can be typed from any of the NWFM "views", the Schedule screen does not  have to active. An example of a Schedule Maintenance screen follows:
 

 

The cursor appears on the EXCEPTION to the rule line. Simply type, over type,  or erase the appropriate items.

  • If you erase an exception entry, a lower case "e" will appear showing you  that an item has been erased.
  • If you make changes on the RULE line, your changes will be permanent. If you  type into the EXCEPTION line, your changes will be for the date range indicated.  If no date range is typed, the default is for the current week.
  • If you with to keep the same EXCEPTIONS, but want to extend the dates to the  current week, just erase the "start date" or type over one of the exception  entries. The program will assume the current week as the date range.
  • The dates can be manually entered, of course, in the form: mm/dd/yyyy. The  "Ends" date defaults to the last day of the "Starts on" week.

Make your changes and hit ENTER. The changes will be edited and redisplayed  for your approval. Hit PF3 to commit the changes; hit PF12 to cancel the  changes. If you wish to start your modifications over, hit CLEAR and the screen  will be refreshed to its initial state. If multiple ddnames were selected, the  next schedule change screen will then appear. If paste "p" was used as the line  command, the previous changes will already have been made for you. You must  still hit PF3 to commit these changes. At the end of the line command  processing, the previous NWFM screen will be redisplayed with a message  indicating which ddnames have been changed. Note:

  • The "Description" field can also be changed from this screen. It is displayed along with the Data Set Name on the default "status" screen when this  application is entered.
  • The history of recent schedule changes is displayed in the bottom half of  the screen.
  • Erased exceptions are shown as lower case "e". Paste will erase appropriate  entries as required.
  • Paste is available even if "s" was used as the line command. Hitting PF6  will type the existing paste values for you.
  • Paste values are reset each time you make changes to the pattern, so look  before you leap.

Why a File May Not Be Available

  • Out-of-shift (it's 10:00 P.M. and this is a day-only file)
  • DATA SET is not cataloged (does not exist: BATCH problem)
  • Closed on-line NWFM trans (OPEN if appropriate)
  • Closed by a batch job NWBCLOSE (OPEN if appropriate)

On-line or batch closes take a file off-line until 7:00 A.M. the next morning  that file is to be available. ON-LINE or BATCH opens reverse any type of close.  Of course, shift availability controls all access to files. An open command is  not honored when a file is out-of-shift.

 

User Maintained Data  Table (UMDT)

A User Maintained Data Table is a sort of fake VSAM  file. It does not exist on DASD, it only lives in CICS memory. You browse,  read  and write to it like any other VSAM file but at the end of the day (when CICS  goes down, or the file is closed) its content disappears. UMDT's provide a good  "scratch file" facility. They can be accessed very fast, and do not suffer from  disorganization. They are a good candidate for high volume read-only  applications.

When a UMDT is first accessed, a "seed" VSAM file is read  into memory. One record or many, depending on the application. The seed file's  attributes (key position, maximum record size and key size) are used for the  UMDT's attributes. One seed file can be used by many UMDT's as appropriate. No  updates to the UMDT will be applied against the seed file.

UMDT Basics

  1. All UMDTs have variable length records.
  2. Maximum LRECL is 32K.
  3. Maximum record count is 16,777,215.
  4. A “seed” VSAM file must be identified. It can contain one record  or many records. The values of key position, key length etc. are copied from the  seed file.
  5. That seed file is read into memory at OPEN time.
  6. Open will occur at first reference (write, read, startbr….)  following startup or file close.
  7. All subsequent activity is against the data in memory.
  8. Memory is cleared at CLOSE time.
  9. Dynamic transaction backout is supported, restart recovery is  not. Item 5 applies.
  10. The seed VSAM file remains unchanged.

Make a UMDT Available to CICS
To  get a UMDT available to CICS, you must tell us:

  • You want a UMDT defined
  • The DDNAME
  • The DSN of the seed file

What you have to do:

  • Define the seed file with the appropriate key length, key  position and maximum record size.
  • Load the seed file with the appropriate initial data.