CICS Transaction Gateway and AIX workload partitions

This article shows you how to use CICS Transaction Gateway in an AIX environment that supports workload partitions (WPARs). It includes scenarios that show you how to use WPARs to consolidate existing hardware or to extend a CICS Transaction Gateway instance.

Share:

Chris Mawer (mawerc@uk.ibm.com), Senior Tester, CICS Transaction Gateway team, IBM

Photo of Chris MawerChris Mawer is a Senior Tester in the CICS Transaction Gateway team at the IBM Software Lab in Hursley, United Kingdom. He is responsible for leading the ECI V2 and Microsoft .NET test teams. He graduated from Manchester University and joined IBM in 2001 as part of the CICS Transaction Gateway Level 3 Support team, where he built a thorough knowledge of CICS Transaction Gateway and its customers. In 2008, he moved to the CICS Transaction Gateway Test team, where he has been a key player in testing and test strategy. More recently, he has diversified into customer scenario and performance testing. You can contact Chris at mawerc@uk.ibm.com.



16 November 2011

Also available in Chinese

Introduction

WPARs were introduced in IBM® AIX® V6.1 to provide a way to partition work within an AIX Logical Partition (LPAR). WPARs allow a single instance of AIX to be divided into multiple virtual partitions, so that the system administrator can quickly deploy multiple, isolated AIX environments without the overhead of managing individual AIX images. There are two types of WPAR:

Application WPAR
A single process (and its children) run in their own partition
System WPAR
An entire AIX environment that can be either shared or detached

If a system WPAR is shared, it mounts the global environment's /usr and /opt partitions as read-only and shares them. If a system WPAR is detached, it has a clone of the global environment, and all file systems are local to the WPAR. Figure 1 shows a shared and detached system WPAR created in the same LPAR. The shared WPAR has read-only access to /usr and /opt in the global environment. The detached WPAR has no access to the global environment and maintains its own file systems:

Figure 1. Deploying system WPARs
Deploying system WPARs

This article explores the different types of WPARs and the ways in which you can use them when deploying IBM CICS® Transaction Gateway (TG) on AIX.

Application WPARs

The first and simplest kind of WPAR is the application WPAR, which is a lightweight environment suitable for executing one or more application processes. CICS TG supports application WPARs for client applications running either in remote mode, or where the IPIC protocol is used, in local mode. Figure 2 shows a Gateway daemon running in the global environment with three application WPARs, each running a different type of application connecting to that Gateway daemon:

Figure 2. Deploying application WPARs
Deploying application WPARs

Setting up the WPAR

In this example, the Gateway daemon is running in the global environment and is therefore started in the LPAR:

aix7host144 # ctgd start

The application to run in the WPAR is the Java EciB3 sample that initially runs in remote mode. Because the application WPAR creates its own environment, the CLASSPATH is not inherited from the global environment and must be passed as a command-line parameter to the application. To start the application WPAR, use the wparexec command with a hostname (in this example ctgwpar1), and a network stack with its own IP address (192.168.1.1), so that the application can communicate with the Gateway daemon:

aix7host # wparexec -h ctgwpar1 -N interface=en0 address=192.168.1.1 netmask=255.255.255.0
 /opt/IBM/cicstg/jvm16/bin/java -cp
 /opt/IBM/cicstg/classes/ctgsamples.jar:/opt/IBM/cicstg/classes/ctgclient.jar
 com.ibm.ctg.samples.eci.EciB3 tcp://aix7host 2006
Starting workload partition 'ctgwpar1'.
Mounting all workload partition file systems.
Loading workload partition.
CICS Transaction Gateway Basic ECI Sample 3

Usage: java com.ibm.ctg.samples.eci.EciB3 [Gateway URL]
                                          [Gateway Port Number]
                                          [SSL Keyring
                                           SSL Password]

To enable client tracing, run the sample with the following Java option:
        -Dgateway.T.trace=on

The address of the gateway has been set to tcp://aix7host port 2006
CICS servers defined:
         1. TS20IPIC – CICS TS IPIC server
         2. TX20 – TXSeries TCP server
         3. TS20 – CICS TS SNA server

Choose server to connect to, or Q to quit: 1

Enter text to send to the CICS program: HELP ME

Program EC03 returned 5 containers in channel "SAMPLECHANNEL":
        [CHAR] CICSDATETIME     = 31/05/2011 15:35:14
        [CHAR] INPUTDATA        = HELP ME
        [CHAR] OUTPUTMESSAGE    = Input data was: HELP ME
         [BIT] INPUTDATALENGTH  = 00000007
        [CHAR] INPUTDATACCSID   =      819
Shutting down all workload partition processes.

When the process ends, the WPAR shuts down and is deleted. To verify that the application WPAR is communicating with the correct Gateway daemon in the global environment, check the Gateway info log:

