KSDS is a short form of Key Sequential Data Set. KSDS is a very commonly used dataset among all types of VSAM datasets.

KSDS allows fixed-length or variable-length logical records. KSDS datasets have most of the similar characteristics as ISAM and contain both DATA and INDEX components.

Records initially loaded in DATA components in ascending order by key and can be accessed (retrieved or deleted or inserted) by a field, by a key, or by an RBA.

The DATA component has all the data records in a logical ascending order based on the key. The INDEX component has pointers to all data records(every data record has a corresponding pointer) to access data. The key is unique, and each record inserted should have a unique key.

The records are always inserts in sorted order based on the key value. For example, let us assume we are trying to insert a record with 100 key-value; it inserts after the highest key, which is less than 100( the key may be <=99).

  • If a record is newly insered, then the records after the newly inserted record will be reorganized to maintain the logical order for easy retrieval.
  • If any record gets deleted, then the records after the deleted record will be reorganized to maintain the logical order for easy retrieval.
  • If any record is updated, there will be no change in positions.

Key (primary key) must be unique, is a combination of one or more fields, and is used as a search component to process the records.

Key restrictions -

  • Key length should be the same in all logical records.
  • Key length can be from 1 to 255 bytes.
  • Key offset (from the record starting) should be the same in all logical records.
  • The key value should be unique and no duplicates allowed in all logical records.
  • Key cannot get altered once specified during the creation of the file.
  • The fields after the key get compressed if we are trying to compress a logical record.

Access types -

VSAM KSDS always uses the INDEX component to access records from the DATA component in ascending or descending order by key. KSDS supports three types of accesses types, and those are -

  • Sequential access
  • Direct access
  • Skip sequential or dynamic access

All the above access types support loading, retrieving, updating, inserting, and deleting records in an existing KSDS data set.

Sequential access -

Sequential access uses to retrieving (reading) or inserting (writing) the records sequentially.

We need to specify the key-value when retrieving (reading) or to insert (writing) records.

The main advantage of sequential access is that it avoids searching the index more than once.

Sequential access is faster than direct when accessing multiple data records in ascending key order.

Direct access -

Direct access uses to process the records directly by using key value. The application program should provide a key value for each record to be processed (read or written).

The key value can be full or generic(partial). The generic(partial) key is the high-order portion of a full key. For example, We might plan to retrieve all records whose keys begin with MTH (where MTH is the generic key), regardless of the full key value.

Skip-sequential access -

Skip-sequential access is a combination of the above two accesses. The application provides one key-value randomly, and from the located logical record, all records are processed sequentially.

Skip sequential access avoids multiple retrieval attempts by retrieving the entire data set sequentially, retrieving the records directly.

DEFINE KSDS -

KSDS data set can be created using the INDEXED parameter in the IDCAMS DEFINE CLUSTER command.

Syntax -

JCL syntax for creating KSDS dataset with minimum parameters -

//JOB CARD
//*------------------------------------------------------------------
//* Definition of KSDS
//*------------------------------------------------------------------
//STEP01  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*   
//SYSOUT   DD SYSOUT=*  
  DEFINE CLUSTER(NAME(userid.CLUSTER.NAME)  -     
    RECORDSIZE(avg max)    		-                     
    CYLINDERS(primary secondary)    	-                     
    FREESPACE(primary secondary)    	-                     
    KEYS(length,offset)            	-                     
    CISZ(ci-size)           		-                     
    VOLUMES(volume-name)      		-                     
    INDEXED              		-                     
    REUSE  )             		-                     
  INDEX(NAME(userid.CLUSTER.NAME.INDEX))	-        
  DATA(NAME(userid.CLUSTER.NAME.DATA))             	 
