1. Application Runtime for CICS User's Guide
  2. Integrating Client Applications Using CPI-C

13 Integrating Client Applications Using CPI-C

This chapter contains the following topics:

13.1 Overview

The Common Programming Interface for Communications (CPI-C) provides a common application programming interface (API) for implementing APPC. CPI-C provides a consistent set of functions for program-to-program communication across different platforms.

Customer applications running on open systems (Windows, Linux, Unix) can use the CPI-C interfaces for APPC communication with mainframe applications running under IBM CICS and IMS TM. After rehosting such mainframe applications to Tuxedo ART, the open systems applications want to preserve the CPI-C/APPC interfaces for communicating with the rehosted mainframe applications in order to avoid or minimize any change. Using Tuxedo ART CICS support for CPI-C interfaces, customer applications can continue to interface with the rehosted mainframe applications without changing any application code.

ART CICS CPI-C support covers the following:

Table 13-1 ART CICS CPI-C Support Coverage

CPI-C APPLICATIONS (CLIENT) CPI-C APPLICATIONS (SERVER)
Windows VS Client WebLogic JAM Client CICS Applications
Over Tuxedo Workstation Client (WSC) Over WTC ARTCTRN/1

WSL/WSH for WSC

Domain Gateway for WTC

MS Visual Studio C/C++, 32-bits JDK 1.6 or higher, 64-bits COBOL/C, 64-bits

Tuxedo ART CICS CPI-C support includes the following components:

  • For Windows, a library kixcpicws.dll, which provides CPI-C interfaces as a replacement for Windows CPI-C/SNA library, using Tuxedo WSC for communications instead of Windows SNA support.
  • For WebLogic, a set of Java classes that implement CPI-C interfaces, replacing JAM beans and using WTC for Tuxedo Domains communications support.
  • For Tuxedo ART CICS runtime, a CPI-C library that works in ARTCTRN servers to support COBOL/C programs using CPI-C.

    For more information, see Supported CPI-C Scenarios.

In addition, ART CICS CPI-C integration provides the support for Windows VS C/C++ applications over Tuxedo WSC and Java applications over WTC, the applications acts as client and use APPC protocol to interoperate with rehosted Mainframe CPI-C applications running under ART CICS server.

Parent topic: Integrating Client Applications Using CPI-C

13.1.1 Client Applications Impact

The section contains the following topics:

Parent topic: Overview

13.1.1.1 Windows Visual Studio C/C++ Environment

Windows applications need to be rebuilt/re-linked using the ART CICS CPI-C library provided for this support. The new library supports the same APIs so no code changes are involved once it's linked in with the application.

This library uses Tuxedo Workstation Client (WSC) on Windows as its communications channel with Tuxedo. This Tuxedo component has to be installed and configured on Windows.

13.1.1.2 WebLogic Java Environment

WebLogic users need to regenerate the EJB package with new version of callService() class that provides main access point to CPI-C interfaces and java class files which provide the ART CICS implementations of CPI-C interfaces.

These classes use WebLogic-Tuxedo Connector (WTC) as its communications channel with Tuxedo. This WebLogic component has to be installed and configured on WebLogic Server.
13.1.1.3 ASCII-EBCDIC Data Conversion

Mainframe applications use EBCDIC data encoding and require Windows and WebLogic applications to specify ASCII-EBCDIC conversion in their calls. When rehosted to ART CICS, these mainframe applications run using ASCII data encoding, so no conversion is required. If Windows or WebLogic applications specify ASCII-EBCDIC data conversion, it should be disabled when working with Tuxedo ART CICS applications.

13.2 Supported CPI-C Scenarios

This section contains the following topics:

Parent topic: Integrating Client Applications Using CPI-C

13.2.1 Windows Application Calling Rehosted CICS Transactions

The client application on Windows server communicates with CICS server application on Tuxedo using the CPI-C APIs in both client and server side code. Windows application with ART CICS CPI-C library uses Tuxedo workstation client, and CPI-C APIs are handled by internal Tuxedo ATMI calls by the ART CICS CPI-C libraries. ARTCTRN server also provides CPI-C interfaces in ART CICS runtime. The rehosted CICS application can directly use CPI-C interfaces without any code changes.