05/31/11 15:35:03:994 [0] CTG6506I Client connected: [ConnectionManager-0] -
tcp@Socket[addr=/192.168.1.1,port=52127,localport=2006]
05/31/11 15:35:14:453 [0] CTG8429I Established new IPIC connection to CICS server
TS20IPIC with: negotiated session limit=100, CICSAPPLID=IY2GTG20
CICSAPPLIDQUALIFIER=GBIBMIYA, HOSTNAME=cicsserv.ibm.com, PORT=1120,sockets=2
05/31/11 15:35:14:473 [0] CTG6507I Client disconnected: [ConnectionManager-0] -
tcp@Socket[addr=/192.168.1.1,port=52127,localport=2006], reason = Java client
application closed the connection

You can also see evidence that the IP address of the WPAR is connecting and triggering the gateway to establish an IPIC connection with CICS. You can then rerun the application in local mode, as long as you add ctgserver.jar on the CLASSPATH:

# wparexec -h ctgwpar1 -N interface=en0 address=192.168.1.1 netmask=255.255.255.0
 /opt/IBM/cicstg/jvm16/bin/java -cp /opt/IBM/cicstg/classes/ctgsamples.jar:
/opt/IBM/cicstg/classes/ctgclient.jar:/opt/IBM/cicstg/classes/ctgserver.jar 
    com.ibm.ctg.samples.eci.EciB3
Starting workload partition 'ctgwpar1'.
Mounting all workload partition file systems.
Loading workload partition.
CICS Transaction Gateway Basic ECI Sample 3

Usage: java com.ibm.ctg.samples.eci.EciB3 [Gateway URL]
                                          [Gateway Port Number]
                                          [SSL Keyring
                                           SSL Password]

To enable client tracing, run the sample with the following Java option:
        -Dgateway.T.trace=on

The address of the gateway has been set to local: port 2006

IPIC servers are not listed when running in local mode.
Enter URL of a CICS server, or Q to quit: tcp://winmvs2g:1120

Enter text to send to the CICS program: HELP ME

Program EC03 returned 5 containers in channel "SAMPLECHANNEL":
        [CHAR] CICSDATETIME     = 31/05/2011 16:02:47
        [CHAR] INPUTDATA        = HELP ME
        [CHAR] OUTPUTMESSAGE    = Input data was: HELP ME
         [BIT] INPUTDATALENGTH  = 00000007
        [CHAR] INPUTDATACCSID   =      819
Shutting down all workload partition processes.

You can also run applications that call the Remote C ECIv2, ESIv2, and Statistics API within an application WPAR.

Why use application WPARs?

Client applications in application WPARs run in their own isolated environment, complete with their own network stack, which has the following advantages:

  • Application instances are easy to identify during monitoring
  • A problem within an application does not affect the rest of the LPAR or any other WPARs running within it.

System WPARs (shared)

A shared system WPAR appears as an AIX instance, but shares the global environment's /usr and /opt file systems and mounts them in the WPAR as read-only. An example of how to use system WPARs to run CICS TG is provided below. Figure 3 shows a CICS TG installation, configured to run in the global environment with three shared system WPARs created within the global environment LPAR. The first system WPAR uses the ctg.ini configuration file in the global environment, and the other two WPARs have their own local configurations but still use the installed CICS TG executables.

Figure 3. Deploying shared system WPARs
Deploying shared system WPARs

Setting up the WPAR for shared install

The first step is to create the WPAR. In this example, you specify that:

  • The WPAR name is ctgwpar1.
  • The install is shared.
  • The hostname is ctgwpar1.
  • Network routing information is inherited from the global environment.
  • The network uses en0 with the given IP address.

To create the WPAR, issue the following command:

aix7host # mkwpar -n ctgwpar1 -l -h ctgwpar1 -r -N interface=en0 address=192.168.1.1
 netmask=255.255.255.0

The WPAR name and the hostname do not have to be identical, but testing has shown that the SNA Remote API client looks for the WPAR name, not the hostname. If the names are different, the WPAR name may not resolve to a valid IP address.

aix7host # startwpar -v ctgwpar1
Starting workload partition 'ctgwpar1'.
Mounting all workload partition file systems.
Mounting '/wpars/ctgwpar1'.
Mounting '/wpars/ctgwpar1/home'.
Mounting '/wpars/ctgwpar1/opt'.
Mounting '/wpars/ctgwpar1/proc'.
Mounting '/wpars/ctgwpar1/tmp'.
Mounting '/wpars/ctgwpar1/usr'.
Mounting '/wpars/ctgwpar1/var'.
Loading workload partition.
Exporting workload partition devices.
Exporting workload partition kernel extensions.
Starting workload partition subsystem 'cor_ctgwpar1'.
0513-059 The cor_ctgwpar1 Subsystem has been started. Subsystem PID is 11403326.
Verifying workload partition startup.
Return Status = SUCCESS.