/*

In the above syntax,

  • The INDEXED parameter specifies the file that is creating is KSDS.
  • The remaining parameters usage is almost identical for ESDS or KSDS. Note that the values in the parameter might change.

Create Fixed-length KSDS JCL -

Requirement - Create KSDS with fixed-length records of size 47 bytes.

Code -

Create KSDS JCL
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
***************************** Top of Data ******************************
//MATEGJK JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//************************************************************          
//* DEFINE VSAM FIXED-LENGTH KSDS CLUSTER                               
//************************************************************          
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD SYSOUT=*                                                  
//SYSOUT   DD SYSOUT=*                                                  
//SYSIN    DD  *                                                        
  DEFINE CLUSTER(NAME(MATEGJ.TEST.KSDS)  -                              
    RECORDSIZE(47,47)    -                                              
    CYLINDERS(2,1)       -                                              
    FREESPACE(10,20)     -                                              
    KEYS(3,0)            -                                              
    CISZ(4096)           -                                              
    VOLUMES(DEVHD4)      -                                              
    INDEXED              -                                              
    REUSE  )             -                                              
  INDEX(NAME(MATEGJ.TEST.KSDS.INDEX)) -                                 
  DATA(NAME(MATEGJ.TEST.KSDS.DATA))                                     
/*                                                                      
**************************** Bottom of Data ****************************

In the above JCL, MATEGJ is the userid and changes all as required.

Output -

Once the above JCL is submitted, check the MAXCC of the job for any errors. If the MAXCC is 00 or 04, RRDS successfully created.

Create KSDS Output

Verify the KSDS in 3.4 (Dataset List utility) or any File management tools.

Create KSDS Output

Explaining Example -

In the above example,

  • RECORDSIZE(47,47) specifies the record average length is 47, and the maximum length is 47. So the KSDS file we are creating is fixed-length.
  • CYLINDERS(2,1) specifies the primary memory allocation is 2 CYLINDERS, and secondary memory allocation is 1 CYLINDER.
  • KEYS(3,0) specifies the key length is 3 bytes from the starting position 0.
  • CISZ(4096) specifies the control interval size is 4096.
  • VOLUMES(DEVHD4) specifies that allocate the ESDS on volume DEVHD4.
  • INDEXED parameter specifies the file is to create KSDS.
  • REUSE specifies the memory can reuse immediately once the file gets deleted.
Note! In the above example, the KSDS file was created with minimum parameters. Add the additional parameters based on the requirements. Refer total parameters description in Define Cluster topic.

Create Variable-length KSDS JCL -

Requirement - Create KSDS with variable-length records of average size 47 and maximum size 67 bytes.

Code -

Create KSDS JCL
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
***************************** Top of Data ******************************
//MATEGJK JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//************************************************************          
//* DEFINE VSAM VARIABLE LENGTH KSDS CLUSTER                            
//************************************************************          
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD SYSOUT=*                                                  
//SYSOUT   DD SYSOUT=*                                                  
//SYSIN    DD  *                                                        
  DEFINE CLUSTER(NAME(MATEGJ.TEST.VKSDS)  -                             
    RECORDSIZE(47,67)    -                                              
    CYLINDERS(2,1)       -                                              
    FREESPACE(10,20)     -                                              
    KEYS(3,0)            -                                              
    CISZ(4096)           -                                              
    VOLUMES(DEVHD4)      -                                              
    INDEXED              -                                              
    REUSE  )             -                                              
  INDEX(NAME(MATEGJ.TEST.VKSDS.INDEX)) -                                
  DATA(NAME(MATEGJ.TEST.VKSDS.DATA))                                    
/*                                                                      
**************************** Bottom of Data ****************************

In the above JCL, MATEGJ is the userid and changes all as required.

Output -

Once the above JCL is submitted, check the MAXCC of the job for any errors. If the MAXCC is 00 or 04, RRDS successfully created.

Create KSDS Output

Verify the KSDS in 3.4 (Dataset List utility) or any File management tools.

Create KSDS Output

Explaining Example -

In the above example,

  • RECORDSIZE(47,67) specifies the record average length is 47, and the maximum length is 67. So the KSDS file we are creating is variable-length.
  • CYLINDERS(2,1) specifies the primary memory allocation is 2 CYLINDERS, and secondary memory allocation is 1 CYLINDER.
  • KEYS(3,0) specifies the key length is 3 bytes from the starting position 0.
  • CISZ(4096) specifies the control interval size is 4096.
  • VOLUMES(DEVHD4) specifies that allocate the ESDS on volume DEVHD4.
  • INDEXED parameter specifies the file is to create KSDS.
  • REUSE specifies the memory can reuse immediately once the file gets deleted.

Advantages -

  • Easy and fast creation.
  • Complete access to the dataset.
  • Can have alternate index.
  • Can access the records sequentially, randonly and dynamicallu(Skip-sequential).

Disadvantages -

  • Records should be in the sorted order based on the key before loading.

Usage -

KSDS used when -

  • Applications require each record have a key field.
  • Applications require both direct and sequential access.
  • Applications use high-level languages that do not support RBA use.
  • Online applications use key-sequenced data sets.

Loading Data to KSDS -

Loading data to KSDS can be done in three ways -

  • Using utilities.
  • Using File Management Tools[Covered in tools section in future].
  • Through programmatically[Covered as part of COBOL tutorial ].

Using utilities -

IDCAMS utility used to load the data to KSDS from input like below -

If the records count is more, load the records to a flat file(PS) and copy PS's data to KSDS. To do that, use the JCL below -

Code -

Loading KSDS
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
***************************** Top of Data ******************************
//MATEGJR JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//************************************************************          
//* LOADING DATA TO KSDS FROM PS(FLAT FILE)                             
//************************************************************          
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD   SYSOUT=*                                                
//INPUT    DD   DSN=MATEGJ.TEST.DATA,DISP=SHR                           
//OUTPUT   DD   DSN=MATEGJ.TEST.KSDS,DISP=SHR                           
//SYSIN    DD   *                                                       
      REPRO    -                                                        
           INFILE(INPUT)   -                                            
           OUTFILE(OUTPUT)                                              
/*                                                                      
**************************** Bottom of Data ****************************

In the above JCL, MATEGJ.TEST.DATA is the flat file and MATEGJ.TEST.KSDS is the KSDS file.

Output -

Once the above JCL is submitted, check the MAXCC of the job for any errors. If the MAXCC is 00 or 04, RRDS loaded successfully with records from PS file.

loading KSDS Output

Verify the KSDS in 3.4 (Dataset List utility) or any File management tools.

loading KSDS Output

Explaining Example -

In the above example, all the records from the MATEGJ.TEST.DATA(flat file of length 47) file copied to MATEGJ.TEST.KSDS(KSDS file of length 47) file.

Note! The flat file(PS) and KSDS file should have the same record length(47 in the above example) to load the data successfully.

Delete KSDS -

Requirement - Delete KSDS using the IDCAMS utility.

Code -

Delete KSDS
----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
***************************** Top of Data ******************************
//MATEGJD JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//************************************************************          
//* DELETING KSDS                                                       
//************************************************************          
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD   SYSOUT=*                                                
//SYSIN    DD   *                                                       
      DELETE 'MATEGJ.TEST.KSDS'                                         
/*                                                                      
**************************** Bottom of Data ****************************

In the above JCL, MATEGJ.TEST.KSDS is the KSDS name that is planned to delete.

Output -

Once the above JCL is submitted, check the MAXCC of the job for any errors. If the MAXCC is 00 or 04, KSDS successfully got deleted.

DELETE KSDS Output

Verify the KSDS in 3.4 (Dataset List utility) or any File management tools if required to double-check.

DELETE KSDS Output

Explaining Example -

In the above example, the MATEGJ.TEST.KSDS (KSDS file) successfully deleted and uncatalogued(space released).

Note! If the file is already deleted and trying to delete the file again, we may receive MAXCC as 08. So, verify the file once before proceeding for delete.

How to use KSDS in the COBOL program?

Fixed-length KSDS files -

Requirement - Define the fixed-length KSDS file for RANDOM access in the COBOL program.

Let us assume MATEGJ.TEST.KSDS is the KSDS file with the record length 47, and it is defined like below in the COBOL program.

In Environment Division -

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
	SELECT KSDS-1 ASSIGN to INPUT.
	ORGANIZATION IS INDEXED.
	ACCESS MODE IS RANDOM.
	RECORD KEY IS KSDS-KEY-1.
	FILE STATUS IS file-status1.

In Data Division -

DATA DIVISION.
FILE SECTION.
FD KSDS-1.
	RECORD CONTAINS 47 CHARACTERS.
	BLOCK CONTAINS 470 CHARACTERS.
	DATA RECORD is KSDS-RECORD-1.
	RECORDING MODE IS F.

01 KSDS-RECORD-1.
	05 KSDS-KEY-1    PIC X(03).
	05 KSDS-REC-PART PIC X(44).

In the above example, KSDS-1 is the file-name used to represent the KSDS file in the COBOL program. INPUT is the DDNAME used to map with the JCL DDNAME specified corresponding to the KSDS file. For example, //INPUT DD DSN=MATEGJ.TEST.KSDS,DISP=SHR.

KSDS-RECORD-1 represents the logical record used to insert the data to a file or read the data from a file.

Variable-length KSDS files -

Requirement - Define the variable-length KSDS file for DYNAMIC access in the COBOL program.

Let us assume MATEGJ.TEST.VKSDS is the variable-length KSDS file with rectord length 47 to 67, and it is defined like below in the COBOL program.

In Environment Division -

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
	SELECT KSDS-2 ASSIGN to INPUTV.
	ORGANIZATION IS INDEXED.
	ACCESS MODE IS DYNAMIC.
	RECORD KEY IS KSDS-KEY-2.
	FILE STATUS IS file-status2.

In Data Division -

DATA DIVISION.
FILE SECTION.
FD KSDS-2.
	RECORD CONTAINS 47 TO 67 CHARACTERS.
	BLOCK CONTAINS 470 TO 670 CHARACTERS.
	DATA RECORD is KSDS-RECORD-2.
	RECORDING MODE IS V.

01 KSDS-RECORD-2.
	05 KSDS-KEY-2    PIC X(03).
	05 KSDS-REC-PART PIC X(64).

In the above example, KSDS-2 is the file-name used to represent the KSDS file in the COBOL program. INPUT is the DDNAME used to map with the JCL DDNAME specified corresponding to the KSDS file. For example,

//INPUTV DD DSN=MATEGJ.TEST.VKSDS,DISP=SHR.

KSDS-RECORD-2 represents the logical record used to insert the data to a file or read the data from a file.