Figure 13-1 CPI-C Client Application on Windows Server


CPI-C Client Application on Windows Server

The diagram above shows CPI-C client application on Windows server which communicates with a CPI-C server CICS program in KIXS region in Tuxedo Domain through Tuxedo Workstation Protocol conversation. CPI-C client library establishes a connection with a tpconnect() call to a CICS transaction running in one or more ARTCTRN servers (ART CICS application server for conversational transactions/programs) and uses Tuxedo conversational tpsend()/tprecv() API calls to mimic CMSEND/CMRCV. Application code on both sides represented by blue shaded areas remains unchanged, with Tuxedo ART infrastructure components providing all the necessary API and communications support.

Parent topic: Supported CPI-C Scenarios

13.2.2 WebLogic Application Calling Rehosted CICS Transactions

The Java client application in WebLogic communicates with CICS application in server side over iWay JAM. The client side uses RMI callService() provided by JAM, and the server side uses CPI-C interfaces and CICS APPC interfaces. ART CICS overloads the callService() method in client side, callService() is composed of a series of CPI-C calls to exchange the application data with CICS application. ART CICS provides the source codes of an overloaded callService() method, and provides a series of Java class files to provide the implementations of CPI-C interfaces.

Figure 13-2 CPI-C Client Application on Windows Server


CPI-C Client Application on Windows Server

As shown in the diagram above, EJB application runs as CPI-C client on WebLogic server and communicates to CPI-C server CICS program in KIXS region through WTC connection to Tuxedo Domain Gateway using conversational protocol. CPI-C client library establishes a connection through tpconnect() call for a CICS transaction published by ARTCTRN (ART CICS application server for Conversational transactions/programs) and uses Tuxedo conversational tpsend()/tprecv() API calls to mimic CMSEND/CMRCV. Application code on both sides represented by blue shaded areas remains unchanged, with Tuxedo ART infrastructure components providing all the necessary API and communications support.

Parent topic: Supported CPI-C Scenarios

13.3 Server Side Configuration

To configure the server , you need to perform the following tasks:

Parent topic: Integrating Client Applications Using CPI-C

13.3.1 ART CICS Resources Configuration

This section contains the following topics:

Parent topic: Server Side Configuration

13.3.1.1 CICS Region Definitions in systems.desc

Configure SYSID for client and server. In the following example, in KIXA, for Windows client, sysid is KIXA and APPLID is ARTKIXA. In KIXB, for CPI-C server, sysid is KIXB and APPLID is ARTKIXB.

[KIXA]

APPLID=ARTKIXA

[KIXB]

APPLID=ARTKIXB

13.3.1.2 CICS APPC Connection Definitions in connections.desc
Configure protocol in connections.desc. In the following example, KIXA connects to KIXB, and protocol is APPC. Resource group DTPAPBK is later used in transaction definition.
[KIXA]
group=DTPAPBK
protocol=APPC
netname=ARTKIXA
maximum=5,2
 
[KIXB]
group=DTPAPBK
protocol=APPC
netname=ARTKIXB
maximum=5,3
13.3.1.3 CICS Transaction Definitions in transactions.desc

Configure CPI-C transaction in server side. The following example configures BC32 as a CPI-C transaction in server side.

BC32;DTPAPBK;APPC server; xxxxxxxx

13.3.2 Oracle Tuxedo Configuration

This section has the following topics:

Parent topic: Server Side Configuration