aix7host # lswpar
Name      State  Type  Hostname  Directory        RootVG WPAR
--------------------------------------------------------------
ctgwpar1  A      S     ctgwpar1  /wpars/ctgwpar1  no

Verifying WPAR install

To verify that the WPAR has been created successfully as a shared install, check that the file systems under the created WPAR are mounted on /dev (with the exception of /opt and /usr, which are mounted as read-only in the WPAR):

aix7host # df -k
Filesystem    1024-blocks      Free %Used    Iused %Iused Mounted on
/dev/hd4          1245184    971756   22%    11826     6% /
/dev/hd2          5734400   1507368   74%    62691    16% /usr
/dev/hd9var       1048576    756404   28%     7002     4% /var
/dev/hd3          3145728   3141308    1%      133     1% /tmp
/dev/hd1          1212416   1038192   15%     2919     2% /home
/dev/hd11admin      131072    130692    1%        5     1% /admin
/proc                   -         -    -         -     -  /proc
/dev/hd10opt      2490368   1857964   26%    13218     4% /opt
/dev/livedump 262144 261776 1% 4 1%
 /var/adm/ras/livedump
/dev/fslv00 98304 67200 32% 2322 14%
 /wpars/ctgwpar1
/dev/fslv01 32768 31904 3% 5 1%
 /wpars/ctgwpar1/home
/opt 2490368 1857964 26% 13218 4%
 /wpars/ctgwpar1/opt
/proc - - - - -
  /wpars/ctgwpar1/proc
/dev/fslv02 98304 96688 2% 9 1%
 /wpars/ctgwpar1/tmp
/usr 5734400 1507368 74% 62691 16%
 /wpars/ctgwpar1/usr
/dev/fslv03 131072 110100 17% 363 2%
 /wpars/ctgwpar1/var

The shared system WPAR has its own IP address and can therefore be remotely logged into by users with rlogin and the hostname. When a user logs in, the WPAR has the look and feel of a regular AIX system. All file systems are flagged as global and no file systems outside the WPAR can be viewed.

aix7host # rlogin ctgwpar1
*******************************************************************************
*  Welcome to AIX Version 7.1!                                                *
*  Please see the README file in /usr/lpp/bos for information pertinent to    *
*  this release of the AIX Operating System.                                  *
*******************************************************************************

ctgwpa1 # df -k
Filesystem    1024-blocks      Free %Used    Iused %Iused Mounted on
Global              98304     67196   32%     2321    14% /
Global              32768     31904    3%        5     1% /home
Global            2490368   1857944   26%    13218     4% /opt
Global                  -         -    -         -     -  /proc
Global              98304     96688    2%        9     1% /tmp
Global            5734400   1507368   74%    62691    16% /usr
Global             131072    110096   17%      364     2% /var

For WPARs that are not configured with TCP/IP, you can use console login (clogin) to access and set up the WPAR, although, without a network stack, it cannot be used with CICS TG.

Installing CICS TG in a shared system WPAR

In a shared WPAR, you must install CICS TG in the global environment, because the WPAR has read-only access to /opt, where CICS TG installs. Run the product installer:

aix7host # ./installer -i console
Preparing to install...
Extracting the JRE from the installer archive...
Unpacking the JRE...
Extracting the installation resources from the installer archive...
Configuring the installer for this system's environment...

Launching installer...

Accept all defaults. CICS TG should install successfully in the global environment. To verify that the product is accessible in both the global environment and the WPAR, issue the following command:

aix7host # type cicscli
cicscli is /usr/bin/cicscli

ctgwpar1 # type cicscli
cicscli is /usr/bin/cicscli

Running CICS TG in a shared system WPAR

By default, in a shared system WPAR installation, the configuration files are shared across all the shared WPARs because the configuration files are located in the /opt/IBM/cicstg/bin directory. Sharing a configuration works well for TCP/IP connections to CICS, but for SNA and IPIC, which require unique values to identify the gateway instance, sharing is restricted and only the first gateway using the configuration that connects to CICS can establish a connection. Other connections are rejected.

When CICS TG is planned to be run as an init task using ctgd, this sharing limitation can be overcome by setting the CTGDCONF environment variable in each of the system WPARs to point to the local ctgd.conf that sets the CICSCLI environment variable to be the ctg.ini file in the WPAR, which contains unique identifiers for that instance of the CICS TG. The ctgd process checks for the presence of this environment variable before using the defaults. If ctgd is not being used, and if ctgstart or cicscli are being used, you must set the CICSCLI environment variable directly to point to the local ctg.ini file. In the example, the CICS TG is started using ctgd:

First, make copies of the two configuration files from the global environment and save them in the WPAR so that they can be modified:

