Rational Application Developer & WebSphere Developer for zSeries Version 6.0.1.1

Rational Application Developer
&
WebSphere Developer for zSeries
Version 6.0.1.1
Accessing CICS from the EGL Debugger
Install and Configuration
Instructions
Author: Mark Evans.
Rational – EGL Development
IBM Software Group
1
Connecting to CICS Transaction Server on z/OS using CICS Transaction
Gateway
While debugging EGL programs, many customers need to call non-EGL programs that are executing on CICS
Transaction Server for z/OS. Since the EGL debugger is running on a Windows machine, remote communications are
needed to CALL these programs. EGL uses the remote communications ability provided through the product called CICS
Transaction Gateway (CTG). CTG provides functionality for the client (the sender), a gateway functionality, and for the
server (the receiver of the call request).
There are many ways to configure the CICS Transaction Gateway product(s) and this document does not attempt to cover
them all nor does it replace the documentation provided by CICS Transaction Gateway and CICS Transaction Server.
For more detailed information on possible setups, please refer to the following documents:
CICS Transaction Gateway – Windows Administration V6 (SC34-6371) (manual)
And/or
CICS Transaction Gateway V5: The WebSphere Connector for CICS (SG24-6133) (Redbook).
This document is based on the installation and use of CICS Transaction Gateway V6.0.1 (or CTG V6), but most items
also apply to CTG V5 as well which is covered well in the Redbook.
Obtaining the required product:
If you are installing both the client and Gateway portions of CTG on the Windows box, then you need to obtain a valid
copy of CICS Transaction Gateway. This can be done by one of the following ways.
a. It is included as an “extra” CD in the media package associated with WebSphere Developer for zSeries
V6.
b. Purchase a copy of CTG V6
This document will assume that the starting point is the need for both client and server.
Another configuration option is to only put the client portion on the Windows box and communicate to a CTG server
running on z/OS. This uses the CTG Server for z/OS product that has been purchased and installed on z/OS. This
z/OS product contains a copy of the client code (ctgclient.jar) that will allow the EGL debugger to communicate with the
CTG server on z/OS.
If this configuration option is used, then you can skip to the section on configuring the workbench/EGL to call CICS and
use the appropriate host names and ports for the CTG server on z/OS when configuring EGL to call CICS.
NOTE: This document does not cover how to configure a WAS Server to use J2C, but the concepts in it also
apply if the developer would like to access CICS using the EGL CICSECI protocol from a pagehandler, program,
library, or service.
2
Obtaining the required information:
CICS Transaction Gateway can communicate through various protocols (see the administration Guide and the Redbook).
This document will describe what is needed to setup the client to communicate through TCP62 (used by many VAGen
customers) and native TCPIP (normally preferred as it does not require any SNA/VTAM setup).
NOTE: Please see the administration manuals or the Redbook listed above for information on setting up a server on the
z/OS system.
To proceed, you will need the following information depending on what protocol you are going to use. Most can be
provided by your z/OS VTAM and CICS Administrators
TCP62:
Item (from z/OS)
Configuration Tool
Example:
IP Address
Domain Suffix:
NETID
APPL
PORT
LOGMODE
Host ip address
Anynet Domain Name Suffix
Netid of Partner LU Name
APPLID of partner LU name
port address of ANYNET definition
mode name of CICS Sna connection
192.168.230.17
MYDOMAIN.COM
NET1
MYLUNM
397 (by default)
#INTER
Fully Qualified CP Name
Local LU name of workstation
$ANYNET.$GWCP
LOCLUNM
(there needs to be one per developer)
Hostname
Hostname/ip address of LPAR with
CICS TCPIP Service enabled
carmvs1.raleigh.ibm.com
Port
Port defined in TCPIPService
1435
TCP/IP
3
Installing CICS Transaction Gateway V6
The following steps can be used for the installation of CICS Transaction Gateway as a service on the developer’s
Windows machine:
NOTE: The person installing must be logged on as member of the local Administrators group or a Domain Administrator

