Closing VSAM Files

   Use the CLOSE statement to disconnect your program from the VSAM file.  If

   you try to close a file that is already closed, you will get a logic

   error.  You should check the file status key after each CLOSE statement.

   In the event that you do not close a VSAM file, COBOL will automatically

   close the file for you, giving you a warning-level diagnostic message.

   See "Automatic Closing of Files"  details. 

Deleting Records from a VSAM File

   Open the file for I-O and use the DELETE statement to remove an existing

   record on an indexed or relative file.  You cannot use DELETE on a

   sequential file.

   When ACCESS IS SEQUENTIAL, or if the file contains spanned records, the

   record to be deleted must first be read by the COBOL program.  The DELETE

   then removes the record that was read.  If the DELETE is not preceded by a

   successful READ, the deletion is not done and the status key value is set

   to 92.

   When ACCESS IS RANDOM or ACCESS IS DYNAMIC, and if the records are not

   spanned, the record to be deleted need not be read by the COBOL program.

   To delete a record, the key of the record to be deleted is moved to the

   RECORD KEY data item and the DELETE is issued.  You should check the file

   status key after each DELETE statement. 

Replacing Records in a VSAM File

   To replace records in a VSAM file, use REWRITE in a file that you have

   opened for I-O.  If you attempt to use REWRITE on a file that is not

   opened I-O, the record is not rewritten and the status key is set to 49.

   You should check the file status key after each REWRITE statement.

   °   For files accessed sequentially, you must read the record before you

       issue the REWRITE statement.

   °   For sequential files, the length of the record you rewrite must be the

       same as the length of the original record.

   °   For indexed files, you can change the length of the record you

       rewrite.

   °   For variable-length relative files, you can change the length of the

       record you rewrite.

   To replace records randomly or dynamically, the record to be rewritten

   need not be read by the COBOL program.  Instead, to position the record

   you want to update:

   °   For indexed files, move the record key to the RECORD KEY data item,

       and then issue the REWRITE.

   °   For relative files, move the relative record number to the RELATIVE

       KEY data item, and then issue the REWRITE.

Adding Records to a File

  The COBOL WRITE statement adds a record to a file, without replacing any

   existing records.  The record to be added must not be larger than the

   maximum record size specified when the file was defined.  You should check

   the file status key after each WRITE statement.

     1 Adding Records Sequentially

     2 Adding Records Randomly or Dynamically

             

    1 Adding Records Sequentially

   Use ACCESS IS SEQUENTIAL and code the WRITE statement to add records

   sequentially to the end of a VSAM file that has been opened with either

   OUTPUT or EXTEND. 

   Sequential files are always written sequentially.

  

   For indexed files, new records must be written in ascending key sequence.

   If the file is opened EXTEND, the record keys of the records to be added

   must be higher than the highest primary record key on the file when the

   file was opened.

   For relative files, the records must be in sequence.  If you include a

   RELATIVE KEY data-item in the SELECT clause, the relative record number of

   the record just written is placed in that data item.

           

   2 Adding Records Randomly or Dynamically

   When you write records to an indexed data set and ACCESS IS RANDOM or

  ACCESS IS DYNAMIC, the records can be written in any order. 