aix7host # cp ctgd.conf ctg.ini /wpars/ctgwpar1/tmp

Switch to the WPAR and modify the ctgd.conf file so that the CICSCLI variable points to the local ctg.ini file:

#-----------------------------------------------------------------------
# Location of ctg.ini file. Set this to specify a location for ctg.ini,
# other than the default <install_path>/bin/ctg.ini.

#CICSCLI=<install_path>/bin/ctg.ini
CICSCLI=/tmp/ctg.ini

Next, update the ctg.ini file to change the gateway's APPLID and the SNA local LU name so that they are both unique and different from those in the global environment:

SECTION PRODUCT
    APPLID=CTGWPAR1
    APPLIDQUALIFIER=CHRSQUAL
    DEFAULTSERVER=TX20
ENDSECTION

SECTION SERVER = TS20
    SRVIDLETIMEOUT=0
    PROTOCOL=SNA
    UPPERCASESECURITY=N
    LOCALLUNAME=CTGCM01
    MODENAME=LU62PS
    NETNAME=GBIBMIYA.IY2GTG20
    PARTNERLUALIAS=N
ENDSECTION

Finally, set the CTGDCONF environment variable in the WPAR so that the shared copy of ctgd can locate the local configuration:

ctgwpar1 # export CTGDCONF=/tmp/ctgd.conf

If you now start CICS TG in both the WPAR and the global environment, SNA and IPIC should both work correctly:

aix7host # ctgd start
CICS Transaction Gateway, Version 8.0.0.1 : Build Level c800-20101014
(C) Copyright IBM Corporation 2004, 2010. All rights reserved.
Starting IBM CICS Transaction Gateway: started as root:system
ctgwpar1 # ctgd start
CICS Transaction Gateway, Version 8.0.0.1 : Build Level c800-20101014
(C) Copyright IBM Corporation 2004, 2010. All rights reserved.
Starting IBM CICS Transaction Gateway: started as root:system

Verify the logs to ensure that the correct ctg.ini is being used, and that the gateway APPLID's are correct and unique:

In the global environment:

06/23/11 18:12:47:206 [2] *** IBM CICS Transaction Gateway log V8.0.0.1 Build Level
 c800-20101014 ***
06/23/11 18:12:47:103 [0] CTG6400I CICS Transaction Gateway is starting
06/23/11 18:12:47:189 [0] CTG8448I Command line options updated adminport to be2810
06/23/11 18:12:47:221 [0] CTG8400I Using configuration file /opt/IBM/cicstg/bin/ctg.ini
06/23/11 18:12:47:221 [0] CTG8426I The applid is CTGGE
06/23/11 18:12:47:221 [0] CTG8427I The applid qualifier is CHRSQUAL

On ctgwpar1:

06/23/11 18:14:51:022 [2] *** IBM CICS Transaction Gateway log V8.0.0.1 Build Level
 c800-20101014 ***
06/23/11 18:14:50:785 [0] CTG6400I CICS Transaction Gateway is starting
06/23/11 18:14:51:000 [0] CTG8448I Command line options updated adminport to be 2810
06/23/11 18:14:51:025 [0] CTG8400I Using configuration file /tmp/ctg.ini
06/23/11 18:14:51:025 [0] CTG8426I The applid is CTGWPAR1
06/23/11 18:14:51:026 [0] CTG8427I The applid qualifier is CHRSQUAL

Now that the gateway daemons have both started correctly, you can run a sample to verify that the IPIC connection to CICS is working. Issue the following command:

aix7host # cat run_me.sh
#!/bin/ksh
/opt/IBM/cicstg/jvm16/bin/java -cp
 /opt/IBM/cicstg/classes/ctgserver.jar:/opt/IBM/cicstg/classes/ctgsamples.jar:
/opt/IBM/cicstg/classes/ctgclient.jar com.ibm.ctg.samples.eci.EciB1 tcp://aix7host 2006

aix7host # ./run_me.sh

CICS Transaction Gateway Basic ECI Sample 1

Usage: java com.ibm.ctg.samples.eci.EciB1 [Gateway URL]
                                          [Gateway Port Number]
                                          [SSL Keyring]
                                          [SSL Password]

To enable client tracing, run the sample with the following Java option:
 -Dgateway.T.trace=on

The address of the Gateway has been set to tcp://aix7host Port:2006

CICS Servers Defined:
         1. TS20IPIC – CICS TS IPIC server
         2. TX20 – TXSeries TCP server
         3. TS20 – CICS TS SNA server

Choose Server to connect to, or q to quit:
1

Program EC01 returned with data:-

        Hex: 32332f30362f31312031393a31323a35380
        ASCII text: 23/06/11 19:12:58

ctgwpar1 # ./run_me.sh

CICS Transaction Gateway Basic ECI Sample 1

