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
- 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.
- 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:
- Initiate® the session:
ftp hostname
- Enter your user name and password when prompted.
- 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
- Edit the startup JCL for the target CICS region and add an entry for the EGL.VSAM.LOAD JCL to the
DFHRPL list.
- 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)
- 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)
- 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:
- 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:
- Use the following EGL command to set the user ID and password
and then proceed to step 5:
SysLib.setRemoteUser("auserid", "apassword");
- 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 .
- Enter a valid ID for the Remote user field.
- Enter a valid password for the Remote password field.
- Click OK to save the preferences and exit.
- 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:
- 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.
- 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 . Click the Libraries tab, click Add External JARs and browse to the ctgclient.jar file.
- Click . In the Class path order section, click Add JARs and browse to the ctgclient.jar file.
- When running an EGL Web project, make sure that ctgclient.jar and EGLVsamCon.jar are
present in the WEB-INF\lib folder of the project.
You can find EGLVsamCon.jar in the folder SHARED_PLUGINS_DIR/com.ibm.etools.egl.vsam_version, where SHARED_PLUGINS_DIR is in the form C:\Program Files (x86)\IBM\IBMIMShared\plugins (Windows) or /opt/IBM/IBMIMShared/plugins (Linux).