Updating Records in a VSAM File

   The COBOL language statements that can be used to update a VSAM file in

   the Environment and Data Divisions are the same.

   Figure shows the statements that you can use in the Procedure Division

   to update VSAM files.

     ________________________________________________________________  

     | Figure 73. Procedure Division Statements Used to Update VSAM Files     |

   |_______________________ ________________________ _______________________|

   | ESDS                  | KSDS                   | RRDS                  |

   |_______________________|________________________|_______________________|

   | ACCESS IS SEQUENTIAL: | ACCESS IS SEQUENTIAL:  | ACCESS IS SEQUENTIAL: |

   |     OPEN EXTEND       |     OPEN EXTEND        |     OPEN EXTEND       |

   |     WRITE             |     WRITE              |     WRITE             |

   |     CLOSE             |     CLOSE              |     CLOSE             |

   |         or            |         or             |         or            |

   |     OPEN  I-O         |     OPEN  I-O          |     OPEN  I-O         |

   |     READ              |     READ               |     READ              |

   |     REWRITE           |     REWRITE            |     REWRITE           |

   |     CLOSE             |     DELETE             |     DELETE            |

   |                       |     CLOSE              |     CLOSE             |

   |_______________________|________________________|_______________________|

   | ACCESS IS RANDOM:     | ACCESS IS RANDOM:      | ACCESS IS RANDOM:     |

   |                       |     OPEN  I-O          |     OPEN  I-O         |

   |                       |     READ               |     READ              |

   |     not applicable    |     WRITE              |     WRITE             |

   |                       |     REWRITE            |     REWRITE           |

   |                       |     DELETE             |     DELETE            |

   |                       |     CLOSE              |     CLOSE             |

   |_______________________|________________________|_______________________|

   | ACCESS IS DYNAMIC     | ACCESS IS DYNAMIC      | ACCESS IS DYNAMIC     |

   | Sequential Processing:| Sequential Processing: | Sequential Processing:|

   |                       |     OPEN  I-O          |     OPEN  I-O         |

   |                       |     READ NEXT          |     READ NEXT         |

   |     not applicable    |     WRITE              |     WRITE             |

   |                       |     REWRITE            |     REWRITE           |

   |                       |     START              |     START             |

   |                       |     DELETE             |     DELETE            |

   |                       |     CLOSE              |     CLOSE             |

   |_______________________|________________________|_______________________|

   | ACCESS IS DYNAMIC     | ACCESS IS DYNAMIC      | ACCESS IS DYNAMIC     |

   | Random Processing:    | Random Processing:     | Random Processing:    |

   |                       |     OPEN  I-O          |     OPEN  I-O         |

   |                       |     READ               |     READ              |

   |     not applicable    |     WRITE              |     WRITE             |

   |                       |     REWRITE            |     REWRITE           |

   |                       |     DELETE             |     DELETE            |

   |                       |     CLOSE              |     CLOSE             |

   |_______________________|________________________|_______________________|

          

Reading Records from a VSAM File

   Use the READ statement to retrieve (READ) records from a file.  To read a

   record, you must have opened the file INPUT or I-O.  You should check the

   file status key after each READ statement.

   Records in VSAM sequential files can be retrieved only in the sequence in

   which they were written.

   Records in VSAM indexed and relative files can be retrieved:

   Sequentially

       According to the ascending order of the key you are using, the RECORD

       KEY or the ALTERNATE RECORD KEY, beginning at the current position of

      the file position indicator for indexed files, or according to

       ascending relative record locations for relative files.

   Randomly

       In any order, depending on how you set the RECORD KEY or ALTERNATE

       RECORD KEY prior to your READ request.

   Dynamically

       Mixed sequential and random.

   With dynamic access, you can switch between reading a specific record

   directly and reading records sequentially, by using READ NEXT for

   sequential retrieval and READ for random retrieval (by key).  See "File

   Access Modes"  for a complete description of the features of

   each access mode.

   When you want to read sequentially, beginning at a specific record, use

   START before the READ NEXT to set the file position indicator to point to

   a particular record.

   When you specify START followed by READ NEXT, the next record is read and

   the file position indicator is reset to the next record.  The file

   position indicator can be moved around randomly through the use of START,

   but all reading is done sequentially from that point.  You can continue to

   read records sequentially, or you can use the START statement to move the

   file position indicator:

     START file-name KEY IS EQUAL TO ALTERNATE-RECORD-KEY

   When a direct READ is executed, based on an alternate index for which

   duplicates exist, only the first record in the data set (base cluster)

   with that alternate key value is retrieved.  You need a series of READ

   NEXT statements to retrieve each of the data set records with the same

   alternate key.  A FILE STATUS value of '02' is returned if there are more

   records with the same alternate key value to be read; a value of '00' is

   returned when the last record with that key value has been read.          