Usage: java com.ibm.ctg.samples.eci.EciB1 [Gateway URL]
                                          [Gateway Port Number]
                                          [SSL Keyring]
                                          [SSL Password]

To enable client tracing, run the sample with the following Java option:
 -Dgateway.T.trace=on

The address of the Gateway has been set to tcp://ctgwpar1 Port:2006

CICS Servers Defined:
         1. TS20IPIC – CICS TS IPIC server
         2. TX20 – TXSeries TCP server
         3. TS20 – CICS TS SNA server

Choose Server to connect to, or q to quit:
1

Program EC01 returned with data:-

        Hex: 32332f30362f31312031393a31323a35390
        ASCII text: 23/06/11 19:12:59

You can now test a connection to CICS over SNA. The /etc/sna/sna_clnt.net file must be duplicated in the WPAR for the SNA daemon to start correctly.

aix7host # ./ecib1
CICS Transaction Gateway Basic ECI V1 Sample

Servers defined in the Client daemon:
   1.TX20
   2.TS20

Choose server to connect to:
2
Program EC01 returned with data: 24/06/11 10:42:10

ctgwpar1 # ./ecib1
CICS Transaction Gateway Basic ECI V1 Sample

Servers defined in the Client daemon:
   1.TX20
   2.TS20

Choose server to connect to:
2
Program EC01 returned with data: 24/06/11 10:47:57

View the client information log to confirm that both programs are running under their respective local LUs (CTGCM01 and CTGCM02):

aix7host # cat /var/cicscli/cicscli_info.log
06/24/11 10:36:15.491 [0049] CCL:CCL0200I *** IBM CICS Transaction Gateway Client log for
 'AIX' '8.0.0.1' Build Level 'c800-20101014' ***
06/24/11 10:36:15.508 [2239] CCL:CCL2239I Server 'TX20' is configured to use the TCP/IP
 protocol with NETNAME 'cicsserv.ibm.com' and PORT '7720'
06/24/11 10:36:15.513 [2238] CCL:CCL2238I Server 'TS20' is configured to use the SNA
 protocol with NETNAME 'GBIBMIYA.IY2GTG20' and LOCALLUNAME 'CTGCM02'
06/24/11 10:36:15.520 [2224] CCL:CCL2218I The initialization of the Client daemon is
 complete
06/24/11 10:42:10.296 [2228] CCL:CCL2222I About to connect to server 'TS20'
06/24/11 10:42:10.493 [2229] CCL:CCL2223I Connected to server 'TS20 ' using 'SNA' to
 'GBIBMIYA.IY2GTG20'

06/24/11 10:47:33.798 [0049] CCL:CCL0200I *** IBM CICS Transaction Gateway Client log for
 'AIX' '8.0.0.1' Build Level 'c800-20101014' ***
06/24/11 10:47:33.807 [2239] CCL:CCL2239I Server 'TX20' is configured to use the TCP/IP
 protocol with NETNAME 'cicsserv.ibm.com' and PORT '7720'
06/24/11 10:47:33.811 [2238] CCL:CCL2238I Server 'TS20' is configured to use the SNA
 protocol with NETNAME 'GBIBMIYA.IY2GTG20' and LOCALLUNAME 'CTGCM01'
06/24/11 10:47:33.819 [2224] CCL:CCL2218I The initialization of the Client daemon is
 complete
06/24/11 10:47:54.605 [2228] CCL:CCL2222I About to connect to server 'TS20'
06/24/11 10:47:57.176 [2229] CCL:CCL2223I Connected to server 'TS20 ' using 'SNA' to
 'GBIBMIYA.IY2GTG20'

Why use shared system WPARs?

The main advantage of a shared system WPAR topology is that the system software including CICS TG, the SNA Remote API Client, and the C/C++ compilers is installed once in the global environment and is then available to all shared system WPARs without any additional installation. Shared system WPARs can therefore have a relatively small footprint when compared with WPARs that are not shared.

In shared system WPAR scenarios (for example when communicating with CICS over TCP/IP), the configuration can also be common across all CICS TG instances. If gateway daemons must be uniquely identified (for example using IPIC or SNA protocols to communicate with CICS), then each WPAR must have its own local configuration, which must be managed independently of the global environment. Shared system WPARs also enable more efficient utilisation of the LPAR and let you create a workload manager in the global environment to distribute work between the WPARs.

Detached system WPAR

A detached system WPAR appears to be an entire self-contained AIX install, complete with its own isolated file system and network stack. An example of how you can use a detached system WPAR to run CICS TG is shown below. Figure 4 shows CICS TG installed in the global environment, and three detached system WPARs. Unlike the shared system WPARs in the previous section, these installations are isolated, and the program and configuration files are installed separately:

Figure 4. Deploying detached system WPARs
Deploying detached system WPARs

Setting up the detached system WPAR for private install