If installed, remove previous versions of CICS Universal Client or CICS Transaction Gateway

From the install media, run the installer.exe
o

You may receive a message related to a temporary install of Java that the install job itself uses.
You should see the following introduction screen:
4

Click Next, and the following screen appears for the terms and conditions

Accept the terms and click Next…..review the readme that appears
5

Click Next, and the following appears:

Choose custom, and click Next, to choose the install location and other options for the install. To minimize the length
of your Windows PATH statement you may want to shorten the Directory name.
6

Change or keep the default location and click Next

Accept the defaults as shown above and click Next
7

Accept the defaults (this means the CTG Gateway/server will be running as a service on this machine) and click Next

Verify the information (based on your choices), Click Next and the install will begin. You will receive the following
when it is complete…..

Click Finish
8
Installing the Java Runtime Environment (depending on your system):
To run the CICS Transaction Gateway and its configuration tool, a valid Java Runtime (JRE) needs to be installed on the
machine. If there is not one already installed, you can install one provided with CTG.
You can verify whether CTG has detected whether there is a JRE on your machine by typing in the following command
from a command prompt.
ctgjava –v
This should display the directory of the JRE that you using.
If it does not detect a JRE, then you can install one by installing the one from CD2 in the d:\JRE\Windows directory or the
ibm-java2-jre-142.exe (depending on how you obtained your copy of CTG). Follow the presented instructions to install
the JRE.
Setting up the TCPIP Hosts file on your workstation (depending on the machine) and TCP62 only
If in your network, you have a TCP/IP Domain Name server to resolve host names, then the following is not required.
Otherwise, you need to add the hostname information into the Windows TCPIP hosts file using the following steps.



Go the c:\winnt\system32\drivers\etc folder
Open the file named “hosts”
Add the TCPIP address and the associated APPL.NETID.Domain Suffix. For example:
192.168.230.17
MYLUNM.NET1.mydomain.com
Where 192.168.230.17 is the ip address of the LPAR with the ANYNET installation
NET1 is the NETID
MYLUNM is the APPL name
mydomain.com is the domain suffix
SEE INFORMATION TO GATHER at the beginning for these values
9
Configuring the CTG Gateway Daemon:
You will need to configure a Client Daemon and a Gateway Daemon. The Gateway Daemon will receive requests from
the EGL Debugger via TCPIP and will convert these to a request to communicate to the CICS server through the protocol
that you specify in the client Daemon.
The steps to perform this configuration are:

Start the CTG Configuration Tool by choosing the following in Windows:
Start->All programs->IBM CICS Transaction Gateway->Configuration Tool

If this is your first time configuring CTG, you will be prompted to run a Task Guide as below.
Type in a server name….the CICS Region name or APPL name is good. This name will be used by the setup in the
EGL debugger, so it should be self-explanatory (see above)
10

Click Next and the following screen should appear.
For TCP62, click the TCP62 button.
For TCP/IP, click the TCP/IP button (and skip to the section where you specify TCPIP options).
11

(TCP62) Click Next and the following screen will appear:
Use the fully qualified CP Name, Domain suffix, and Port from the information to gather.
12

(TCP62) Click Next and fill in the following screen using the names from the information gathered at the beginning.
NETID.APPL = Partner LU
Local LU is machine dependent (each developer will have their own Local LU)
MODE Name = #INTER
13

(TCP62) Click Finish and you should get the following screen:

Check the Use upper case security checkbox

Save the configuration by using File->Save from the menu bar. Choose ctg.ini if prompted.

Skip to Setting up the Gateway Daemon
14
15
>>>>>> PLACE TO GO TO IF CONFIGURING FOR TCPIP:

(TCPIP) Click Next and the following screen will appear. The values filled in are the hostname of the machine
containing the region with the TCPIPSERVICE defined. The PORT is port defined in the TCPIPSERVICE definition.
16

(TCPIP) Click Next and then Click Finish on the next dialog. The configuration main screen will appear. Server
NRACICS3 will appear in the list of Client Daemons as shown

(TCPIP) Check the Use Upper Case Security checkbox