13.3.2.1 UBBCONFIG Configuration
  • Configure ARTCTRN server in SERVERS section. The following example specifies KIXB region in CLOPTs with -s and CICS resource group with -l. The MIN/MAX values can be adjusted to match the number of concurrent conversations that the application must support. Since APPC/CPI-C is a conversational mode protocol, the ARTCTRN server will block on CMSEND until the client does CMRCV, and will block on CMRCV until the client performs CMSEND.

    ARTCTRN

    SRVGRP=GRP02

    SRVID=30

    CONV=Y

    MIN=1 MAX=1 RQADDR=QKIX030 REPLYQ=Y

    CLOPT="-o /stdout_ctrn -e /stderr_ctrn -r -- -s KIXB -l DTPSUB:DTPAPBK"

  • Configure workstation listener (WSL) server in SERVERS section. In the following example, two WSHs are started initially, up to maximum of five WSHs can be started, up to 5 /WS clients per WSH WSL SRVGRP=G1 SRVID=10 CLOPT="-A -- -n //gumby:9977 -m 2 -M 5 -x5"
  • Configure MACHINES section.
    • MAXWSCLIENTS: maximum numbers of WSCs for each machine is specified.
    • MAXACCESSERS: MAXWSCLIENTS + number of Tuxedo servers connected to the bulletin board (including all servers listed in UBBCONFIG, plus maximum allowed WSL/WSH servers).
  • Configure domain servers in SERVERS section for connecting WebLogic server. For example,

    DMADM SRVID=1030 SRVGRP=DMGRP

    GWADM SRVID=1040 SRVGRP=GWGRP

    GWTDOMAIN SRVID=1050 SRVGRP=GWGRP

    Note:

    Make sure you compile UBBCONFIG with tmloadcf.
13.3.2.2 DMCONFIG Configuration

Configure DMCONFIG for WTC Tuxedo domain configuration. See an example as follows.

*DM_LOCAL_DOMAINS

DOM GWGRP="GWGRP"

TYPE=TDOMAIN

DOMAINID=KIXD

*DM_REMOTE_DOMAINS

wldom1 TYPE=TDOMAIN DOMAINID=TDOM2 ACL_POLICY=GLOBAL

*DM_TDOMAIN

wldom1 NWADDR="//10.0.0.1:5669"

DOM NWADDR="//10.0.0.2:5022"

*DM_LOCAL_SERVICES

KIXR_CPIS LDOM=DOM

Note:

Make sure you compile DMCONFIG with dmloadcf.

13.4 Client Side Configuration

The section contains the following topics:

Parent topic: Integrating Client Applications Using CPI-C

13.4.1 Configuration for Windows Client

Windows client uses sym_dest_name set by cminit() to connect the target ART CICS server. sym_dest_name should be set as the sysid of target ART CICS server.

  • To use Tuxedo/WS client, two environment variables should be set on Windows:
    • TUXDIR=c:/tuxedo

      This is the Tuxedo install location.

    • WSNADDR=//gumby:9977

      This is the hostname and port of Tuxedo server WSL connection from -n parameter in WSL's CLOPTs.

  • KIX_CPI-C_WSSYSID is introduced to specify CPI-C /WS client sysid. It is needed to establish the connection between CPI-C /WS client and CPI-C CICS server. It should be set to client sysid listed in connections.desc (KIXA in this example).
  • To track CPI-C client runtime log, a new environment variable is introduced to show the log file path. If ARTKIX_CLIENT_LOGPATH is not set, the log will be printed to local directory.

    ARTKIX_CLIENT_LOGPATH=c:/tmp/ARTKIX_client.log

Parent topic: Client Side Configuration

13.4.2 Configuration for WebLogic Client

No specific configuration is required for using CPI-C java classes other than a basic WTC access point configuration for connecting to Tuxedo Domain as documented in Administering WTC manual. WTC supports on_startup and on_demand connection policies and can support failover and failback between primary and alternate access points to multiple Tuxedo domains or a single domain deployed across multiple machines (MP mode domain).

Parent topic: Client Side Configuration

13.5 Oracle Tuxedo Timeout Controls

Tuxedo enforces multiple types of timeouts through configuration. The timeout control for a blocked operation depends on SCANUNIT and BLOCKTIME settings in UBBCONFIG. Both of these can be set globally in RESOURCES section, and BLOCKTIME can additionally be set per service in SERVICES section of UBBCONFIG. See Settings in UBBCONFIG for more information.