Opening a File (ESDS, KSDS, or RRDS)

   How you code your OPEN statement for a VSAM file depends on whether the

   file is an empty file or a loaded file.

   To open a file that has never contained records (an empty file):

 |     Use OPEN OUTPUT for ESDS files.

     Use OPEN OUTPUT or OPEN EXTEND for KSDS and RRDS files.  (Either

     coding has the same effect.)  If you have coded the file for random or

     dynamic access, you can also use OPEN I-O if the file is optional.

   To open a file that already contains records (a loaded file):

       Use OPEN INPUT, OPEN I-O, or OPEN EXTEND

       °   For an ESDS or RRDS file opened EXTEND, the added records are

           placed after the last existing records in the file.

       °   For a KSDS file opened EXTEND, each record you add must have a

           record key higher than the highest record in the file.

   A file that once contained records, all of which have been deleted, can be

   opened as I-O or EXTEND.

   In every case, you should check the file status key after each OPEN statement.

Subtopics:

       1 Initially Loading a File Sequentially

       2 Initially Loading a File Randomly or Dynamically

       3 Loading a VSAM Data Set with Access Method Services

           

 Loading a VSAM Data Set with Access Method Services

   You can load or update a VSAM data set with the IDCAMS REPRO command.  See

   your Access Method Services Reference manual.  REPRO should be used

   whenever possible. 

File Position Indicator

   The file position indicator indicates the next record to be accessed for

   sequential COBOL requests.  You do not specify the file position indicator

   anywhere in your program.  The file position indicator is set by

   successful OPEN, START, READ, and READ NEXT statements.  Subsequent READ

   or READ NEXT requests then use the established file position indicator

   position and update it.

   The file position indicator is not used or affected by the output

   statements WRITE, REWRITE, or DELETE.  The file position indicator has no

   meaning for random processing. 

The Importance of the File Status Key

   All errors in processing a VSAM file, whether logic errors in your program

   or I/O errors on the external storage media, return control to your COBOL

   program.  When an error occurs, the status key value will indicate the

   status of the last request on the file.  Refer to VS COBOL II Application

   Programming Language Reference if you need to know the status key values

   and their meanings for VSAM files.

   Because file problems do not usually cause an abend, it is possible that

   your program will continue executing with invalid information.  Good

   coding practice demands that you check the file status key value after

   every input/output request (including OPEN and CLOSE).  Each VSAM file

   should have its own status key defined in your program.  For more

   information, see "File Status Key" in topic 4.4.3.

   You can also use an ERROR/EXCEPTION declarative for handling input/output

   errors for VSAM files

