Transactions, security, and connection properties for a CICS system

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM Resource Adapters > WOLA resource adapter
Transactions, security, and connection properties for a CICS system

Using WOLA, business processes and services on IBM Process Server for z/OS can call CICS programs.

CICS outbound calling

WOLA is implemented in CICS as a task-related user exit (TRUE) that provides the low-level connection code to cross-memory services. There are two ways of making outbound calls to applications in CICS:

Using the WebSphere supplied link server - You can start the WOLA CICS link server in the CICS region using a WebSphere for z/OS-supplied CICS control transaction (BBOC). The link server accepts program LINK requests from Process Server for z/OS through WOLA and calls the target CICS program using the EXEC CICS LINK API. The link server invocation task can pass a set of parameters to the CICS program in either a COMMAREA or a CHANNEL/CONTAINER. Then the link server invocation task receives the response back and returns the response to the calling program in Process Server for z/OS.
Using the native WOLA APIs - The native APIs Host Service or Receive Request can be used instead of the supplied WOLA link server. These APIs provide enhanced control and performance.

Global transactions using WOLA

The WebSphere optimized local adapter (WOLA) supports global transactions in a two-phase commit process for Process Server for z/OS to CICS program invocations.
When calling into a CICS transaction from Process Server for z/OS using WOLA, an XA-capable transaction context is passed from Process Server for z/OS to CICS.
The WOLA CICS link server that runs in CICS must be started with the TXN=Y parameter so that the link server can read the XA transaction context and create a unit of work to run the specified native language program. When Process Server for z/OS reaches a sync point or a commit point, XA protocol messages are exchanged between Process Server for z/OS and the WOLA link server. The link server drives the appropriate functions in the CICS OTS (OT) domain to complete the unit of work.
To use the global transaction capability when calling into a CICS transaction from Process Server for z/OS, use CICS Transaction Server for z/OS V4.1 or later. How WOLA propagates a transaction context is based on the settings of the WOLA CICS link server that runs inside CICS and the transaction attributes of the process application that runs inside Process Server for z/OS.

CICS security propagation

In CICS transactions, you can propagate the thread level user ID from Process Server for z/OS to CICS using the WOLA CICS link server, but you must start the link server with SEC=Y. When running in this mode, WOLA propagates the identity of the user on the current thread to CICS and the link server invokes a link invocation task using EXEC CICS START TRANSID(‘BBO#') USER(<userid>).
Important: You must ensure that the CICS SURROGAT SAF class is active and that the user ID under which the link server runs has authority to issue START TRANSID for the propagated user ID. Alternatively, when the WOLA CICS link server runs with SEC=NO, all requests that are received in CICS from Process Server for z/OS run under the identity of the link server task, which is the ID of the user that started the link server.
In Process Server for z/OS, you may choose to use the security credentials that are already set on the thread, which by default is the user ID that is running the server, or you can set the credentials using a JAAS alias.

CICS connection properties

When creating the WOLA import and service, you must define the connection properties for the target CICS system.
In the New External Service wizard, on the Security and Configuration Properties page, specify the JNDI name of the connection factory defined on Process Server for z/OS or specify the connection properties for the CICS server that you want to connect to. If you choose to specify the connection properties, then the managed connection factory is created during deployment with the specified properties. In both the cases, a connection property that must be specified for CICS is the target register name.
Important: Define the connection factory on the server for easy changes by the administrator. You can share or reuse the same connection factory among many external services.
If the target program on the CICS system uses CICS containers and can be accessed using WOLA, then in the Security and Configuration Properties page under the CICS connection properties area, you must select CICS connection properties and select Use CICS containers to use CICS containers to communicate with the CICS link server. CICS programs that use containers can pass data that is larger than 32 KB.
To communicate with a COBOL, PL/I, C, or C++ program on a CICS system when using CICS containers, you must set the following properties:

Request container ID - Specifies the name of the container used to pass the request message to a CICS program.
Request container type - Specifies the CICS link request container type. If you select CHAR, the WOLA CICS Link task copies the message into the request container and converts it from code page UTF-8 to IBM-037 (EBCDIC).
If you set the Request container type property to CHAR, then the Code page in the Select Data Structures page must be set to UTF-8 while specifying the target program for the WOLA import.
Response container ID - Specifies the name of the container that receives the response message from a CICS program.
Response container type - Specifies the CICS link response container type. If you select CHAR, the WOLA CICS Link task converts the response message to code page UTF-8 before it returns message to the application server.

Link invocation task transaction ID - Specifies the CICS transaction ID used to run the program link invocation task. The default transaction ID is BBO#.
If the default transaction ID is changed, the CICS system programmer must ensure that the transaction ID is defined properly in the target CICS regions. The transaction ID must be defined with the name of the WOLA CICS link invocation program, which is BBOACLNK.
Important: For CICS programs, you must specify the name of the CICS program to invoke in the InteractionSpec Service name property for the selected operation in the New External Service wizard.