This is an example of global timeout management in UBBCONFIG. In this example, the BLOCKTIME x SCANUNIT is 40 seconds. The client will be blocking on CMRCV until it really gets the response. If it does not complete in 40 seconds, it then returns TPETIME to report timeout and CMRCV return error CM_RESOURCE_FAILURE_RETRY.

*RESOURCES

BLOCKTIME 8

SCANUNIT 5

This is an example of granular timeout management for transactions in UBBCONFIG. In this example, it specifies that global timeout setting is 60 seconds (12 x 5), but Tuxedo service KIXB_B32 (which maps to CICS transaction B32 in region/SYSID KIXB) has a timeout of 40 seconds (8x5).

Note:

Transactions that have no explicit BLOCKTIME specified in *SERVICES section are controlled by the global timeout setting. 
*RESOURCES
SCANUNIT 5
BLOCKTIME 12
…
*SERVICES
KIXB_B32 BLOCKTIME 8

Parent topic: Integrating Client Applications Using CPI-C

13.5.1 Settings in UBBCONFIG

SCANUNIT numeric_value

The interval of time (in seconds) between which periodic scans are done by the BBL to find old transactions and timed-out blocking calls within service requests. This value is used as the basic unit of scanning by the BBL. It affects the granularity with which transaction timeout values can be specified on tpbegin() and the blocking timeout value specified with the BLOCKTIME parameter. The SANITYSCAN, BBLQUERY, DBBLWAIT, and BLOCKTIME parameters are of this unit for other timed operations within the system. SCANUNIT must be a multiple of 5 greater than 0 and less than or equal to 60 seconds. The default is 10 seconds.

BLOCKTIME numeric_value

Sets a multiplier of the basic SCANUNIT after which a blocking call (for example, receiving a reply) times out. The value of BLOCKTIME must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.

Parent topic: Oracle Tuxedo Timeout Controls

13.5.2 Security

ART CICS CPI-C checks user/password passed from CPI-C security interface (cmscsu/cmscsp), and then it does local Tuxedo security check inside. The user/password should be added based on security levels set in Tuxedo security framework.

Parent topic: Oracle Tuxedo Timeout Controls

13.5.3 Scaling

To scale the configuration to support larger number of concurrent connections, you can:

  • Configure multiple WSLs and increase WSH min/max limits in Tuxedo domain for handling more concurrent Windows connections.
  • Configure multiple Tuxedo domain gateways to handle multiple WTC access points for more concurrent WebLogic connections.
  • Configure multiple ARTCTRN servers to run more instances of the CICS transactions in parallel. Since CPI-C is a conversational protocol, each server will block waiting for user response. The number of servers you configure should roughly correspond to the number of concurrent users of the CICS transactions.

Parent topic: Oracle Tuxedo Timeout Controls

13.5.4 Diagnostics

Runtime log will be printed for debugging. You can set KIX_TRACE_LEVEL environment variable to control log level from 1 to 9.

Parent topic: Oracle Tuxedo Timeout Controls

13.5.5 Packaging/Installation

ART CICS runtime provides a dynamic library for ART CICS CPI-C support. The Windows version of the library is named kixcpicws.dll and Linux version is named libkixcpicws.so. To use ART CICS CPI-C library, you only need to build/link with this library instead of Microsoft/IBM CPI-C library in your build project.

  • For Windows/Linux Using Tuxedo Workstation Client

    The Windows library is provided in a separate Windows distribution package. Current version of the library kixcpicws.dll is built on VC6 and certified with Tuxedo Workstation Client from Microsoft Windows (32-bit) tuxedo81_win distribution for Windows server 2003. To use the library, you need to link kixcpicws.dll with the application or dynamically open the *.dll in the runtime.

  • For WebLogic Server Using WTC

    ART CICS provides source code of an overloaded callService() method, and provides a series of Java class files to provide the implementations of CPI-C interfaces. You need to regenerate the EJB package with new version of callService() and java class files provided by ART CICS.

Parent topic: Oracle Tuxedo Timeout Controls