The first step in setting up a detached system WPAR is to create the WPAR. In this example, you specify that:

  • The WPAR name is ctgwpar4.
  • The install is private (detached from the global environment).
  • The hostname is ctgwpar4.
  • The network routing information is inherited from the global environment.
  • The network is set up to use en0 with the given IP address.
aix6host # mkwpar -n ctgwpar4 -l -h ctgwpar4 -r -N interface=en0 address=192.168.1.2
netmask=255.255.255.0

As for the shared system WPAR section, the WPAR name and the hostname do not have to be identical, but testing has shown that the SNA Remote API client looks for the WPAR name, not the hostname. If the names are different, the WPAR name may not resolve to a valid IP address.

The process of setting up the WPAR takes some time because it creates a copy of the AIX environment inside the WPAR. When the process has completed, you can start the WPAR:

aix6host # startwpar -v ctgwpar4
Starting workload partition 'ctgwpar4'.
Mounting all workload partition file systems.
Mounting '/wpars/ctgwpar4'.
Mounting '/wpars/ctgwpar4/home'.
Mounting '/wpars/ctgwpar4/opt'.
Mounting '/wpars/ctgwpar4/proc'.
Mounting '/wpars/ctgwpar4/tmp'.
Mounting '/wpars/ctgwpar4/usr'.
Mounting '/wpars/ctgwpar4/var'.
Loading workload partition.
Exporting workload partition devices.
Starting workload partition subsystem 'cor_ctgwpar4'.
0513-059 The cor_ctgwpar4 Subsystem has been started. Subsystem PID is 11206788.
Verifying workload partition startup.
Return Status = SUCCESS.
aix6host # lswpar
Name      State  Type  Hostname   Directory         RootVG WPAR
----------------------------------------------------------------
ctgwpar4  A      S     ctgwpar4   /wpars/ctgwpar4   no

Verifying the detached system WPAR install

From the LPAR, check that the mounted file systems are correct for a detached install. Mount all file systems under the created WPAR on /dev, which is different from the shared system WPAR, where mount points such as /wpars/CTG_WPAR1/opt use the file systems/opt (in read-only mode).

aix6host # df -k
Filesystem    1024-blocks      Free %Used    Iused %Iused Mounted on
/dev/hd4           327680    133972   60%    10820    25% /
/dev/hd2          7602176   4960396   35%    55415     5% /usr
/dev/hd9var        720896    373892   49%    12479    13% /var
/dev/hd3          2293760   2159324    6%      167     1% /tmp
/dev/hd1            65536     65144    1%       15     1% /home
/dev/hd11admin      131072    130692    1%        5     1% /admin
/proc                   -         -    -         -     -  /proc
/dev/hd10opt      2555904   2045364   20%    12617     3% /opt
/dev/livedump      262144    261776    1%        4     1% /var/adm/ras/livedump
/dev/fslv00        131072     82264   38%     2977    14% /wpars/ctgwpar4
/dev/fslv01         65536     64156    3%        5     1% /wpars/ctgwpar4/home
/dev/fslv02       2555904   2035252   21%    12614     3% /wpars/ctgwpar4/opt
/proc                   -         -    -         -     -  /wpars/ctgwpar4/proc
/dev/fslv03        131072    128420    3%       10     1% /wpars/ctgwpar4/tmp
/dev/fslv10       7602176   4874528   36%    53437     5% /wpars/ctgwpar4/usr
/dev/fslv11        131072     53320   60%     2755    19% /wpars/ctgwpar4/var

As with the shared WPAR, the detached system WPAR has its own IP address and can therefore be remotely logged into by users using rlogin and the TCP/IP hostname. The detached system WPAR also looks to the user like a normal AIX system; every file system appears as global and nothing outside the WPAR is visible.

aix6host # rlogin ctgwpar4
*******************************************************************************
*  Welcome to AIX Version 6.1!                                                *
*                                                                             *
*  Please see the README file in /usr/lpp/bos for information pertinent to    *
*  this release of the AIX Operating System.                                  *
*******************************************************************************
Last login: Thu 26 May 15:14:20 2011 on /dev/pts/0 from 192.168.1.3

ctgwpar4 # df -k
Filesystem    1024-blocks      Free %Used    Iused %Iused Mounted on
Global             131072     82216   38%     2991    14% /
Global              65536     64156    3%        5     1% /home
Global            2555904   2035660   21%    12614     3% /opt
Global                  -         -    -         -     -  /proc
Global             131072    128420    3%       12     1% /tmp
Global            7602176   4936516   36%    55414     5% /usr
Global             131072     49436   63%     2818    20% /var

If the WPAR is not configured with TCP/IP, you can use clogin (console login) to access and configure the WPAR, although without a TCP/IP stack, the CICS TG cannot be used.

