Explorer plug-in
This chapter provides an overview of installing IBM CICS Transaction Gateway plug-in for CICS Explorer into IBM Explorer for z/OS, and using it to configure, start, and stop a z/OS Gateway daemon. It also describes the CICS Transaction Gateway perspective, explaining how to view status and activity information for Gateway daemons on all platforms.
This chapter explains how to configure a z/OS Gateway daemon using IBM Explorer for z/OS, use CICS TG plug-in for CICS Explorer to connect to Gateway daemons, and navigate the CICS Transaction Gateway perspective.
This chapter contains the following topics:
14.1 Introduction
IBM Explorer for z/OS (z/OS Explorer) and IBM CICS Explorer both provide a common, intuitive, Eclipse-based rich client platform for architects, developers, programmers, and administrators. These products contain powerful task-oriented views, context-sensitive resource editors, and wizards to provide integrated access to a broad range of CICS and z/OS data and control capabilities. Both products are extendable through the IBM repository of compatible products, including IBM CICS Transaction Gateway plug-in for CICS Explorer, to fulfill each user’s roles and responsibilities.
z/OS Explorer provides a common connection management and single sign-on component to simplify access to z/OS-based subsystems, and an intuitive and secure way to view, edit, and manage z/OS data sets and z/OS file system (zFS) files, submit JCL, and view JES output and job logs.
CICS Explorer integrates the visibility and control of the CICS run time and its resource definitions within a single, consistent user interface. A wide range of IBM CICS and Problem Determination tools can be installed into CICS Explorer from the IBM web-based repository. This helps both novice and experienced CICS users get more from CICS, and accelerates the transfer of knowledge, skills, and preferred practices to the next generation.
You can use either of the following common approaches to obtain the capabilities of z/OS Explorer, CICS Explorer, and CICS TG plug-in for CICS Explorer:
•Install z/OS Explorer with CICS Explorer software development kit (SDK) plug-in and CICS TG plug-in for CICS Explorer.
•Install CICS Explorer, which embeds z/OS Explorer, and then install CICS TG plug-in for CICS Explorer.
 
Note: z/OS Explorer is also embedded within other IBM products, including IBM Rational Developer for System z. For more information about the installation options and capabilities of these products, see these websites:
CICS TG plug-in for CICS Explorer
CICS TG plug-in for CICS Explorer can be used in either z/OS Explorer or CICS Explorer. It allows users to view status and activity for Gateway daemons on both Multiplatforms and z/OS by using the statistics API. This includes information for the connections to the CICS servers from each Gateway daemon.
The examples in this chapter use z/OS Explorer, but the same functionality is available in CICS Explorer.
14.2 Installing CICS TG plug-in for CICS Explorer
This section describes how to obtain and install z/OS Explorer with the CICS Explorer SDK plug-in and the IBM CICS Transaction Gateway plug-in for CICS Explorer.
z/OS Explorer can be installed by using either IBM Installation Manager (IM), which is the suggested method, or by using the Eclipse P2 software update method. IM installs the Explorer product code and plug-ins from a network repository.
We selected the following Explorer components:
•z/OS Explorer Version 2.1.0.0
•CICS Explorer SDK Version 5.1.1.0
•IBM CICS Transaction Gateway plug-in for CICS Explorer 2.0.1.0
To install z/OS Explorer with the CICS Explorer and CICS Transaction Gateway plug-ins using IM, perform the following steps:
1. Download z/OS Explorer from the IBM download site:
2. Follow the installation instructions for “Scenario 1 - Install z/OS Explorer and Installation Manager” from the download site, noting the following points:
a. From the Install Packages “Select packages to install” dialog box, select the following components:
 • z/OS Explorer
 • CICS Explorer SDK
 • IBM CICS Transaction Gateway plug-in for CICS Explorer
b. Click Cancel when prompted for authentication with an IBM ID and jazz.net ID, because this authentication is not required for the selected packages. See the z/OS Explorer installation instructions for more details about these authentication prompts.
c. From the Install Packages “Review the summary information” dialog box, confirm that the chosen packages and any subcomponents are selected.
d. Wait for the installation to complete and ensure that it completes successfully.
3. Launch z/OS Explorer:
The Welcome page opens and contains a First Steps section that explains how to define connections to systems in z/OS Explorer. It also contains tutorials for the IBM CICS Transaction Gateway plug-in and CICS Explorer.
14.3 Creating and administering z/OS Gateway daemons
This section describes how to use z/OS Explorer to create, start, and stop a z/OS Gateway daemon. It includes information about creating the z/OS partitioned data set (PDS) members and UNIX System Services files, and submitting z/OS jobs.
Table 14-1 summarizes the values that are used to configure the new Gateway daemon.
Table 14-1 Values used to configure new Gateway daemon
Gateway daemon
Attribute
Value
z/OS Test Gateway daemon
Jobname
CTGTJOB
z/OS Test Gateway daemon
JCL
‘CTGUSER.CTGITSO(
CTGTJOB)’
z/OS Test Gateway daemon
Environment variables
‘CTGUSER.CTGITSO(
CTGTENV)’
z/OS Test Gateway daemon
Configuration file
/u/cicstguser/ctg/ctg.ini
z/OS Test Gateway daemon
Hostname
lp01.redbooks.ibm.com
z/OS Test Gateway daemon
Statistics API handler port
2989
z/OS Test Gateway daemon
tcp protocol handler port
2009
z/OS Test Gateway daemon
SECTION IPICSERVER
CICSTOR1
z/OS Test Gateway daemon
APPLID/APPLIDQUALIFIER
CTGAPP/CTGAPPQ
CICS Transaction Server for z/OS (CICS TS)
IPIC TCPIPSERVICE port
9011
CICS TS
IPIC TCPIPSERVICE hostname
lp01.redbooks.ibm.com
z/OS FTP
hostname and port
lp99.redbooks.ibm.com
21
z/OSMF (z/OS Management Facility)
hostname and port
lp99.redbooks.ibm.com
32208
z/OS credentials
User ID/password
CTGUSER/password
14.3.1 Creating a z/OS Gateway daemon using z/OS Explorer
This section describes how to create the CICS TG configuration and environment files and JCL to start and stop a z/OS Gateway daemon using z/OS Explorer. For detailed information about configuring a z/OS Gateway daemon, see 10.1, “Configure the Gateway daemon” on page 172.
The CICS TG for z/OS configuration consists of two parts:
•A set of environment variables. The environment variables are stored as a PDS member. A sample environment variables PDS member is in CTG.V9R0M0.SCTGSAMP(CTGENV).
•A text-based configuration file. The configuration file can be stored as either a PDS member or as a UNIX System Services file. Sample configuration files are in PDS member CTG.V9R0M0.SCTGSAMP(CTGCONF) and /usr/lpp/cicstg/ctg900/samples/configuration/ctgsamp.ini.
 
