3
CICS and the CICS Adapter

This chapter discusses the following:

• The CICS Adapter

• Message Description Language (MDL)

• Classes

• LU6.2 CPI-C Protocol Stack, ECI Protocol Stack, and URLs

• How the CICS Adapter Communicates With CICS

• CICS Adapter Security

• Implementing the CICS Adapter

• Using the CICS Adapter Inbound

• Creating an Implemented Procedure

• Creating a Subscribed Event

The CICS Adapter

In CICS, both partners (CICS and the CICS adapter) must define the content of the CICS buffer. When this is done, it is possible to exchange data.

The CICS adapter provides the OracleAS InterConnect system with the ability to interact with CICS. To make the CICS buffer description visible to OracleAS InterConnect, the adapter specifies how to format data (representing a call) on a communication line by describing the format of the data being passed. The format is described in an Message Description Language (MDL) file. It abstracts a method call as input and output messages. A normal method call has arguments passed from the Agent (caller) to CICS (callee) represented as synchronous or asynchronous messages going up and back from arbitrary services.

Individual message reply and request pairs (each request message can have a reply message) describe interactions between clients and servers.

The CICS adapter represents a method call as a pair of messages:

• A request message containing all input arguments.

• A reply message containing all output arguments.

Message Description Language (MDL)

Message-oriented technology does not have any type description which object-technologies require. A language specification, the Message Description Language, describes the internal data format of each message buffer.

The CICS adapter uses the Message Description Language to describe the CICS buffer.

Message Description Language elements are message buffers, sent or received by the CICS adapter, mapped as Message Description Language method arguments. The mapping allows object-oriented technologies to have a familiar view of the message buffers; with each message treated as a single argument or separated into multiple arguments. The CICS adapter automatically concatenates the arguments at run-time. The request and reply messages are grouped as a single method with input and output arguments. One Message Description Language interface groups Message Description Language methods (performing similar tasks) for a specific message queue.

Classes

To make CICS servers visible as components to OracleAS InterConnect applications, you first describe a set of methods using adapter's message formats. A method call translates into a request message and a reply message. The request message contains all the input arguments and the reply message contains all the output arguments.

The CICS adapter uses Message Description Language *.cls files as the representation of component interfaces with methods having elements as arguments. For example, the message definition:

method GetBalance
   in BankName bank
   in CustName customer
   out Balance balance
   out CustStatus status
end method

defines a method containing four arguments with the type defined using Message Description Language fixed length string types:

typedef string(54,' ',tail) BankName
typedef string(30,' ',tail) CustName
typedef string(20,' ',head) Balance
typedef string(20,' ',tail) CustStatus

The following is an example of a Message Description Language file for CPI-C LU6.2 SNA protocol. This file must be named cics62b.cls (this is the class name and the cls extension):

#cics62b.CLS
# Class for CICS A62B transaction invoking ACTB62P1 Program
#   Note the ACTB62P1 program is invoking (CICS LINK) ACTBNKP1 Program

