Installing and configuring remote VSAM support for VSAM Connector Server

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

To set up z/OS and Rational® Business Developer for remote VSAM support, you must install and configure the EGLVsamCon VSAM handler module on the z/OS system. EGLVsamCon is an archive file that contains a set of Java programs. Those programs handle the VSAM access requests and return the results. The following instructions assume that Java Runtime Environment version 1.5 or higher is already installed and configured. You do not need to apply any special configurations during Java installation for the VSAM Connector Server.

Transfer EGLVsamCon to z/OS

  1. Use z/OS UNIX System Services (USS) to create a directory to which you can transfer EGL VSAM Connector Server files. These instructions assume you created a directory named /u/auser/EGLVSAMCon.
  2. Locate the EGLVsamCon.jar file in your Rational Business Developer installation folder:
    installDir\eclipse\plugins\com.ibm.etools.egl.vsam_version\EGLVsamCon.jar
  3. Transfer the EGLVsamCon.jar archive to z/OS by using FTP in binary mode:
    1. Initiate® the session:
      ftp hostname
    2. Enter your user name and password when prompted.
    3. Enter the following commands:
      bin
      cd /u/auser/EGLVSAMCon
      put EGLVsamCon.jar
  4. Locate the following library in your Rational Business Developer installation folder:
    installDir\eclipse\plugins\com.ibm.etools.egl.vsam_version\
          binaries\noncics\libEGLConSrvrUtility.so
  5. Transfer the libEGLConSrvrUtility.so library to z/OS by using FTP in binary mode:
    1. Initiate the session:
      ftp hostname
    2. Enter your user name and password when prompted.
    3. Enter the following commands:
      bin
      cd /u/auser/EGLVSAMCon
      put libEGLConSrvrUtility.so

Prepare the EGL VSAM Connector Server start-up JCL

The main class for the EGLVsamCon.jar file is com.ibm.etools.egl.vsam.host.zos.EGLConSrvr. The EGLConSrvr, when running, listens to the requests coming from a specified port and returns the results to that port. Start EGLConSrvr as you would any other Java program, using the following JCL. This JCL calls JVMPRC50 and passes the specified arguments using ARGS. In this example, the specified port is 5553.
//EGLVSAMC JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//PROCLIB JCLLIB ORDER=SYS1.PROCLIB
//* TODOs
//* 1. Tailor the JCL to suite the installation of Java.
//* 2. Review EGLVsamCon_HOME.
//* 3. Review the first argument to EGLSRV step to configure port.
//* 4. Add TRACE as second argument to EGLSRV step to enable log.
//EGLSRV EXEC PROC=JVMPRC50,VERSION='50',
// JAVACLS='com.ibm.etools.egl.vsam.host.zos.EGLConSrvr',
// ARGS='5553'
//STDENV DD *
export EGLVsamCon_HOME=/u/auser/EGLVSAMCon
export JAVA_HOME=/usr/lpp/java/J5.0
export PATH=/bin:"${JAVA_HOME}"/bin:"${EGLVsamCon_HOME}"

LIBPATH=/lib:/usr/lib:"${JAVA_HOME}"/bin
LIBPATH="$LIBPATH":"${JAVA_HOME}"/bin/classic
LIBPATH="$LIBPATH":"${EGLVsamCon_HOME}"
export LIBPATH="$LIBPATH":

CLASSPATH="${JAVA_HOME}/lib/tools.jar"
CLASSPATH="$CLASSPATH":"${EGLVsamCon_HOME}/EGLVsamCon.jar"
export CLASSPATH="$CLASSPATH":

# Configure JVM options
IJO="-Xms64m -Xmx128m"
groupname='id -gn'
export IBM_JAVA_OPTIONS="$IJO "
export JAVA_DUMP_HEAP=false
export JAVA_PROPAGATE=NO
export IBM_JAVA_ZOS_TDUMP=NO
//
To enable a detailed log, add the keyword TRACE as a second parameter:
// ARGS='5553 TRACE'

Start the EGL VSAM Connector Server

EGL VSAM Connector Server creates a Java thread to handle each VSAM access request. The thread uses the ID of the requester (as opposed to the user who started the EGL VSAM Connector Server) so that it can access only the VSAM files that the requester has access to. Therefore the user who starts the EGL VSAM Connector Server requires one of the following authorizations:
  • Read or update access to the BPX.SERVER resource profile in the FACILITY class
  • Superuser status

To start the server:

  1. Use the following command to turn on the program-control flag for the libEGLConSrvrUtility.so library:
    extattr +p libEGLConSrvrUtility.so
  2. Submit the EGLVSAMC JCL from the previous section to start EGL VSAM Connector Server.

If the server fails to start, you will see an error message in the log file. Otherwise the server starts listening to the specified port and returns the results from any requests.

To shut down the EGL VSAM Connector Server, cancel the job:
/p EGLVSAMC

Configure EGL

  1. You need a valid user ID and password to access remote VSAM files on z/OS:
    • 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:
        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:
      ZOS:\\install_dns_or_ip:port\dataset
      install_dns_or_ip
      The location where z/OS is installed
      port
      The port EGL VSAM Connector Server is listening to
      dataset
      The name of the VSAM file
      In the following example, the VSAM file name is userid.INFO.ORDERS. Omitting quotation marks causes the user ID to be added as a prefix to the file name:
      ZOS:\\ZOSMVS01:5553\//INFO.ORDERS
      In the following example, the VSAM file name is CUST.INFO.ORDERS. The single quotation marks cause the file name to be interpreted literally:
      ZOS:\\ZOSMVS01:5553\//'CUST.INFO.ORDERS'
      In the next example, the VSAM Connector Server startup JCL contains the following definition for ORDERS:
      //ORDERS DD   DSN=CUST.INFO.ORDERS,DISP=SHR
      Because of this definition, you can use the DD name in the systemName property:
      ZOS:\\ZOSMVS01:5553\//DD: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.

Feedback