Note: The ability to store the configuration file in a PDS was introduced in CICS TG for z/OS V8.1.
For this example, the configuration file will be created as a UNIX System Services file to demonstrate how the z/OS Explorer can work with UNIX System Services files and directories.
IBM for z/OS Explorer consists of various perspectives. A perspective defines the initial set and layout of views in the Workbench window. Each perspective provides a set of functionality aimed at accomplishing a specific type of task or works with specific types of resources. The available perspectives depend on which plug-ins have been installed. For this example, it includes the z/OS (the default), CICS Transaction Gateway, and CICS SM perspectives.
Each perspective consists of multiple views. The z/OS perspective contains the following views:
•Data sets: Lists all the data sets that you are authorized to view and that match the data set name qualifier specified. You can open a data set to view the members.
•z/OS UNIX files: Shows the zFS file system structure and contents. The files are shown in a tree structure and you can expand the tree to show individual files.
•Editor: A text editor is used to view and edit content of PDS members and UNIX System Services files.
•Jobs: Lists the completed and running jobs that you are authorized to view and that match the job name prefix and owner ID specified.
•z/OS job: Shows all the output data sets for a specified job.
•Properties: Displays all the properties, or attributes, of the selected resource.
•Console: History of the actions performed, such as submitting a job, or changing and saving a file.
Figure 14-1 shows the z/OS perspective of IBM for z/OS Explorer.
Figure 14-1 z/OS perspective of z/OS Explorer
z/OS Explorer establishes connections to z/OS using FTP and connections to the z/OS Management Facility (z/OSMF). z/OSMF is a management product for z/OS that provides support for a modern, web browser-based console for z/OS. It is intended to enable IT personnel, such as system programmers, administrators, and others, to more easily manage a mainframe by simplifying the configuration and management of a z/OS system. For more information about z/OSMF, see the IBM z/OS Management Facility:
An FTP connection is required to use the function in the z/OS perspective. A z/OSMF connection provides additional functionality: the ability to view the output of active jobs while they are running and delete or cancel active jobs. When you define a z/OSMF connection, you also define an FTP connection. z/OS Explorer then chooses the connection that is most suitable for the task that you are performing.
Use the following steps to create the configuration resources for the Gateway daemon:
1. Create a connection to z/OSMF:
a. Select Windows → Manage Connections to open the Host Connections view as shown in Figure 14-2 on page 327.
b. Define credentials to access z/OS. In the Credentials pane, click Add and complete the New credentials dialog box:
i. Set Credentials name to ITSO zOS credentials.
ii. Set User ID to CTGUSER.
iii. Set Password or Passphrase to password.
iv. Optional: Select Save password.
v. Click OK.
c. Define an FTP connection to z/OS. In the Connections pane, click Add → z/OS FTP and complete the Add z/OS FTP Connection dialog box:
i. Set Name to ITSO Sysplex FTP.
ii. Set Host name to lp99.redbooks.ibm.com.
iii. Set Port to 21.
iv. Click Save and Close.
d. Define a Secure Sockets Layer (SSL) connection to the z/OSMF. In the Connections pane, click Add → z/OSMF FTP and complete the Add z/OSMF Connection dialog box:
i. Set Name to ITSO Sysplex zOSMF.
ii. Set Host name to lp99.redbooks.ibm.com.
iii. Set Port to 32208.
iv. Select Secure connection.
v. Set FTP connection to ITSO Sysplex FTP.
vi. Click Save and Connect.
vii. The first time that you connect, a Sign-on prompt is displayed. Select Use existing Credentials and set it to ITSO zOS credentials. Click OK. Confirm the credential details and click OK.
Figure 14-2 Host Connections view
2. Open the z/OS perspective:
This is the default perspective, but if it is not currently open, open it by selecting Window → Open Perspective → Other → z/OS (default).
3. Create a configuration file in UNIX System Services from the z/OS UNIX Files view:
 
