Skip to main content

Appendix M: Installation and Configuration for VSAM Files

PK Protect supports detection on VSAM Files. VSAM files contain sequential record data. To read VSAM files, install the Files IDP on the Unix System Services (USS) environment on your z/OS mainframe. Controller will be installed on a remote machine.

System Requirements

Following system configurations are required for scanning the VSAM clusters:

  1.  z/OS machine version must be 2.1 or higher.

  2. Install the latest version of DSM Administrator 8.3.50+ for scanning VSAM clusters.

  3. To setup z/OS UNIX System Services (USS), minimum 8 (GB) memory and 100 (GB) disk space is required.

  4. z/OSMF must be enabled for scanning target environments i.e., Prod, Dev and Test.

  5. PKZIP 16.1.7+, Smartcrypt 16.1.7, or PK Encrypt for Z 17.0.0 must be installed across all the system where the VSAM clusters need to be accessed. 

  6. A VSAM filename to copybook filename associations

  7. XML mappings of copybook

  8. Copy of each original copybook

  9. To create a user account for installing and executing Files IDP in USS environment, contact System Administrator. Use the below sample JCL script for creating a user. The JCL script can be modified as per requirement.

//FPDAUID  JOB (123),CLASS=A,MSGCLASS=X,                      
//S0 EXEC PGM=IKJEFT01,DYNAMNBR=75                       
//SYSPRINT DD SYSOUT=*                                         
//SYSTSPRT DD SYSOUT=*                                        
//SYSTERM DD DUMMY                                            
AG pkware SUPGROUP(SYS1) GID(nnnn)
AU pkzidp DFLTGRP(pkware)  
ALU pkzidp OMVS(HOME('/u/pkzidp ') PROGRAM('/bin/sh') UID(nnnn))  
ALU pkzidp PASSWORD(xxx) 

1. AG pkware SUPGROUP(SYS1) GID(nnnn) - The pkware is a suggested name for the group. You can choose any name. The nnnn is the group ID number for the pkware group.
2. AU xxx DFLTGRP(pkware) – In this property the xxx is the default user ID thai is used for login and installing the product. The value of xxx must not exceed more than 7 characters.
3. ALU xxx OMVS(HOME('/u/xxx ') PROGRAM('/bin/sh') UID(nnnn)) – Use /u/xxx, if the default folder is pkware else you can select any folder. The UID(nnnn) is the user number associated with the xxx UID.
4. ALU xxx PASSWORD(xxx) – This is used for establishing a password.


Once user account is created, perform the below steps to install the Files IDP for scanning VSAM files.

  1. Install the Files IDP on your local machine. To know more, refer section Install Files IDP.

  2. Zip the Files IDP folder and unzip it on the z/OS host machine. This will setup the same environment on both the local and z/OS machine.

  3. Re-start the IDP. This will also start the VSAM cluster. To restart the IDP on z/OS machine enter the below command:

    java -Xms4g -Xmx8g -jar dgLocalFilesAgent-jetty.jar

  4. To restart an IDP, execute ‘sh ./’ command. To stop an IDP, execute ‘sh ./’ command.

When unzipping the IDP folder on z/OS folder, update the following properties:

  1. Open ‘’ file located at ‘…/…/DgSecure/Agents/LocalFilesAgent/’ and update the expandedArchiveLoc property. This property specifies the archiving location for File IDP.

  2. Open ‘’ file located at ‘…/DgSecure/Agents/LocalFilesAgent/expandedArchive/WEB-INF/classes/’ and update the below mentioned properties:

    1. dg.meta.dir – This property specifies the name of the DG meta directory.

    2. hadoopConfigPath – This property specifies the absolute path to directory containing the Hadoop config files.

    3. kmip.pekkeystore.path – This property specifies the KMIP PEK keystore location.


Below are the configuration settings to support detection on VSAM files.

  1. Open ‘zip.jcl’ file placed at the following location ‘…/Dataguise/vsam/jcl/’ and update the following:

    1. Edit the file and add the appropriate job card.



    2. Enter the JCLLIB where the modified PKWDGZIP proc resides.

  2. Remove the asterik (*) and change the SAMPLE(%) to desired value. Similarly, set the threshold size for
    MAXSZ using K(ilobyte), M(egabyte), or G(igabyte). By default, this parameter is commented out.

  3. Open ‘listcat.jcl’ file placed at the following location ‘…/Dataguise/vsam/jcl/’ and update the following:

    1. Edit the listcat.jcl file and add the same job card details which are added in zip.jcl



    2. Enter the same JCLLIB details which were added in the zip.jcl file.

  4. Copy the *.copybook files in the copybooks folder placed at location ‘…/Dataguise/vsam/copybooks/’. The format of each file must be ASCII UTF-8.

  5. Copy the *.xml files in the xml folder placed at location ‘…/Dataguise/vsam/xml/’. The format of each file must be ASCII UTF-8. There should be one xml file for each copybook.

  6. Open each *.xml file placed at the following location ‘…/Dataguise/vsam/xml/’. Enter the absolute path and the filename of each copybook.text file. This will create xml mapping of copybooks.


    <DatasetName>[Insert absolute path to copybook.txt file]</DatasetName>


    <Copybook name="[Insert absolute path to copybook.txt file]">

  7. Open vsam_xml_mapping.xml placed at the following location: ‘/Dataguise/vsam/layouts/’. Add the VSAM dataset name, associated xml mapping and filename in this file for every dataset that you want to scan.
    [Format]     VSAM File Names||XML Mapping path and file

  8. Open ‘’ file placed at the following location: ‘…/DgSecure/Agents/LocalFilesAgent/expandedArchive/WEB-INF/classes/’ and update the below mentioned properties:

    1. vsam.mapping.layour.file.path- This file contains the details of the VSAM file and its mapping file. If mapping for VSAM file does not exists, then that file will be skipped.

    2. vsam.file.upload.path – On this location the zip VSAM files will be uploaded by JCL job.

    3. – This property specifies the absolute path of the JCL file.

    4. Vsam.listcat.jcl.path – This property specifies the absolute path of the listcat jcl file which fetches the files based on the search string.

    5. Vsam.hostname – This property specifies the ZOS hostname.

    6. Vsam.file.unzip.dir – This property specifies the path where the extracted VSAM files are stored. The files are deleted from the location when processing is completed.

    7. Vsam.authorization.token – This property lets you specify the token used for JCL job.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.