KSDS (for Experienced)


  • KSDS is a short form of Key Sequential Data Set.
  • KSDS is a very commonly used dataset among all types of VSAM datasets.
  • KSDS datasets have the most similar features as ISAM and contain DATA and INDEX components. 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.
  • KSDS allows fixed-length or variable-length records.
  • Records are initially loaded in ascending order by key-value and can be accessed (retrieved or deleted or inserted) by a field, a key, or an RBA.
  • A key identifies each record uniquely, and a key is a field in a predefined position within the logical record.
  • The records are always inserted in sorted order based on the key value. For example, let us assume we are trying to insert a record with a 100 key value; it inserts after the record with the highest value of less than 100.
  • The records are reorganized as specified below for each operation -
    • If a record is newly inserted, then the records after the newly inserted record will be reorganized to maintain the logical order for easy retrieval.
    • If any record gets deleted, the records after the deleted one will be reorganized to maintain the logical order for easy retrieval.
    • If any record is updated, there will be no change in positions.

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, and those are -

Access Type Description
Sequential Access
  • Sequential access uses to retrieve (reading) or inserting (writing) the records sequentially.
  • When retrieving (reading) or inserting (writing) records, we need to specify the key value.
  • Sequential access is faster than direct when accessing multiple data records in ascending order.
Direct Access
  • Direct access uses to process the records directly by using key values.
  • 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).
Dynamic Access
or
Skip Sequential
  • Skip-sequential access is a combination of the above two accesses.
  • The application provides a key value, and all records are processed sequentially from the located logical record.
  • Skip sequential access avoids multiple retrieval attempts by retrieving the entire data set sequentially, retrieving the records directly.

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

DEFINE KSDS Syntax -


IDCAMS DEFINE CLUSTER command with INDEXED parameters used to create KSDS dataset.

Syntax - JCL for creating KSDS dataset with minimum parameters

//JOBCARD
//*------------------------------------------------------------------
//* 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 that the file created is KSDS.
  • The remaining parameters usage is almost identical for ESDS or KSDS. Note that the values in the parameter might change.

Refer IDCAMS DEFINE command for full set of parameters.

Create Fixed-length KSDS Example -


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

Code -

----+----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.

Create Variable-length KSDS Example -


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

Code -

----+----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 that 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 as 3 bytes from the starting position 0.
  • CISZ(4096) specifies that 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 that the memory can reuse immediately once the file gets deleted.

Advantages -


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

Disadvantages -


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

Usage -


KSDS used when -

  • Applications require to access the records in different access modes using a key field.
  • Applications require both direct and sequential access.
  • Applications use high-level languages that do not support RBA.
  • CICS appication preferred dataset.

Loading Data to KSDS -


Loading data to KSDS can be done in three ways -

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

Using utilities -


IDCAMS utility is used to load the data to the KSDS file from another file or instream data.

Requirement - Copy data from PS file to KSDS file.

Input PS File - MATEGJ.TEST.DATA

Code -

----+----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 the 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 Example -


Requirement - Delete KSDS using the IDCAMS utility.

Code -

----+----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 record 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.