Note: UNIX System Services paths and file names are case-sensitive.
a. Create a new UNIX System Services directory and configuration file, for example, /u/cicstguser/ctg/ctg.ini:
i. Enter /u/cicstguser in the Path field (in this example, this directory already exists).
ii. Right-click in the z/OS UNIX Files view and select New Directory.
iii. In the New z/OS directory dialog box, enter ctg as the New directory name and click Finish.
iv. In the z/OS UNIX Files view, open the new directory by double-clicking ctg.
v. Right-click in the z/OS UNIX Files view and select New File.
vi. In the New z/OS file dialog box, enter ctg.ini as the New file name and click Finish.
vii. Double-click ctg.ini to open it in the editor. (The file is initially empty; leave the file open.)
b. Copy the contents of the CICS TG sample configuration file /usr/lpp/cicstg/ctg900/ctg/samples/configuration/ctgsamp.ini into the new configuration file, for example, /u/cicstguser/ctg/ctg.ini:
i. Enter CICS TG /usr/lpp/cicstg/ctg900/samples/configuration in the Path field.
ii. Double-click ctgsamp.ini to open it in the editor. (Leave the file open.)
iii. Press Ctrl+A to select all the contents of ctgsamp.ini. Press Ctrl+C to copy and then press Ctrl+P to paste the contents into ctg.ini. Press Ctrl+S to save the new ctg.ini file.
iv. Close the ctgsamp.ini file.
 
Note: As an alternative to using the keyboard shortcuts, use the File and Edit menus from the z/OS Explorer toolbar.
c. Customize the configuration file to enable the tcp protocol and statistics API handlers and define an IPICSERVER definition to a CICS TS region. Edit the following values in the configuration file /u/cicstguser/ctg/ctg.ini in the editor:
i. In the PRODUCT section, uncomment the SECTION and ENDSECTION statements.
ii. In the PRODUCT section: uncomment and set APPLID to CTGAPP and set APPLIDQUALIFIER to CTGAPPQ.
iii. In the GATEWAY section, uncomment the SECTION and ENDSECTION statements.
iv. In the GATEWAY section, uncomment the Protocol handler for statistics API requests definitions and change the port to a unique value, for example, 2989.
v. In the GATEWAY section, uncomment the Protocol handler for TCP/IP requests definitions and change the port to a unique value, for example, 2009.
vi. In the IPICSERVER section, uncomment the SECTION and ENDSECTION statements.
vii. In the IPICSERVER section, change the server name to CICSTOR1.
viii. In the IPICSERVER section, uncomment and set the Hostname to lp01.redbooks.ibm.com and set the Port to 9011.
ix. Save the file by pressing Ctrl+S.
x. Check the attributes of the configuration file by right-clicking the file name, for example, ctg.ini, and selecting Properties. The user ID under which the Gateway daemon runs requires at least read access to the file.
Example 14-1 shows the properties specified in the ctg.ini file. (The other properties were left to use the default values.) For information about other configuration properties, see 10.1.3, “Configuration file” on page 174.
Example 14-1 The ctg.ini file properties
SECTION PRODUCT
Applid = CTGAPP # The APPLID of the Gateway daemon
ApplidQualifier = CTGAPPQ # The APPLID qualifier of the Gateway daemon
ENDSECTION
 
SECTION GATEWAY
# Protocol handler for statistics API requests
[email protected] = com.ibm.ctg.server.RestrictedTCPHandler
connecttimeout=2000;
maxconn=5;
port=2989;
 
# Protocol handler for TCP/IP requests
[email protected] = com.ibm.ctg.server.TCPHandler
connecttimeout=2000;
idletimeout=600000;
pingfrequency=60000;
port=2009;
solinger=10;
ENDSECTION
 