class cics62b (lu62cpic://CICSVIET)
   struct dfhcommarea
      string(8,' ',tail)                       transCode
      number(5,0,none) in string(5,'0',head)   acctNumber
      string(20,' ',tail)                      clientName
      number(6,2,none) in string(8,'0',head)   Amount
      number(8,2,none) in string(10,'0',head)  Balance
      string(3,' ',tail)                       ReturnCode
      string(80,' ',tail)                      Information
   end struct
   method AB62
      return void
      inout dfhcommarea programdata
   end method
end class

#          01  IOAREA.
#          05 TRANSACTION-CODE     PIC X(8).
#          05 ACCOUNT-NUMBER       PIC 9(5).
#          05 CLIENT-NAME          PIC X(20).
#          05 TRANSACTION-AMOUNT   PIC 9(6)V99.
#          05 ACCOUNT-BALANCE      PIC 9(8)V99.
#          05 APPL-RETURN-CODE     PIC X(3).
#          05 APPL-ERROR-MESSAGE   PIC X(80).

LU6.2 CPI-C Protocol Stack, ECI Protocol Stack, and URLs

At run-time, the CICS adapter interacts with the communication framework to pass along data over the adapter CPI-C protocol stack or the ECI protocol API. You can use either of these protocol stacks with the CICS adapter.

Both the ECI protocol API and the CPI-C protocol stack (CPI-C LU6.2 SNA protocol API) defines the transport layer used to communicate data between CICS applications and adapter. Just as the metadata describes how to format documents, the protocol stack defines the shipping mechanism.

Message Description Language class files must specify a URL in the class definition. URLs specify routing information when describing destinations within the CICS world. The URL contains CPI-C transport, ECI transport, and protocol under the form of a protocol stack identifier, as well as transport specific server identification. The following is an example using the CPI-C LU6.2 SNA protocol API:

lu62cpic://luname/tpname

where:

• lu62cpic--Specifies the IBM snalu62 protocol stack, using the CPI-C API.

• Luname--Alias of the remote location unit name of the destination.

• tpname--CICS transaction name.

The following is an example using the ECI protocol API:

eci://cicsservername/cicsprogramname

where:

• eci--Specifies the ECI protocol API.

• cicsservername--Specifies the CICS server name.

• cicsprogramname--Specifies the CICS program name.

How the CICS Adapter Communicates With CICS

The CICS adapter uses either a SNA LU62 CPI-C interface or ECI protocol application to communicate with CICS.

Using SNA LU 6.2 CPI-C Protocol API

To achieve the communication, install the CICS adapter on a machine that has the IBM eNetwork communication server or the IBM eNetwork communication client, or on a machine having a Microsoft SNA server or Microsoft SNA client.

Install all the required definitions in the following locations:

• Local SNA Server

• Remote SNA Server (Virtual Telecommunications Access Method/Network Program Control)

• CICS tables

To communicate with CICS, the CICS adapter needs two pieces of information:

1. Remote LU alias--The name defined in the local SNA server. Usually it is the same name as the remote LU name (this name is often also the name of the CICS in VTAM (VTAM ACB)).

2. transaction program Name--The name of the CICS transaction. Its length is usually four characters.

The URL specified in the Message Description Language class definition provides this information.

Using the ECI Protocol API

To achieve the communication, install the CICS adapter on a machine that has the IBM CICS Universal Client. This software may require one of the following pieces of software to communicate with the CICS server:

• TCP/PI--This protocol can be used with non-mainframe CICS server.

• TCP62--This protocol can be used with all CICS servers. It requires IBM Personal Communication software installed on the computer running ACB with the CICS adapter using the ECI protocol.

• SNA LU6.2--This protocol can also be used with all CICS servers. It requires IBM eNetwork Communication Server client or server software installed on the computer running ACB with the CICS adapter using the ECI protocol.

To communicate with CICS, the CICS adapter needs two pieces of information:

1. CICS server name--The name defined in the CICS Universal Client configuration. It is the server name.

2. CICS program name--The name of the CICS program. Its length can be up to eight characters. This is the name of the program as defined in the CICS region

The URL specified in the Message Description Language class definition provides this information.

CICS Adapter Security

Security is provided by the CICS adapter and by the different software needed by the protocols.

Using the LU 6.2 CPI-C Protocol

There are different levels of security when using the CICS adapter with the SNA LU 6.2 CPI-C protocol. Security may be optional, but it is almost always used in mainframe applications. You may also have security between the SNA Client and the SNA server (if you are using a SNA client) and security between SNA servers (the mainframe SNA server and the SNA server used by the CICS adapter to communicate. For more details refer to your system administrator or to the SNA (Microsoft or IBM) books for the CICS LU6.2 CPI-C protocol and to the IBM SNA and CICS mainframe books.

Security can be specified in the user profile. If you are using security, you must provide a user identification and a password that your mainframe application accepts.

See Also: "Using the Configuration Editor"

Using the ECI Protocol

There are different levels of security when using the CICS adapter with the ECI protocol. Security may be optional, but it is almost used in mainframe applications. The security used in the CICS Universal agent depends on which communication protocol is used. For more details, refer to your system administrator or to the CICS Universal Agent documentation.

Security can be specified in the user profile. If you are using security, you must provide a user identification and a password that your mainframe application accepts.

See Also: "Using the Configuration Editor"

Implementing the CICS Adapter

There are two parts in the implementation:

• LU 6.2 protocol or the ECI protocol API

• CICS adapter

SNA LU 6.2 CPI-C Protocol API

LU 6.2 provides the services required to establish a conversation with the Remote partner of the CICS adapter, the Mainframe CICS region. The services related to a transaction program are:

• Start transaction program (identify to LU 6.2 a transaction program that can issue ALLOCATE or MC_ALLOCATE).

• Stop the transaction program.

• Data related to a transaction program--transaction program identification and transaction program behavior (dead or alive).

• Services related to a Conversation:
  • Receive_Allocate (start an invoked transaction program)

  • Send Data

  • Receive data

  • All the other APPC conversation verbs

• Data related to a conversation--Conversation Identification, conversation behavior (dead or alive), and conversation states (reset, receive, or send state).

ECI Protocol API

ECI provides the service requires to establish a Distributed Program Link (DPL) call to a CICS program running in a CICS region, through the Commarea. The services related to a Distributed Program Link call are:

• Provides security information if required.

• Establish contact with the CICS Universal Agent.

• Do the call to a remote CICS program, by passing to the CICS Universal agent:
  • Name of the CICS server.

  • Name of the CICS program.

  • Commarea containing the application data.

  • User Id and password, if required.

CICS Adapter

The CICS adapter in inbound mode does the following:

• Uses services provided by the SNA LU 6.2 CPI-C protocol or by the ECI protocol.

• Provides UserID and Password for security (at data communication message level).

• Builds from the metadata and the request received messages sent to the CICS region.

If using services provided by the SNA LU 6.2 CPI-C protocol, the following is achieved:

• Allocates a conversation with the remote Transaction Program (CICS region).

• Sends the required data and security.

• Receives reply (replies) from the CICS program.

• Converts the data to the original format.

If using services provide by the ECI protocol:

• Connect with the CICS Universal Agent (using the CICS server Name and security).

• Sends the required data using to the CICS program.

• Receives reply (replies) from the CICS region.

• Converts the data to the original format.

CICS Adapter Information Flow

The following is the CICS adapter information flow:

• Receives a request from the OracleAS InterConnect application.

• Transforms the component (in a CICS transaction and in procedures to obtain what it is required).

• For SNA LU 6.2 CPI-C:
  • Transaction definition

  • Transaction code and input data (format) (fields position + type: binary, ASCII, EBCDIC)

  • Transaction output data format

  • Transaction destination and protocols

  • LU name (Transaction destination)

  • Protocol used (LU 6.2 CPI-C)

  • Security (application level--logical to be mapped in configuration data (logonids or others)

• For ECI:
  • Commarea definition

  • Program name and input data (format (fields position & type: binary, ASCII, EBCDIC)

  • Message Destination (CICS Server name)

  • Security (application level--logical to be mapped in configuration data logonIds or others)

• Sends the result of the transformation to the Communication layer.

• Receives transaction responses from the Communication layer.

• Transforms the transaction response.

• Sends the response to the OracleAS InterConnect application.

• Uses functions library for sending/receiving data (CPI-C and/or APPC or ECI Protocol API).

The Communication Layer manages physical communication with the mainframe (physical links, PUs and logical units activation/deactivation, and link security). It sends and receives data received from the CICS adapter.

Multi-Threading

The following are multi-threaded for SNA LU62 CPI-C:

• CICS

• SNA servers (VTAM and Windows)

The SNA API DLLs support multiple calls from a program using APPC or CPI-C SNA APIs.

More than one instance of the CICS adapter are possible:

• one to one

• one to two or plus

• two or plus to one

• two or plus to two or plus

It is possible for one instance of the CICS adapter to have more than one conversation with multiple remote transaction programs.

Note: Implementation of security and/or implementation of multi-threading is specific to the SNA server and to the functions provided by the API. For example, Microsoft provides a Windows standard APPC where they allow asynchronous APPC calls on Windows.

The following are multi-threaded for ECI:

• CICS

• The CICS Universal Agent

• Windows

The CICS Universal Agent DLLs support multiple calls from a program using ECI API.

More than one instance of the CICS adapter is possible. The possibilities are:

• one to one

• one to two or plus

• two or plus to one

• two or plus to two or plus

It is possible for one instance of the CICS adapter to have more than one program call to multiple CICS regions.

Implementation of security and/or implementation of multi-threading is specific to the CICS Universal Agent and to the functions provided by the API.

Using the CICS Adapter Inbound

Sending messages inbound means that the CICS adapter is the client and CICS is the server. To send messages to CICS using the CPI-C LU 6.2 SNA protocol, ensure that the SNA client and the adapter configuration settings are setup properly. To use an ECI protocol, ensure that the IBM Universal client and adapter settings are set up properly.

SNA LU 6.2 CPI-C Protocol

Before using the CICS adapter, you must prepare your environment. For example:

• SNA controllers are up and running.

• CICS at the mainframe is up and running.

• Session(s) between LUs are either active or inactive. If sessions are active, the Bind security was done at session activation.

Application Start-up

Launch the CICS adapter. In its initialization process, the CICS adapter sends a TP_START APPC verb. The SNA returns a TP_id. All conversations and commands sent to the SNA controller use this TP_id. It is valid until the adapter issues a TP_END later in the allocation of a conversation.

Receiving a CICS Adapter Request from OracleAS InterConnect

When the CICS adapter receives a request, complete the following:

1. Extract the data required to build the CICS transaction.

2. Get and set all related settings for the conversation:
   • Security information--UserID and Password.

   • ModeName--Characteristics of the session between the 2 LUs.

   • Synchronization level of the conversation--NONE or CONFIRM.

   • Remote LU name--The SNA name of the CICS region.

   • Remote transaction program name--For CICS, he CICS transaction name.

   • Start (allocate) the conversation--The protocol obtains from SNA a conversion identifier. This identifier is used on each subsequent call to the SNA LU62 CPI-C API for this conversation.

   • Data is sent to the CICS region through SNA.

3. Issue a confirmation command if CONFIRM is set as synchronization level.

4. Issue a receive command to receive the reply from the CICS transaction.

   When all the data is received, the session will be de-allocated and the CICS adapter receives notification. With the data, the CICS adapter builds back a reply to the requestor.

ECI Protocol

Before using the CICS adapter, you must prepare your environment. For example:

• CICS Universal agent is up and running.

• Communications software used by CICS agent is up and running.

• CICS at the mainframe is up and running.

Application Start-up

To start the application, launch the CICS adapter.

Receiving a CICS Adapter Request from OracleAS InterConnect

When the CICS adapter receives a request, complete the following:

1. Extract the data required to build the CICS program Commarea.

2. Initialize and set all the control information, such as:
   • CICS Server Name--Name of the CICS server, as known by the CICS Universal Agent.

   • CICS Program Name--Name of the CICS program, as known by the CICS region.

   • If required, enter the User Id and Password.

3. Send the data to the CICS region.

4. The CICS program in the CICS Region receive data in a memory buffer called Commarea. It processes the data and puts back output data in the same buffer. When finished, control returns to the CICS Server.

5. The CICS server sends back the Commarea to the CICS Universal Agent.

6. The CICS Universal Agent passes the buffer back to the CICS adapter.

Design Time

Create an Message Description Language *.cls file describing the messages buffer format to send and receive as Message Description Language method argument parameters.

See Also: "Message Description Language Reference" "Classes" for an example of an Message Description Language class file

Create a new sub-directory under config/CICS and copy the Message Description Language class file into the new directory. After the Message Description Language files have been copied into the directory, the interfaces are visible to OracleAS InterConnect. iStudio can be used in the normal manner to create definitions, procedures, and events.

You use the CICS adapter to:

1. Expose the Message Description Language interface in iStudio.

2. Define application views in iStudio.

Runtime

Performing a call requires a bidirectional exchange of information with the CICS servers. On performing a call, the CICS adapter extracts all input information from the passed in arguments; it uses information within the Message Description Language to format these arguments into an input message. The CICS adapter uses the URL provided in the Message Description Language file to connect to the service.

Creating an Implemented Procedure

To create an implemented procedure using iStudio:

1. Start iStudio.

2. Open your project.

3. Expand the Applications folder.

4. Right-click Implemented Procedures and select New.

   Figure 3-1 iStudio - New Implemented Procedure

   

   Text description of the illustration newimplementedprocedure.gif

   The Implement Wizard--Select a Procedure dialog displays.

   Figure 3-2 Selecting a Procedure

   

   Text description of the illustration selectaprocedure.gif

5. Select the Application and Message Type from the dropdown lists.

6. Select a procedure and click Next. The Implement Wizard--Define Application View dialog displays.

   Figure 3-3 Implement Wizard - Define Application View - Importing CICS

   

   Text description of the illustration implementwiz.gif

7. Click Import and select CICS from the dropdown list. The Component Selector dialog displays.

   Figure 3-4 Component Selector

   

   Text description of the illustration componentselector.gif

8. Expand the CICS tree to display the component for selection.

9. Select a component and click OK. The populated Define Applications View dialog displays.

   Figure 3-5 Implement Wizard - Define Application View Dialog

   

   Text description of the illustration implpopulateddefineapp.gif

10. Click Next to define the mappings.

    The Define Mappings dialog displays.

11. Click New to define mappings and click Finish.

    The new populated event displays in the right panel of iStudio.

Creating a Subscribed Event

To create a subscribed event in iStudio:

1. Start iStudio.

2. Open your project.

3. Expand the Applications folder.

4. Right-click Subscribed Events and select New.

   Figure 3-6 iStudio--Creating a Subscribed Event

   

   Text description of the illustration newsubevent.gif

   The Subscribe Wizard--Select an Event dialog displays.

   Figure 3-7 Select an Event

   

   Text description of the illustration selectanevent.gif

5. Select the Application and Message Type from the dropdown lists.

6. Select an event and click Next.

   The Define Application View dialog displays.

   Figure 3-8 Implement Wizard - Define Application View - Importing CICS

   

   Text description of the illustration defineapplicationview.gif

7. Click Import and select CICS. The Component Selector dialog displays.

   Figure 3-9 Component Selector

   

   Text description of the illustration componentselector.gif

8. Expand the CICS tree to display the correct component for selection.

9. Select a component and click OK. The populated Define Applications View dialog displays.

   Figure 3-10 Implement Wizard - Define Application View

   

   Text description of the illustration populateddefineapp.gif

10. Click Next to define the mappings.

    The Define Mappings dialog displays

11. Click New to define mappings and click Finish.

    The new populated event displays in the right panel of iStudio.