Save the configuration by using File->Save from the menu bar. Choose ctg.ini if prompted.
17
Setting up the Gateway Deamon
In the Configuration Tool, you need to setup the Gateway daemon. This daemon listens for requests from the debugger
and then routes them to the appropriate client daemon based on the server name.
Use the following Steps:

In the main configuration screen, select TCP and the following dialog appears:

Check the Enable protocol handler checkbox and the other fields will be enabled as shown. Accept the defaults or
change the port if desired. I usually take the defaults.
18

Click file->Save. Again…save it to ctg.ini if prompted.

Remember the port name as it is needed for the configuration of the EGL Debugger.

Close the Configuration Tool
19
Testing your connection to the CICS Server:
To test your configuration and connectivity to your HOST CICS region, do the following:

Open a COMMAND prompt (DOS Prompt):

Type the following command and hit enter
cicscli –s=servername
where servername is one of the servers you defined in the configuration tool (e.g. cicscli –s=CIT2CLK)

You should receive the following messages. (my server name is NRACICS3)

Now type the following command and hit enter:
cicscli -l
(the letter L)

The following status output should appear and the started server should show as available.

If not, available, then the settings should be modified in the configuration tool to match the needed values or ensure
the host system is ready to receive the request.

Stop the client by typing in the command. The client should be stopped.
cicscli –x
20
Starting the CICS Transaction Gateway to use with the EGL Debugger
To invoke a call from the EGL Debugger, the CICS Transaction Gateway must be started. For now, this will be done
manually in case problems arise. Later, the CTG may be started as a Windows Service.

To start CTG, choose Start->All Programs->IBM CICS Transaction Gateway->CICS Transaction Gateway. The
following command window should appear and the initialization should be complete

Minimize the window (do not close it).
21
Setup the EGL Debugger for calls to CICS:
To have the EGL debugger use the CTG setup we just created, you need to do two basic steps:
1. Setup the EGL Debug Preferences to
a. Add the CTG code to the CLASSPATH so that the debugger can use the needed product files
b. Specify the USERID and PASSWORD for the host connection
2. Specify to the debugger how to call the Gateway Daemon that has been started.
To get started, bring up WebSphere Developer for zSeries or Rational Application Developer with the workspace you want
to use:
See the following pages for information on how to setup the two items.
22
To setup the EGL Debug Preferences, do the following:

Open your EGL Debug preferences (Window->Preferences->EGL->Debug). After the following changes, the
preferences dialog should look like the screen shot below :
o
Add the ctgclient.jar to the CLASSPATH by choosing the Add Jars button and browsing to the CTG install
location and its “classes” folder.
Select the ctgclient.jar once you get to this folder.
This gives you access to the CTG code needed by the debugger to reach the gateway daemon that was created.
o
Type your z/OS userid and password in the Remote User and Remote Password fields. Make sure they are
entered in upper case.
23
To specify to the debugger how to call the CTG Gateway Definition, use the following steps:
At a high level, when the debugger encounters a “call” statement in the EGL code, it needs to determine the location of
this program in order to invoke it. The program named in the call statement can be either an EGL or non-EGL program.
EGL provides something called a linkage Options part. The linkage Options part contains entries whose key is a program
name (or generic name using wildcards). If it finds a key match to the called program name, then the debugger will call
this program according to the specification in the entry. If it does not find a match, then it assumes the program is in the
local workspace, looks for, and then uses this EGL source to debug it. When the called program is found in the linkage
options part and it is a remote program, then it is called and executed, but it is not debugged.
When you need to call a program running on CICS, you need to specify an entry for the program to be called so that the
debugger knows to make the remote call to the CICS on z/OS system. This entry will specify the parameters to cause the
debugger to use our CTG setup defined in the previous screens.
The steps are for calling a program (assuming we are calling a program named SQSERV (e.g. call sqserv sqws; )) are:
This also assumes there is an existing build descriptor file containing a build descriptor to debug the program.