The disadvantage of using detached system WPARs is that they use the default partition sizes when creating the WPAR, and the partition size may need to be increased to provide enough storage to install the software stack. In the example, the /tmp directory is too small to hold a copy of the CTG installer and increase its size in the global environment:

aix6host # chfs -a size=+1G /wpars/CTG_WPAR1/tmp
Filesystem size changed to 2359296
Inlinelog size changed to 8 MB.
aix6host # cp installer /wpars/CTG_WPAR1/tmp

Installing CICS TG in the detached system WPAR

Run the product installer:

ctgwpar4 # ./installer -i console
Preparing to install...
Extracting the JRE from the installer archive...
Unpacking the JRE...
Extracting the installation resources from the installer archive...
Configuring the installer for this system's environment...
Launching installer...

Accept all the defaults. CICS TG should install successfully into the WPAR. To verify the installation, compare the /opt/IBM in the global environment to the /opt/IBM in the WPAR:

aix6host # ls -l /opt/IBM
total 16
drwxr-xr-x   28 root     system         4096 24 May 17:38 ITM
drwxr-xr-x    2 root     system         4096 24 May 16:40 sysmgtlib

ctgwpar4 # ls -l /opt/IBM
total 24
drwxrwxr-x   17 root     system         4096 26 May 15:46 cicstg
drwxr-xr-x   28 root     system         4096 24 May 17:38 ITM
drwxr-xr-x    2 root     system         4096 24 May 16:40 sysmgtlib

Adding SNA Remote API Client and XL C compiler

There are two ways to install an application that uses the native AIX installer:

  • Multiple times (once for each system WPAR)
  • A single time in the global environment, followed by a synchronized copy of all file sets into each system WPAR.

The SNA Remote API client and xlC/C++ compiler both use the native AIX installer. For this example, they will be installed using the single-time method, which has the advantage that, although the software is installed a single time, each software instance runs independently in its own WPAR.

Smit gives you the option at install time to install in all detached WPARs. If you set the option to no, the WPARs can be manually synched at a later time by running the following command:

aix6host # syncroot
syncroot: Processing root part installation status.
syncroot: Installp root packages are currently synchronized.
syncroot: RPM root packages are currently synchronized.
syncroot: Root part is currently synchronized.
syncroot: Returns Status = SUCCESS

Each system WPAR should now act as an isolated SNA client and have a C/C++ compiler available.

Configuring the gateway daemon in the detached system WPAR

You can configure the gateway using the configuration tool. The configuration is local to this WPAR, so you must ensure that the APPLID and SNA local LU are unique.

Update the PATH for Java if the JVM is not referenced there:

ctgwpar4 # export PATH=/opt/IBM/cicstg/jvm16/bin:$PATH

Configure the Gateway daemon so that it has TCP/IP, SNA, and IPIC server definitions, and ensure that the logs are written to file and not to console. You must also enable the Gateway TCP and statistics port handlers. Now save the ini file into /opt/IBM/cicstg/bin in the WPAR. In this example, use ctgstart to start the gateway daemon. You should now verify that the gateway starts without error and is listening on the correct ports:

ctgwpar4 # ctgstart
*** IBM CICS Transaction Gateway log V8.0.0.1 Build Level c800-20101014 ***
(C) Copyright IBM Corporation 1996, 2010.  All rights reserved.
CTG6508I To shut down the Gateway daemon type
CTG6493I    Q or - for normal shutdown
CTG6494I    I for immediate shutdown

ctgwpar4 # more /var/cicscli/ctg_info.log
05/27/11 11:19:40:670 [2] *** IBM CICS Transaction Gateway log V8.0.0.1 Build Level
 c800-20101014 ***
05/27/11 11:19:40:626 [0] CTG6400I CICS Transaction Gateway is starting
05/27/11 11:19:40:661 [0] CTG8448I Command line options updated adminport to be 2810
05/27/11 11:19:40:673 [0] CTG8400I Using configuration file /opt/IBM/cicstg/bin/ctg.ini
05/27/11 11:19:40:673 [0] CTG8461I Successfully initialized trace plug-in
 'com.ibm.ctg.client.FileTrace'
05/27/11 11:19:40:676 [0] CTG6577I Java details: Version=1.6.0, Vendor=IBM Corporation,
 Path=/opt/IBM/cicstg/jvm16/bin/java
05/27/11 11:19:40:710 [0] CTG6981I Successfully initialized JNI library
05/27/11 11:19:40:758 [0] CTG6502I Initial Connection managers = 1, Maximum Connection
 managers = 100
05/27/11 11:19:40:759 [0] CTG6526I Initial workers = 1, Maximum workers = 100
05/27/11 11:19:40:763 [0] CTG6505I Successfully created the initial connection manager
 and Worker threads
05/27/11 11:19:40:771 [0] CTG6524I Successfully started handler for the tcp: protocol on
 port 2006
