Step 3 - Create A VSAM database

In this blog-post we going to take a look on permanent datastorage with KICKS.

See previous steps for a better understanding.

In order to be able to store data what we enter via KICKS to a DASD (harddisk) we need to create a so called VSAM cluster. This is an allocation on the disk where we are able to store our records.

The following is for TK4

The record storing is almost hassle free in KICKS, because we can easily approach our records with a record key. It is very fast that way to get a certain record out of the VSAM cluster, or sometimes just called the database.

Simple COBOL/KICKS/CICS instruction to read a record:

        EXEC CICS READ FILE ('VSAM-CLUSTER-DATABASE')
                  INTO (RECORD-DEFINITION)
                  RIDFLD (RECORD-KEY)
        END-EXEC.


It is however nothing like a SQL database!. You can compare it to a random access database as was in implemented in for example, GWBasic long time ago under MS-DOS. We are only able to store, update or delete a record by its record key. You will see in next blog post that this is very handy, because KICKS/CICS has some easy to use features what takes advantage of those record keys.

Before we create the database we need to determine very carefully the record layout. Think deeply about the record fields, there are obviously often more fields then on the BMS map defined, (see post about creating a BMS map), because changing afterwards involves a database copy to a different layout (structure) what brings extra (complex) work. 

The record layout must be created, or defined, as a COBOL variable as shown below, and the member must be placed in your copybook dataset. A simple copy record-layout-member command in COBOL will include it during compilation. This is not a must. You can include the record data in your COBOL program, but maintaining is more difficult. When using a copybook member for this a simple record update and recompile of the COBOL sources and all are updated. (The VSAM cluster of course needs to be copied to the new layout (or structure if you will) also. But thats for another blog post, one where we also go into other pitfalls like VSAM PATH files.



Sum all field lengths together, wich give you the byte size of the record. This must be correct, so check it again!. Wrong length will give hard to find errors and bugs later on. (pitfall)
After determining the record size we can execute a JCL job that creates the VSAM cluster like below:



This has a different record size, to keep you sharp, and BIS is the HLQ.

//VSAMCREA JOB (1),'CREATE VSAM',CLASS=A,MSGCLASS=H,
//          MSGLEVEL(1,1),REGION=4M,NOTIFY=HERC01
//DELDEF EXEC PGM=IDCAMS,REGION=1024K                             
//SYSPRINT DD SYSOUT=*                                            
//SYSIN DD *                                                      
 DELETE BIS.VSAM.TEST                                             
 SET MAXCC = 0                                                    
 DEFINE CLUSTER                                     -           
     (NAME(BIS.VSAM.TEST) INDEXED                   -             
      VOLUMES(PUB020)                               -           
      TRACKS(15 15)                                 -           
      SHAREOPTIONS(1 3) UNIQUE                      -           
      RECORDSIZE(934 934) NONSPANNED                -             
      KEYS(6 0)                                     -           
     )                                              -           
    DATA ( NAME(BIS.VSAM.TEST.DATA))                -             
   INDEX ( NAME(BIS.VSAM.TEST.INDEX))                             
/*                                                                
//    
                                                             


The JCL procedure has a few interesting points you need to address:

  • The location of the cluster. If you going to add a lot of records then you can run out of space. Best is to create and add an decicated DASD for the cluster(s). Calculate the record length times the assumed total of records to expect to store, and use those bytes to determine the size. If enough space, be generous, you will not regret it later on.
  • The key length in bytes is of high importance, and this field must be in the JCL definition, as you defined in the record. The key field is also stored in the record definition.
  • The record size as discussed above.
  • And, note that this JCL first attempts to delete the old one, thus removing all your old data, and then creates a new one. Four references to the same members are to be changed.
This concludes the creation of the VSAM cluster, file, member or dataset, whatever you want to call this member.





To use it in KICKS under MVS 3.8J TK4 it must be declared in the FCT table in KICKS, AND equally important, also in the CLIST member where KICKS is been started with. The CLIST is needed to allocate the VSAM cluster, wich in CICS isnt needed, but in TK4 it is mandatory. 
We will take a deeper look in the CLIST and the FCT in upcomming blog posts but for now you can add it to the FCT like this:


And adding it at three (3) places in the CLIST, one to FREE it if allocated, one to ALLOCate it properly and one mention of FREE again after KICKS quits execution.

No comments:

Post a Comment