Coding Input/Output Statements

   VSAM file processing involves seven COBOL statements:

   OPEN

       Connect the VSAM data set to your COBOL program for processing.

   WRITE

       Add records to a file or load a file.

   START

       Establish the current location in the cluster for a READ NEXT

       statement.

       START does not retrieve a record; it only sets the current record

       pointer, described under "File Position Indicator" in topic 4.3.5.2.

   READ and READ NEXT

       Retrieve records from a file.

   REWRITE

       Update records.

   DELETE

       Logically remove records from indexed and relative files only.

   CLOSE

       Disconnect the VSAM data set from your program.

   All of the following determine which input/output statements are valid for

   a given VSAM data set:

   °   Access mode (sequential, random, or dynamic)

   °   File organization (ESDS, KSDS, or RRDS)

   °   Mode of OPEN statement (INPUT, OUTPUT, I-O, or EXTEND).

   Figure  shows the possible combinations with sequential files (ESDS).

   The 'X' indicates that the specified statement may be used with the open

   mode given at the top of the column.

    _____________________________________________________________________ 

   | Figure     Valid COBOL Statements with Sequential Files (ESDS)      |

   |____________ ____________ __________ __________ __________ __________|

   |            | VS COBOL II|   OPEN   |   OPEN   |   OPEN   |   OPEN   |

   | Access Mode| Statement  |   INPUT  |  OUTPUT  |    I-O   |  EXTEND  |

   |____________|____________|__________|__________|__________|__________|

   | Sequential | OPEN       |     X    |     X    |     X    |     X    |

   |____________|____________|__________|__________|__________|__________|

   |            | WRITE      |          |     X    |          |     X    |

   |____________|____________|__________|__________|__________|__________|

   |            | START      |          |          |          |          |

   |____________|____________|__________|__________|__________|__________|

   |            | READ       |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | REWRITE    |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | DELETE     |          |          |          |          |

   |____________|____________|__________|__________|__________|__________|

   |            | CLOSE      |     X    |     X    |     X    |     X    |

   |____________|____________|__________|__________|__________|__________|

   Figure  shows the possible combinations with indexed (KSDS) and relative

   (RRDS) files.  The 'X' indicates that the specified statement may be used

   with the open mode given at the top of the column.

    _____________________________________________________________________ 

   | Figure  Valid COBOL Statements with Indexed Files (KSDS) and        |

   |            Relative Files (RRDS)                                    |

   |____________ ____________ __________ __________ __________ __________|

   |            | VS COBOL II|   OPEN   |   OPEN   |   OPEN   |   OPEN   |

   | Access Mode| Statement  |   INPUT  |  OUTPUT  |    I-O   |  EXTEND  |

   |____________|____________|__________|__________|__________|__________|

   | Sequential | OPEN       |     X    |     X    |     X    |     X    |

   |____________|____________|__________|__________|__________|__________|

   |            | WRITE      |          |     X    |          |     X    |

   |____________|____________|__________|__________|__________|__________|

   |            | START      |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | READ       |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | REWRITE    |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | DELETE     |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | CLOSE      |     X    |     X    |     X    |     X    |

   |____________|____________|__________|__________|__________|__________|

   |            |            |          |          |          |          |

   |____________|____________|__________|__________|__________|__________|

   | Random     | OPEN       |     X    |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | WRITE      |          |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | START      |          |          |          |          |

   |____________|____________|__________|__________|__________|__________|

   |            | READ       |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | REWRITE    |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | DELETE     |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | CLOSE      |     X    |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            |            |          |          |          |          |

   |____________|____________|__________|__________|__________|__________|

   | Dynamic    | OPEN       |     X    |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | WRITE      |          |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | START      |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | READ       |     X    |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | REWRITE    |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | DELETE     |          |          |     X    |          |

   |____________|____________|__________|__________|__________|__________|

   |            | CLOSE      |     X    |     X    |     X    |          |

   |____________|____________|__________|__________|__________|__________|

File Access Modes

   You can only access records in VSAM sequential files sequentially.  You

   can access records in VSAM indexed and relative files in three ways:

   sequentially, randomly, or dynamically.

   1.  Sequential access--Specify ACCESS IS SEQUENTIAL in the FILE-CONTROL

       entry.

       For indexed files, records are accessed in the order of the key field

       selected (either primary or alternate).

       For relative files, records are accessed in the order of the relative record numbers.

   2.  Random access--Specify ACCESS IS RANDOM in the FILE-CONTROL entry.

       For indexed files, records are accessed according to the value you place in a key field.

       For relative files, records are accessed according to the value you place in the relative key.

   3.  Dynamic access--Specify ACCESS IS DYNAMIC in the FILE-CONTROL entry.

       Dynamic access is a mixed sequential-random access within the same

       program.  Using dynamic access, you can write one program to perform

       both sequential and random processing, accessing some records in

       sequential order and others by their keys.

       For example, suppose you had an indexed file of employee records, and

       the employee's hourly wage formed the record key.  Also, suppose your

       program was interested in those employees earning between $7.00 and

       $9.00 per hour and those earning $15.00 per hour and above. To do

       this, retrieve the first record randomly (with a random-retrieval

       READ) based on the key of 0700.  Next, begin reading sequentially

       (that is, using READ NEXT) until the salary field exceeds 0900.  You

       would then switch back to a random read, this time based on a key of

       1500.  After this random read, switch back to reading sequentially

       until you reach the end of the file.

   