05/27/11 11:19:40:774 [0] CTG6524I Successfully started handler for the statsapi:
 protocol on port 2980
05/27/11 11:19:40:775 [0] CTG8455I Successfully started the local administration handler
 on port 2810
05/27/11 11:19:40:788 [0] CTG6512I CICS Transaction Gateway initialization complete
05/27/11 11:19:40:800 [0] CTG6411I Interval statistics are active. The statistics
 interval length is set to 3 hours, 0 minutes and 0 seconds. The statistics end of day
 time is set to 00:00:00 Greenwich Mean Time.

You can now send a sample request over an IPIC connection that references this gateway:

ctgwpar4 # ./ctgecib3 ctwpar4 2006
CICS Transaction Gateway Basic ECI V2 Sample 3

Usage: ctgecib3 [hostname] [port number]

Connected to CICS TG on ctgwpar4 using port 2006

Servers returned from CICS TG:
     1. TS20IPIC – CICS TS IPIC server
     2. TX20 – TXSeries TCP server
     3. TS20 – CICS TS SNA server

Choose server to connect to, or q to quit:
1
Enter text to send to the CICS program (max 128):
HELP ME!
Program EC03 returned containers:
    [BIT]  INPUTDATALENGTH = 00000007
   [CHAR]   INPUTDATACCSID =      819
   [CHAR]    OUTPUTMESSAGE = Input data was: HELP ME
   [CHAR]     CICSDATETIME = 27/05/2011 14:43:23
   [CHAR]        INPUTDATA = HELP ME
Closed connection to CICS Transaction Gateway

ctgecib3 completed successfully

Verify that SNA is working correctly in the WPAR by compiling and running the ecia1 sample, which tests the connections across both TCP/IP and SNA:

ctgwpar4 # export PATH=/usr/vac/bin:$PATH
ctgwpar4 # make -f samp.mak

Creating Advanced ECI C Sample
        cc_r -c -g -DCICS_AIX -I../../../include -I../../include ecia1.c
cc_r -o ecia1 ecia1.o -L../../../lib -L/opt/IBM/cicstg/lib -lpthreads -lc_r
-lcclaix

ctgwpar4 # ./ecia1
CICS Transaction Gateway Advanced ECI V1 Sample

SYNTAX :
  ecia1 <Threads> <Calls> <SYNC|ASYNC> [-DEBUG]
    where
  Threads    = Number of threads to run per server (Default=5)
  Calls      = Number of ECI calls to make per thread (Default=10)
  SYNC/ASYNC = Do (a)synchronous eci calls (Default=SYNC)
  -DEBUG     = Show all messages (Default is off)

Running with:
2 Servers
5 Threads per server
10 ECI calls per thread
Call type is synchronous
MAIN : Threads all started - Starting test
MAIN : Threads all finished - Results follow:
Server : TX20    , overall average time in seconds 0.020060
Server : TS20    , overall average time in seconds 0.023860
Press enter to terminate

Why use detached system WPARs?

Detached system WPARs offer the benefits of LPARs but have a smaller processor and memory footprint, enabling you to further carve up LPARs to sub-manage resources while running multiple gateways in the same LPAR. This improved utilisation of the LPAR enables you to create a workload manager in the global environment to distribute work between the WPARs.

Using WPARs in existing topologies

This section explores a few scenarios where you can use WPARs.

Expanding the capacity of an existing LPAR that uses TCP/IP connections

In this scenario, CICS TG is installed and configured to run within an LPAR. Connections to CICS are over TCP/IP. Using shared system WPARs, you can run many instances of the CICS TG configuration, with each configuration having its own network stack. This scenario better utilises LPAR resources while maintaining the low administrative overhead of a single product install and single configuration.

Running multiple versions of the CICS TG concurrently

In this scenario, multiple machines or LPARs are each hosting a different release of CICS TG. This topology is likely to consume a large amount of machine resources or LPAR resources. A more efficient solution is to consolidate the hardware into a single LPAR with each instance running as a detached system WPAR.

Testing new releases before deploying

This scenario is similar to the previous one. A detached system WPAR is used to test a new release of CICS TG in the current operating environment with existing applications. There is no impact on the existing installations and configurations.

Running multiple applications in the same LPAR

In a scenario where multiple, long-duration applications are running in the same LPAR, you can run each application in its own WPAR. Doing so isolates each application from the other parts of the system, so that if an application fails, the failure is contained within the WPAR without affecting the other applications.

Conclusion

This article described two types of WPAR – the application WPAR and the system WPAR, and showed how CICS TG can interoperate with them. The article also described various customer scenarios where deploying WPARs with CICS TG can provide significant advantages.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, AIX and UNIX
ArticleID=774829
ArticleTitle=CICS Transaction Gateway and AIX workload partitions
publish-date=11162011