Installing and configuring remote VSAM support for CICS®

You can use TCP/IP to access a VSAM file on a remote z/OS® or z/VSE® system from EGL-generated Java™ code or from the EGL debugger. Use CICS® to control the operation if you typically access the file through CICS® transactions.

To set up z/OS®, z/VSE®, CICS®, and Rational® Business Developer for remote VSAM support, you must install and configure the ELAVSHN VSAM handler module on the host system. The following instructions assume that CICS® Transaction Gateway is already installed and configured for the target CICS® region. CTG can be installed on any platform that the EGL-generated Java™ code or the EGL debugger can reach through TCP/IP. For more information about CTG, refer to your CICS® documentation.

If you have installed the latest version of Rational® COBOL Runtime for zSeries®, the ELAVSHN module should already be installed. Skip to the "Verify the VSAM handler" section.

Transfer ELAVSHN to z/OS®

  1. Locate the following dataset:
    installDir\eclipse\plugins\com.ibm.etools.egl.vsam_version\binaries\
   cics\EGL.VSAM.LOAD.TRS

    This dataset contains a packed partition dataset named EGL.VSAM.LOAD that includes ELAVSHN.

  2. Transfer EGL.VSAM.LOAD.TRS to z/OS® by using FTP in binary mode. Use record length 1024, block size 6144, and fixed block record format:
    1. Initiate® the session:
      ftp hostname
    2. Enter your user name and password when prompted.
    3. Enter the following commands:
      quote site lrecl=1024
quote site blocksize=6144
quote site recfm=fb
bin
put EGL.VSAM.LOAD.TRS //EGL.VSAM.LOAD.TRS

Extract the VSAM handler

Decompress the EGL.VSAM.LOAD.TRS dataset by using the following JCL. This job allocates all required attributes to the EGL.VSAM.LOAD module:
//VSHNMAKE JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//* 
UNZIP    PROC DSN=
//*
//*--------
//UNPACK   EXEC PGM=TRSMAIN,PARM=UNPACK
//SYSPRINT DD SYSOUT=*
//INFILE   DD DISP=SHR,
//            DSN=&DSN..TRS
//OUTFILE  DD DISP=(NEW,CATLG),SPACE=(CYL,(2,2,20),RLSE),
//            DSN=&DSN
//         PEND
//*--------
//*
//UNTERSE  EXEC UNZIP,DSN=EGL.VSAM.LOAD

A copy of this JCL is included in the same folder as the EGL.VSAM.LOAD.TRS. The JCL is named EGL.VSAM.LOAD.JCL(VSHNMAKE).

Set up the target CICS® region

  1. Edit the startup JCL for the target CICS® region and add an entry for the EGL.VSAM.LOAD JCL to the DFHRPL list.
  2. Log on to the target CICS® region and define and install the ELAVSHN program with the Language option set to COBOL:
    CEDA DEF PROGRAM (TEST) LANGUAGE (COBOL)
  3. Optional: Define and install a transaction to run the ELAVSHN program. Rational® COBOL Runtime names this transaction ELAV; you can assign another name:
    CEDA DEF TRAN (ELAV) PROGRAM (ELAVSHN)
  4. Restart the target CICS® region.

This completes the setup for CICS®.

Verify the VSAM handler

To verify the setup, log on to the target CICS® region and run the ELAV transaction. You should see the following message:
EGL REMOTE VSAM ACCESS. BUILD DATE yyyymmdd

If this message is not displayed, review the instructions in this topic.

VSAM dataset attributes

Each VSAM dataset should be defined in the FCT (or file RDO entries) under CICS®. Some of the attributes play an important role in how CICS® will allow access to that dataset. Set the attributes as shown in the following table unless you have a reason to choose otherwise. Use these values if you perform any of the following actions on the VSAM dataset through the EGL debugger:
  • Read
  • Write
  • Update
  • Delete
  • Browse
Table 1. Attributes for VSAM datasets
Attribute Value
LSrpoolid None
STRings 010 or higher
Add Yes
BRowse Yes
DELete Yes
Read Yes
Update Yes

Configure EGL

Configuration steps are as follows:

  1. You need a valid user ID and password to access remote VSAM files on z/OS® and z/VSE®:
    • If you intend to access the files from EGL-generated Java™ code, do as follows:
      1. Use the following EGL command to set the user ID and password and then proceed to step 5: 
        SysLib.setRemoteUser("auserid", "apassword");
      2. Proceed to step 5.
    • If you intend to access the files from the EGL debugger, store the ID and password in your EGL preferences. Click Window > Preferences > EGL > Debug.
  2. Enter a valid ID for the Remote user field.
  3. Enter a valid password for the Remote password field.
  4. Click OK to save the preferences and exit.
  5. Create a resource associations part for the EGL-generated Java™ code and for debugging and then add an association element for each VSAM data set that you intend to access:
    • Set system to win for debugging, and set that element to the target platform for run time.
    • Set fileType to vsam or ibmcobol.
    • Use the following format to set systemName:
      CTG:\\install_dns_or_ip:port\cics_region\dataset
      install_dns_or_ip
      The location where CTG is installed, regardless of platform
      port
      The port CTG is listening to
      cics_region
      The target CICS® region as defined under CTG
      dataset
      The name of the VSAM file as defined in the FCT or the File RDO entry for the CICS® region
      Examples:
      CTG:\\ANETNAME:2006\ACICSREG\AVSAMFIL
CTG:\\ZOSMVS01:2006\CICS01\ORDERS
CTG:\\192.168.123.12:2006\CICS01\ORDERS
  6. Ensure that in the build descriptors for run time and debugging, the resourceAssociations option is set to the name of the resource associations part that you created in the previous step.
  7. Make sure the ctgclient.jar file is accessible during the runtime. You might add the ctgclient.jar archive to the class path in one of the following ways:
    • Right click the project name, and then click Properties > Java Build Path. Click the Libraries tab, click Add External JARs and browse to the ctgclient.jar file.
    • Click Window > Preferences > EGL > Debug. In the Class path order section, click Add JARs and browse to the ctgclient.jar file.