SECTION IPICSERVER = CICSTOR1 # Arbitrary name for the server
Hostname = lp01.redbooks.ibm.com # The server's TCP/IP name or IPv4 or IPv6 address
Port = 9011 # The listening TCPIPSERVICE port in CICS
ENDSECTION
4. On the Data Sets view, create an environment variables file as a PDS member in a new PDS:
a. To create the PDS that will contain the environment variables file and JCL to start and stop the z/OS Gateway daemon, follow these steps:
i. Right-click in the Data Sets view, and select New Source or JCL Data Set, which opens the New Data Set dialog box.
ii. Set Data Set Name to CTGUSER.CTGITSO.
iii. Accept the default values for other properties, including the Type of Library, Record Format = Fixed Blocked, and Record Length = 80.
iv. Click Finish.
b. To create a new member in the PDS, right-click the PDS name, for example, CTGUSER.CTGITSO, in the Data Sets view, and select New Data Set Member. This opens the New Data Set Member dialog box. Enter the following values:
i. Set Partition Data Set Name to CTGUSER.CTGITSO.
ii. Set Member Name to CTGTENV.
iii. Select Open Editor.
iv. Click Finish.
The empty CTGTENV is opened in the editor. (Leave the file open.)
c. Copy the contents of the sample environment variable PDS member from the CICS TG installation PDS CTG.V9R0M0.SCTGSAMP(CTGENV) to the new PDS CTGUSER.CTGITSO:
i. Enter CTG.V9R0M0.SCTGSAMP in the Qualifier field.
ii. Double-click CTGENV to open it in the editor.
iii. Press Ctrl+A to select all contents. Press Ctrl+C to copy, and then press Ctrl+P to paste the contents into CTGUSER.CTGITSO(CTGTENV). Press Ctrl+S to save the new CTGTENV file.
d. Customize the environment variable PDS member CTGTENV in the editor:
i. Set CICSCLI=/u/cicstguser/ctg/ctg.ini (location of the configuration file).
ii. Set PATH=/bin:/usr/lpp/java/J7.0/bin.
iii. Comment STEPLIB, DFHJVSYSTEM_00, and CTG_PIPE_REUSE. These are not required because this example does not use external CICS interface (EXCI) connections.
iv. Uncomment statement CTG_EXCI_INIT=NO, because this example does not use EXCI connections. This allows our z/OS Gateway daemon IPIC connections to use more than 250 connections.
v. Accept the default values for the other parameters. For information about other environment variables, see 10.1.4, “Environment variables” on page 176.
vi. Save the file by pressing Ctrl+S.
Example 14-2 on page 330 shows the contents of the CTGTENV environment variable PDS member.
Example 14-2 CTGTENV file contents
CICSCLI=/u/cicstguser/ctg/ctg.ini
PATH=/bin:/usr/lpp/java/J7.0/bin
_BPX_SHAREAS=YES
CTG_EXCI_INIT=NO
AUTH_USERID_PASSWORD=NO
COLUMNS=80
14.3.2 Starting and stopping a z/OS Gateway daemon
z/OS Explorer can be used to submit z/OS jobs and view the job output. This section describes how to stop and start a z/OS Gateway daemon by submitting z/OS jobs.
Starting a z/OS Gateway daemon
A z/OS Gateway daemon address space can be started as either a job or procedure, both requiring JCL stored as a PDS member. This example starts the Gateway daemon using a job, based on the sample PDS member provided in CTG.V9R0M0.SCTGSAMP(CTGJOB).
Create JCL to start the Gateway daemon as a job in a PDS member of an existing PDS:
1. From the Data Sets view, enter CTGUSER.CTGITSO in the Qualifier field.
2. To create a new member in the PDS, right-click the PDS name, for example, CTGUSER.CTGITSO, in Data Sets view and select New Data Set Member. This opens the New Data Set Member dialog box.
3. In the New Data Set Member dialog box, enter the following values:
 – Set Partition Data Set Name to CTGUSER.CTGITSO.
 – Set Member Name to CTGTJOB.
 – Select Open Editor.
 – Click Finish.