VSAM File Organization

   The physical organization of VSAM data sets differs considerably from

   those used by other access methods.  VSAM data sets are held in control

   intervals and control areas; the size of these is normally determined by

   the access method, and the way in which they are used is not visible to

   you.

   There are three types of file organization you can use with VSAM 

   VSAM sequential file organization

       Also referred to as VSAM ESDS (Entry-Sequenced Data Set) organization.

   VSAM indexed file organization

       Also referred to as VSAM KSDS (Key-Sequenced Data Set) organization.

   VSAM relative file organization

      Also referred to as VSAM RRDS (Relative-Record Data Set) organization.

  Note:  Throughout this book, the term VSAM relative-record data set (or

  RRDS) is used to mean both relative-record data sets with fixed-length

  records and with variable-length records, unless they need to be

  differentiated.

   For all VSAM data set processing, you can use either fixed- or

  variable-length record formats without any special coding.  If you cannot

  or choose not to use VSAM variable-length RRDS, you can use "COBOL

  simulated variable-length relative data sets."  For information on using

  simulated variable-length relative data sets, see Appendix C, "Processing

  Simulated Variable-Length RRDS".

    ________________________________________________________________________ 

   | Figure     Comparison of VSAM Data Sets                                |

   |_______________________ ________________________ _______________________|

   | Entry-Sequenced       | Key-Sequenced          | Relative-Record       |

   | Data Set              | Data Set               | Data Set              |

   |_________________      |________________________|_______________________|

   | Records are in order  | Records are in         | Records are in        |

   | in which they are     | collating sequence     | relative record       |

   | written.              | key field.             | number order.         |

   |_______________________|________________________|_______________________|

   | Access is sequential. | Access is by key       | Access is by relative

   |                       | through an index.      | record number, which 

   |                       |                        | is treated like a key.                                                                                                    

     

   |_______________________|________________________|_______________________|

   | May have one or more  | May have one or more   | May not have          |

   | alternate indexes,    | alternate indexes.     | alternate indexes.    |

   | though not supported                                                 

   | in COBOL.                                    

   |_______________________|________________________|_______________________|

   | A record's RBA        | A record's RBA can     | A record's relative   |

   | (relative byte        | change.                | record number cannot  |

   | address) cannot       |                        | change.               |

   | change.               |                        |                       |

   |_______________________|________________________|_______________________|

   | Space at the end of   | Distributed free space | For fixed-length      |

   | the data set is used  | is used for inserting  | RRDS, empty slots in  |

   | for adding records.   | records and changing   | the data set are used |

   |                       | their lengths in       | for adding records.   |

   |                       | place.                 | For variable-length   |

   |                       |                        | RRDS, distributed     |

   |                       |                        | free space is used    |

   |                       |                        | for adding records    |

   |                       |                        | and changing their    |

   |                       |                        | lengths in place.     |

   |_______________________|________________________|_______________________|

   | A record cannot be    | Space given up by a    | Space given up by a   |

   | deleted, but you can  | deleted or shortened   | deleted record can be |

   | reuse its space for a | record is              | reused.               |

   | record of the same    | automatically          |                       |

   | length.               | reclaimed within a     |                       |

   |                       | control interval.      |                       |

   |_______________________|________________________|_______________________|

   | Can have spanned      | Can have spanned       | Cannot have spanned   |

   | records.              | records.               | records.              |

   |_______________________|________________________|_______________________|

   | Can be reused as a    | Can be reused as a     | Can be reused as a    |

   | work file unless it   | work file unless it    | work file.            |

   | has an alternate      |  has an alternate      |                       |

   | index, is associated  | index, is associated   |                       |

   | with key ranges, or   | with key ranges, or    |                       |

   | exceeds 123 extents   | exceeds 123 extents    |                       |

   | per volume.           | per volume.            |                       |

   |_______________________|________________________|_______________________|