Define a linkage Options part to specify the linkage (call) information for the program (Unless you already have a
linkage options part…then just skip to the step that specifies the values for the linkage options part).
o
o
Open the eglbld file that contains the build descriptor part used for debugging
In the outline view for the eglbld file, select the eglbld file name and in the context menu, choose Add part:
o
The following dialog will appear…choose Linkage Options and click Next
24
o
The following dialog appears…
Supply a name for the part (in this case debuglinkage) and click Finish.
25
o
The linkage options editor will appear:
26
o
Click the Add button at the bottom-left of the eglbld editor. This will request a name to be entered. This should
match the name of the program named in the Call Statement (SQSERV in our case).
Note: You could also enter something like SQ* and any program starting with the letters SQ would use this entry.
Since we are calling a program on CICS, change the Type to remotecall. See the result below:
27
o
The properties for the remoteCall should be set to use the CTG gateway we defined and also CICS protocols.
See the screen shot below:
Note the following settings:
conversionTable = CSOE037 - This specifies the name of the conversion table to convert from Unicode on
on Windows and EBCDIC on z/OS
ctgLocation = 127.0.0.1 - This is the tcpip address of the machine, so the call will be directed to the local CTG
gateway that we defined
ctgPort
= 2006
- This is the port we defined in the CTG TCP Gateway Daemon
location
= NRACICS3 - This is the server definition we created as a Client Daemon that is associated with
the CICS region we want to call.
luwcontrol = SERVER - This tells the system to end the unit of work after each call and commit/rollback
changes when returning from the call.
parmform = COMMDATA - This specifies whether the called program is expecting data as values or by
reference. COMMDATA is by value and COMMPTR is by reference
remoteComType = CICSECI - This tells the debugger that the call is to a CICS region and to use CTG
remotePgmType = EXTERNALLYDEFINED - This tells the debugger that the called program is a non-EGL
generated program
serverid
= APMI
- This is used to define an alternate transaction if calling generated EGL COBOL
as the transaction must have a TWASIZE of 1024 or greater. Most installations do
not want to change the CICS default transaction of CPMI
o
Save the eglbld file using CNTL-S
28
o
Edit the build descriptor part that you are using to specify the parameters for debug. In this case, we are using
the build descriptor part named “debugBuildOptions”.
You need to specify a value for the “linkage” build descriptor option so that the linkage part we create above is
looked at. The screen shot has the “Show only specified options checked, so if linkage was not previously
specified, it would not show up in the list. To see the linkage value, just uncheck this to show all values.
Set the linkage value to the linkage options part we created as shown below.
o
Save the eglbld file by using Cntl-S.
!!!! Now you can start your EGL program in the debugger and when the listed programs
(in the linkage options part) are called, the debugger will invoke a call to the host
system.
29
Appendix A: Setting up the CTG Gateway and Client to run as a Windows Service:
In order to avoid having to remember to start the CTG Gateway each time you are getting ready to run a debug session,
you can have the CTG gateway started automatically as a Windows Service when the machine is started.
The install process we chose registered the CTG gateway as a service, but it did not set it to start automatically.
The steps below describe how to change the service to start automatically:
NOTES:
1. You will see both an IBM CICS Transaction Gateway Service and a IBM CICS Universal Client Service. Both
have to be started to operate properly.
2. You should run the CICS Transaction Gateway service as either System (Adminstrator) or as a user with the “log
on as a service” right in a secured environment.
Steps:

Shut down the CTG Gateway if it is running (type in Q in the command window).

Go to Start->Control Panel->Administrative Tools->Services

In the Services dialog, scroll down to the IBM CICS Transactions Gateway service in the list. See the following
screen:
30

Double click on the IBM CICS Transaction Gateway to edit is properties. Change the “Startup Type” to Automatic
and click Apply. See the following dialog with the properties changed:

Click Start to start the service manually (to test).

Click OK once started

Repeat for the IBM CICS Universal Client by setting its property to start automatically.
31

After changing the properties and starting the services, you should have the following dialog:

Test the call through the debugger.

Reboot the machine to test that the services are started automatically and still support the call to the remote system.
32