The empty CTGTJOB is opened in the editor. (Leave the file open.)
4. Copy the contents of the sample JCL to start the Gateway daemon PDS member from the CICS TG installation PDS CTG.V9R0M0.SCTGSAMP(CTGJOB) to the new PDS CTGUSER.CTGITSO:
a. Enter CTG.V9R0M0.SCTGSAMP in the Qualifier field.
b. Double-click CTGJOB to open it in the editor.
c. Press Ctrl+A to select all the contents. Press Ctrl+C to copy and press Ctrl+P to paste the contents into CTGUSER.CTGITSO(CTGTJOB). Press Ctrl+S to save the new CTGTJOB file.
5. Customize the environment variable PDS member CTGTJOB in the editor:
a. Change the job name to CTGTJOB.
b. Add a JOBPARM SYSAFF statement to indicate the LPAR on which the address space will run, for example, /*JOBPARM SYSAFF=LP01.
c. Change <Install path> to the fully qualified path of the CICS TG UNIX System Services installation directory, for example, /usr/lpp/cicstg/ctg900.
d. Change <Install hlq> to the high-level qualifier (HLQ) of the CICS TG installation, for example, CTG.V9R0M0.
e. Change <STDENV DSN> to the environment variable PDS member, for example, CTGUSER.CTGITSO(CTGTENV).
f. Press Ctrl+S to save your changes. You might receive a prompt informing you that the file changed in the host and asking whether you want to overwrite the file. Click Save.
Example 14-3 shows the contents of the JCL to start the Gateway daemon. Ensure that the values on the SET CTGHOME, CTGHLQ, CTGUSR, and LEOPTS statements are enclosed in single quotation marks.
Example 14-3 JCL to start Gateway daemon
//CTGTJOB JOB (0),MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID,REGION=500M
/*JOBPARM SYSAFF=LP01
// SET CTGHOME='/usr/lpp/cicstg/ctg900'
// SET CTGHLQ='CTG.V9R0M0'
// SET CTGUSR='CTGUSER.CTGITSO(CTGTENV)'
// SET LEOPTS='/'
//CTG EXEC PGM=CTGBATCH,
// PARM='&LEOPTS.&CTGHOME./bin/ctgstart -noinput '
//STEPLIB DD DSN=&CTGHLQ..SCTGLOAD,DISP=SHR
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//STDENV DD DSN=&CTGUSR.,DISP=SHR
//
Use these steps to start the Gateway daemon from the z/OS perspective:
1. Submit the ‘CTGUSER.CTGITSO(CTGTJOB)’ job:
a. From the Data Sets view, navigate to ‘CTGUSER.CTGITSO’.
b. Right-click the PDS member CTGTJOB and select Submit z/OS Job.
c. From the Perform Operation dialog box, confirm that the correct job was selected and click OK.
2. Check that the Gateway daemon job is running:
a. From the Jobs view, set the filter Job name to CTGTJOB and the filter User to *. Then, click the Refresh icon.
b. Expand CTGTJOB to see the job log. Either double-click each file to open it in the editor or view the log steams in the z/OS Job view.
c. The JESMSGLG contains the following message: CTG6512I CTGAPP CICS Transaction Gateway initialization complete.
CTGAPP is the APPLID value specified in the PRODUCT section of Gateway daemon configuration file.
Stopping a z/OS Gateway daemon
A z/OS Gateway daemon can be stopped by issuing a modify command to the address space, for example, /F jobname,APPL=SHUT, for a normal shutdown. z/OS Explorer does not yet provide the function to issue a modify command directly, but it can submit a job to issue the command.
Use the following steps to create a job to issue the z/OS Gateway daemon shutdown command:
1. From the Data Sets view, enter CTGUSER.CTGITSO in the Qualifier field.
2. Right-click the PDS name, for example, CTGUSER.CTGITSO, in the Data Sets view and select New Data Set Member.
3. In the New Data Set Member dialog box, enter the following values:
 – Set Partition Data Set Name to CTGUSER.CTGITSO.
 – Set Member Name to CTGTSTOP.
 – Select Open Editor.
 – Click Finish.
The empty CTGTSTOP is opened in the editor.
4. In the editor view, paste the text that is shown in Example 14-4.
Example 14-4 JCL to stop a z/OS Gateway daemon
//CTGTSTOP JOB (0),CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID,REGION=500M
/*JOBPARM SYSAFF=LP01
//STOP EXEC PGM=IEFBR14
// F CTGTJOB,APPL=SHUT
//
This example will run on LPAR LP01 and attempt to shut down the z/OS Gateway daemon address space with the jobname CTGTJOB.
Use the following steps to submit a job to issue the z/OS Gateway daemon shutdown command from the z/OS perspective:
1. Submit the ‘CTGUSER.CTGITSO(CTGTSTOP)’ job:
a. From the Data Sets view, navigate to ‘CTGUSER.CTGITSO’.
b. Right-click PDS member CTGTSTOP and select Submit z/OS Job.
c. From the Perform Operation dialog box, confirm that the correct job was selected and click OK.
2. Check that the job ran successfully and that the Gateway daemon shut down:
a. From the Jobs view, set the filter Job name to CTGTSTOP and the filter User to *. Then, click the Refresh icon.
b. Expand CTGTSTOP to see the job log. Either double-click each file to open it in the editor or view the log steams in the z/OS Job view. The JESYSMSG log contains the following message: CTGTSTOP STOP - STEP WAS EXECUTED - COND CODE 0000.
c. From the “Jobs” view, set the filter Job name to CTGTJOB and the filter User to *. Then, click the Refresh icon to see the Gateway daemon address space job.
d. Expand CTGTJOB to see the job log. Either double-click each file to open it in the editor or view the log steams in the z/OS Job view. The JESMSGLG contains the following message: CTG6511I CTGAPP GATEWAY DAEMON HAS SHUT DOWN where CTGAPP is the APPLID value specified in the PRODUCT section of the Gateway daemon configuration file.
14.4 Preparing a Gateway daemon to use Explorer
The CICS TG statistics API allows remote users to obtain live statistical data from a Gateway daemon at run time. The CICS TG plug-in for CICS Explorer uses this facility to retrieve information about the Gateway daemon status.
The CICS TG plug-in for CICS Explorer connects to an active Gateway daemon using the Gateway daemon statistics API protocol handler port. To view the details of a Gateway daemon using the plug-in, ensure that the statistics API protocol handler port has been enabled. It is not enabled, by default.
Configure the statistics API handler
To define a statistics API handler definition in the configuration file, use the following steps:
1. Edit the Gateway daemon configuration file.
2. In the SECTION GATEWAY, add the following entry. (The sample configuration file ctgsamp.ini contains a commented out version of this entry.)
Example 14-5 Statistics API requests protocol handler definition
# Protocol handler for statistics API requests
[email protected] = com.ibm.ctg.server.RestrictedTCPHandler
connecttimeout=2000;
maxconn=5;
port=2989;
This example uses the default port value 2989. If required, modify this value to ensure that it is unique on the target system.
3. Restart the Gateway daemon.
14.5 Connecting to a Gateway daemon
This section describes how to configure a connection to a Gateway daemon. These instructions demonstrate how to create a new connection using the Host Connections view dialog box:
Use the following steps to add a connection for a Gateway daemon to z/OS Explorer:
1. Select Windows → Manage Connections to open the Host Connections view.
2. In the Connections pane, click Add → CICS Transaction Gateway as shown in Figure 14-3 on page 334.
Figure 14-3 Host Connections dialog box to add CICS Transaction Gateway
3. Add a connection to the z/OS Gateway daemon configured in 14.3.1, “Creating a z/OS Gateway daemon using z/OS Explorer” on page 324. From the Add CICS Transaction Gateway Connection dialog box that is shown in Figure 14-4, enter the following values:
 – Set Name to zOS Test Gateway.
 – Set Host name to lp01.redbooks.ibm.com.
 – Set Port number to 2989 (statistics API handler port).
 – Click Save and Connect.
Figure 14-4 Add CICS Transaction Gateway Connection
 – The connection zOS Test Gateway appears in the Connections pane under the Transaction Gateway heading as shown in Figure 14-5 on page 335.
Figure 14-5 Host Connections view displaying a Gateway daemon connection
As an alternative to manually defining host connections on each instance of z/OS Explorer or CICS Explorer, definitions can be shared. If your systems administrator has already created a shared host connections definitions file, this file can be loaded or imported. For more information, see “Export and import of Gateway daemon, CICS TS, and z/OS connections” on page 336.
14.5.1 Backing up and restoring connection definitions
This section describes the options provided by the CICS TG plug-in for CICS Explorer and z/OS Explorer for importing and exporting connection definitions.
Export and import of connection groups and connection links
This information relates to the custom connection group and associated connection link definitions created in the custom option of the CICS TG Explorer view.
If you uninstall the CICS TG plug-in for CICS Explorer, all custom connection group and associated connection link definitions are deleted. Two options are available to avoid losing these definitions:
•Export all custom group definitions before uninstalling the CICS TG plug-in for CICS Explorer and import the definitions after installing the new version of the plug-in.
•Use the update feature when installing a new version of the CICS TG plug-in for CICS Explorer to preserve custom group definitions.
Use the following steps from the CICS TG Explorer view to export a connections group and the associated connection link definition:
1. Click the View Menu (triangle) icon on the CICS TG Explorer view toolbar and select Custom.
2. Select the connection groups to export, for example, zOSGatewayGroup. Right-click your selection and click Export as shown in Figure 14-6 on page 336.
3. Use the Save As dialog box to specify the target file name (with a file extension of .ctg) and a path, for example, C: empExplorer_GatewayConns.ctg.
4. Click OK.
Figure 14-6 Export CICS TG custom connection group
The connection groups and the associated connection links that are previously exported can be imported to the root level or nested inside an existing connection group. Use the following steps from the CICS TG Explorer view to import the gateway connections in a connections group:
1. Click the View Menu (triangle) icon on the CICS TG Explorer view toolbar and select Custom.
2. Right-click inside the CICS TG Explorer at the root of where the imported connection groups are to be created and click Import as shown in Figure 14-7.
3. Use the Open dialog box to select the previously exported custom group file (file extension .ctg) to import, for example, C: empExplorer_GatewayConns.ctg.
4. Click OK.
Figure 14-7 Import CICS TG custom connection group
Export and import of Gateway daemon, CICS TS, and z/OS connections
This information applies to all connection definitions created in the Host Connections view. It includes CICS TG, CICS System Management, and z/OS definitions.
As an alternative to each user manually defining their own connection definitions, a set of shared definitions can be created by a system administrator using z/OS Explorer and exported to a central location. The exported file must have a file extension of .pref. Any user with access to the file location can load or import the definitions in their copy of z/OS Explorer:
•When you load connections, a link is created to an external connection definition file, and the connections are shown in the Host Connections view. The definitions can be viewed but not changed. Any changes to the shared connections file are reflected the next time that z/OS Explorer starts. This has the advantage of keeping definitions synchronized across multiple workspaces, but it requires a network connection to the location of the shared definitions file. If the connection file is deleted or moved, the connections are lost from z/OS Explorer.
•When you import connections, the details are copied into your local workspace and must be manually updated if any details change. Importing a connection definition that already exists in z/OS Explorer and is associated with a credential updates only the existing connection definition details. It does not change the credential.
This approach can also be used to back up and restore the host connections in a local workspace, which have previously been created manually.
 
Note: This approach exports all host connections currently defined in the Host Connections view and imports all host connections defined in the .pref file. There is not an option to select individual connections.
Use the following steps from the Host Connections view to export connection definitions:
1. Select Windows → Manage Connections to open the Host Connections view.
2. Click the Export Connections to File icon (blue arrow) on the Host Connections view toolbar, as shown in Figure 14-8 on page 338.
3. Use the Export Connections to File dialog box to specify the target file name (file extension of .pref) and path, for example, C: empExplorer_connections.pref.
4. Click OK.
Figure 14-8 Export host connections to a file
Use the following steps from the Host Connections view to load or import connection definitions:
1. Select Windows → Manage Connections to open the Host Connections view.
2. Click Load Connections from file or URL icon (green arrow) on the Host Connections view toolbar, as shown in Figure 14-9 on page 339.
3. Use the Load Connections to File dialog box to select the previously exported connection definition file, for example, C: empExplorer_connections.pref, and select the Load or Import radio button.
4. Click OK.
Figure 14-9 Load or import host connections
14.6 Viewing information for a Gateway daemon
This section describes how to view Gateway daemon information by using the CICS Transaction Gateway perspective. It assumes that a Gateway daemon has already been configured with at least one connection to CICS and that the Gateway daemon is running.
Open the CICS Transaction Gateway perspective by using the following steps:
1. From the z/OS Explorer toolbar, select Windows → Open Perspective → Other.
2. From the Open Perspective dialog box, select CICS Transaction Gateway and click OK.
The CICS Transaction Gateway perspective contains the following views, which are described in more detail in the referenced sections:
•Properties view
•Console view
14.6.1 CICS TG Explorer view
The CICS TG Explorer view displays the Gateway daemons and their associated CICS server connections. The Gateway daemons that are displayed are those Gateway daemons whose connections were defined using the Managed Connections view. (See 14.3, “Creating and administering z/OS Gateway daemons” on page 323.) It can also test the connections to the Gateway daemon and from the Gateway daemon to its defined CICS servers.
 
Note: If a new Gateway daemon connection is defined and connected, but it is not displayed in this view, restart z/OS Explorer.
Sorting and organizing the view
The Gateway daemons can be displayed in various ways:
•By APPLID qualifier
•As a flattened list
•By custom connection groups
Each of these views is described in more detail:
•The Gateway daemons can be displayed as a tree view sorted by APPLID qualifier (the default option):
 – Click the View Menu (triangle) icon on the CICS TG Explorer view toolbar and select APPLID qualifier.
 – This view is useful when you use z/OS Gateway groups to see all z/OS Gateway daemons, which all share a common APPLID qualifier value, in the same group.
Figure 14-10 displays an example APPLID qualifier view. It shows five z/OS Gateway daemons in a Gateway group (APPLID qualifier CTGALP00), an AIX Gateway daemon (APPLID qualifier CTGMP), and the z/OS test Gateway daemon created earlier in this chapter (APPLID qualifier CTGAPPQ).
Figure 14-10 CICS TG Explorer APPLID qualifier view
•The Gateway daemons can be displayed as a flattened list that is sorted in alphabetic order:
 – Click the View Menu (triangle) icon on the CICS TG Explorer view toolbar and select List.
 – Figure 14-11 on page 341 displays an example List view. It shows an AIX Gateway daemon and six z/OS Gateway daemons, including the z/OS test Gateway daemon that was created earlier in this chapter.
Figure 14-11 CICS TG Explorer List view
•The Gateway daemons can be displayed by using custom connection groups of selected Gateway daemons.
The first time that you select the custom option, the CICS TG Explorer view is empty. The custom option allows custom connection groups to be created and the required Gateway daemon connections to be assigned to each group.
Use the following steps to create a connection group and assign the Gateway daemon connections to it:
a. Click the View Menu (triangle) icon on the CICS TG Explorer view toolbar and select Custom.
b. Right-click inside the CICS TG Explorer view and select New → Connection group. (Alternatively, click File → New → Connection Group from z/OS Explorer.) The New connection group dialog is displayed.
c. On the New connection group dialog shown in Figure 14-12 on page 342, follow these steps:
i. Set the Connection group to /. (The forward slash indicates the root node.)
This defines the position in the custom group hierarchy, the first connection group must start at the root node. Subsequent connection groups can be nested in a hierarchy. In this case, use Browse to select an existing connection group to use as the parent for the new group.
ii. Set the Connection group name to zOSGatewayGroup.
iii. Click Finish.
Figure 14-12 New connection group dialog
d. Right-click the connection group name, for example, zOSGatewayGroup, and select New → Connection link. (Alternatively, click File → New → Gateway connection link from z/OS Explorer.) The New connection link dialog is displayed.
e. On the New connection link dialog shown in Figure 14-13 on page 343, follow these steps:
i. Set the Connection group name to zOSGatewayGroup.
ii. From the Available connections, select the Gateway daemon connections that you want to add to the connection group from the displayed list. Multiple connections can be added to the custom group by pressing the Shift or Ctrl keys while selecting.
iii. In this example, we chose to add four of the ITSO zOS Gateway daemons.
iv. Click Finish.
Figure 14-13 New connection link dialog
Figure 14-14 displays an example custom view. It shows a single connection group with four z/OS Gateway daemons.
Figure 14-14 CICS TG Explorer custom view
f. Create another connection group called TestGatewayGroup and add the following connection links: ITSO AIX gateway, ITSO zOSGateway0, and zOS Test Gateway.
Testing the connection to the Gateway daemon
The CICS TG plug-in for CICS Explorer can be used to test the connection to a Gateway daemon. Follow these steps:
1. From your preferred CICS TG Explorer view option (APPLID qualifier, List, or Custom), right-click the Gateway daemon name, for example, zOS Test Gateway, and click Test Gateway connection, as shown in Figure 14-15 on page 344.
Figure 14-15 Test Gateway connection dialog
2. The result is displayed in the Console view, as shown in Example 14-6.
Example 14-6 Example output from test gateway connection
Attempting to open connection to Gateway daemon using host lp01.redbooks.ibm.com on port 2,009
Success: Opened connection to lp01.redbooks.ibm.com on port 2,009
Testing connections to CICS servers
The CICS TG Explorer view also displays the CICS server connection definitions for each Gateway daemon.
 
Note: For z/OS Gateway daemons, EXCI connections to CICS servers are only displayed while they are active.
Figure 14-16 on page 345 shows an expanded version of the CICS TG Explorer view sorted by the APPLID qualifier:
•The numbers in parentheses after the Gateway daemon connection name indicate the number of active CICS connections and the number of defined CICS server connections. For example, Gateway daemon connection ITSO zOSGateway1 displays (4/4), which indicates that the Gateway daemon configuration file contains four CICS server definitions, all of which are currently active. Also, zOS Test Gateway displays (0/1), which indicates that the Gateway daemon configuration file contains a single CICS server definition, which is not currently active.
•The CICS server definitions are displayed below each Gateway daemon by expanding the Gateway connection name. For example, the Gateway daemon connection ITSO zOSGateway1 has four server definitions: CICSTOR1, CICSTOR2, CICSTOR3, and CICSTOR4. The Gateway daemon connection zOS Test Gateway has one server definition, CICSTOR1.
Figure 14-16 CICS TG Explorer expanded view showing CICS connections
The CICS TG plug-in for CICS Explorer can be used to test the connection to a CICS region using the Gateway daemon in remote mode. By default, the test is configured to call CICS server program PONG with a 32-byte COMMAREA; however, this can be customized.
Note: The PONG program is available from CICS SupportPac CH50 (CTGPING).
In the following example, the default configuration was customized to use the CICS TG sample server program EC01 instead. This program requires an 18-byte COMMAREA.
Use the following steps to test an IPIC connection to CICS TS by running program EC01:
1. Configure z/OS Explorer to set the parameters to use to test the connection, for example, the CICS program to be invoked, COMMAREA length, user ID, and password required:
a. On the z/OS Explorer toolbar, select Window → Preferences.
b. Select CICS Transaction Gateway.
c. On the CICS Transaction Gateway preferences page, as shown in Figure 14-17 on page 346, follow these steps:
i. Set the Program name to EC01.
ii. Set the COMMAREA size (bytes) to 18.
iii. The User ID and Password can be left as blank, provided that the CICS server has not implemented link security.
iv. Click OK.
Figure 14-17 CICS TG preferences to customize the CICS program that is used to test the connection
2. From your preferred CICS TG Explorer view style, right-click the CICS server connection name, for example, CICSTOR1 for Gateway daemon connection zOS Test Gateway, and click Test CICS connection, as shown in Figure 14-18.
Figure 14-18 Test CICS connection dialog
3. The result is displayed in the Console view, as shown in Example 14-7.
Example 14-7 Example output from Test CICS connection action
Attempting to open connection to Gateway daemon using host lp01.redbooks.ibm.com on port 2,009
Attempting to run program EC01 on CICS server CICSTOR1
Success: Time spent in ECI call was: 156 ms
14.6.2 Gateway daemons view
The Gateway daemons view displays status and activity information for Gateway daemons. This view includes the values of properties specified in the configuration file and values obtained from the CICS TG startup, lifetime, and current statistics information. The Gateway daemons view displays information for the CICS TG connections that are currently selected in the CICS TG Explorer view. The CICS TG connection must be in the connected state.
To view the status and activity information for a Gateway daemon, follow these steps:
1. From the CICS TG Explorer view, ensure that the CICS TG connection, zOS Test Gateway, shows as connected (blue connection icon):
 – If the CICS TG connection is not currently connected (gray connection icon), right-click the connection name, for example, zOS Test Gateway, and select Refresh status.
 – If the connection fails, ensure that the Gateway daemon is running and listening on the statistics API port specified in the CICS TG connection definition.
2. From the CICS TG Explorer view, select the CICS TG connection, zOS Test Gateway. It is possible to select multiple Gateway daemon connections by pressing the Shift or Ctrl keys.
 – The Gateway daemons view now displays the status and activity information for the Gateway daemon as shown in Figure 14-19.
 
Note: In this example, the value -1 for SSLPort indicates that the SSL protocol handler was not defined for this Gateway daemon.
Figure 14-19 Gateway daemons view
The columns can be sorted by clicking the column headings, and the order can be rearranged by clicking and dragging the column headings. This view can be customized by using these options under the View Menu (triangle) icon:
•Column Layout → Gateway displays Gateway daemon property information.
•Column Layout → Requests displays information about requests made to that Gateway daemon.
•Column Layout → Resources displays information about the Gateway daemon resources.
•Customize Columns allows columns to be added or removed from the view.
•Choose filter attributes allows columns to be selected that can be used to filter requests. The default filter column displayed on the toolbar is for the Name. For Multiplatforms CICS TG connections, Name is the connection name. For z/OS CICS TG connections, Name is the Gateway daemon job or procedure name.
The Reset Columns option can be used to reset the view to the default options.
For a description of each column (property) value, see the CICS TG plug-in for CICS Explorer help. From the z/OS Explorer toolbar, select Help → Help Contents → CICS TG Plug-in Users Guide → Views → Gateway daemons views.
All of the status and activity information can also be viewed in the Properties view. This information is displayed when a single Gateway daemon is selected in the Gateway daemons view. The Properties view has two formats:
•Information is arranged in categories, for example, Client daemon, Gateway daemon, Connections, IPIC, and EXCI.
•Information is sorted in the alphabetical order of the properties.
To switch between the values, click the Show categories icon on the Properties view toolbar.
14.6.3 CICS connections view
The CICS connections view displays the status and activity information for the CICS server connections. The values are obtained from the CICS TG statistics information. The CICS connections view displays information for the CICS TG connections currently selected in the CICS TG Explorer view. The CICS TG must be connected. Multiple connections can be selected.
To view the status and activity information for the CICS server connections for a Gateway daemon, from the CICS TG Explorer view, select the CICS TG connection, for example, zOS Test Gateway. The CICS connections view now displays the status and activity information for the CICS server connections for the zOS Test Gateway.
Figure 14-20 shows the CICS server connection CICSTOR1 status for the Gateway daemon CTGTJOB.
Figure 14-20 CICS connections view
For a description of each of the column (property) values, see the CICS TG plug-in for CICS Explorer help. From the z/OS Explorer toolbar, select Help → Help Contents → CICS TG Plug-in Users Guide → Views → CICS connections views.
This concludes our brief tour of the CICS Transaction Gateway perspective that is provided with the IBM CICS Transaction Gateway plug-in for CICS Explorer. For more information about the options that are available with the views and statistics displayed, see the “CICS TG Plug-in User Guide” by clicking Help → Help Contents.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
52.14.85.76