Orbix Mainframe

CICS Adapters Administrator’s

Guide
Version 6.3, July 2009
© 2009 Progress Software Corporation and/or its affiliates or subsidiaries. All rights reserved.
These materials and all Progress® software products are copyrighted and all rights are reserved by Progress
Software Corporation and/or its affiliates or subsidiaries. The information in these materials is subject to change
without notice, and Progress Software Corporation and/or its affiliates or subsidiaries assume no responsibility
for any errors that may appear therein. The references in these materials to specific platforms supported are
subject to change.

Actional, Actional (and design), Allegrix, Allegrix (and design), Apama, Apama (and Design), Artix, Business
Empowerment, DataDirect (and design), DataDirect Connect, DataDirect Connect64, DataDirect Technologies,
DataDirect XML Converters, DataDirect XQuery, DataXtend, Dynamic Routing Architecture, EdgeXtend,
Empowerment Center, Fathom, IntelliStream, IONA, IONA (and design), Mindreef, Neon, Neon New Era of
Networks, ObjectStore, OpenEdge, Orbix, PeerDirect, Persistence, POSSENET, Powered by Progress, PowerTier,
Progress, Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment
Center, Progress Empowerment Program, Progress OpenEdge, Progress Profiles, Progress Results, Progress
Software Developers Network, Progress Sonic, ProVision, PS Select, SequeLink, Shadow, SOAPscope,
SOAPStation, Sonic, Sonic ESB, SonicMQ, Sonic Orchestration Server, Sonic Software (and design),
SonicSynergy, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and Your
Software, Our Technology-Experience the Connection are registered trademarks of Progress Software
Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, Apama
Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, Apama Risk Firewall,
AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward, DataDirect Spy, DataDirect
SupportLink, FUSE, FUSE Mediation Router, FUSE Message Broker, FUSE Services Framework, Future Proof,
GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert, OpenAccess,
Orbacus, Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress
Event Engine, Progress RFID, PSE Pro, SectorAlliance, SeeThinkAct, Shadow z/Services, Shadow z/Direct,
Shadow z/Events, Shadow z/Presentation, Shadow Studio, SmartBrowser, SmartComponent,
SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects,
SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic Business Integration Suite, Sonic Process Manager,
Sonic Collaboration Server, Sonic Continuous Availability Architecture, Sonic Database Service, Sonic
Workbench, Sonic XML Server, StormGlass, The Brains Behind BAM, WebClient, Who Makes Progress, and Your
World. Your SOA. are trademarks or service marks of Progress Software Corporation or one of its affiliates or
subsidiaries in the U.S. and other countries. Java and all Java-based marks are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other trademarks contained herein
are the property of their respective owners.
Third Party Acknowledgments:
1. The Product incorporates IBM-ICU 2.6 (LIC-255) technology from IBM. Such technology is subject to the
following terms and conditions: Copyright (c) 1995-2009 International Business Machines Corporation and
others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the
Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright
notice(s) and this permission notice appear in all copies of the Software and that both the above copyright
notice(s) and this permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS
INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL
DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software without prior written authorization of the copyright
holder. All trademarks and registered trademarks mentioned herein are the property of their respective owners.
2. The Product incorporates IDL Compiler Front End Technology from Sun Microsystems, Inc. Such technology
is subject to the following terms and conditions: Copyright 1992, 1993, 1994 Sun Microsystems, Inc. Printed in
the United States of America. All Rights Reserved. This product is protected by copyright and distributed under
the following license restricting its use. The Interface Definition Language Compiler Front End (CFE) is made
available for your use provided that you include this license and copyright notice on all media and
documentation and the software program in which this product is incorporated in whole or part. You may copy
and extend functionality (but may not remove functionality) of the Interface Definition Language CFE without
charge, but you are not authorized to license or distribute it to anyone else except as part of a product or
program developed by you or with the express written consent of Sun Microsystems, Inc. ("Sun"). The names of
Sun Microsystems, Inc. and any of its subsidiaries or affiliates may not be used in advertising or publicity
pertaining to distribution of Interface Definition Language CFE as permitted herein. This license is effective until
terminated by Sun for failure to comply with this license. Upon termination, you shall destroy or return all code
and documentation for the Interface Definition Language CFE. The Interface Definition Language CFE may not be
exported outside of the United States without first obtaining the appropriate government approvals.
INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING
THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE,
NONINFRINGEMENT, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. INTERFACE
DEFINITION LANGUAGE CFE IS PROVIDED WITH NO SUPPORT AND WITHOUT ANY OBLIGATION ON THE PART OF
SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR
ENHANCEMENT. SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES SHALL HAVE NO LIABILITY WITH RESPECT TO
THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY INTERFACE DEFINITION LANGUAGE
CFE OR ANY PART THEREOF. IN NO EVENT WILL SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES BE LIABLE
FOR ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL DAMAGES, EVEN IF
SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227-19.
Sun, Sun Microsystems and the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc.
SunSoft, Inc. 2550 Garcia Avenue Mountain View, California 94043. NOTE: SunOS, SunSoft, Sun, Solaris, Sun
Microsystems or the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc.

Updated: August 4, 2009

Contents
List of Figures 11

List of Tables 13

Preface 15

Part 1 Introduction
Chapter 1 Introduction to CORBA and Orbix 21
Overview of CORBA 22
Why CORBA? 23
CORBA Objects 25
The ORB 27
CORBA Application Basics 28
Overview of Orbix 31
Simple Orbix Application 32
Broader Orbix Environment 35

Chapter 2 Introduction to the CICS Adapters 37

Overview of the CICS Server Adapter 39
Role of the CICS Server Adapter 40
CICS Server Adapter Processing of IDL Operations 43
The CICS Server Adapter cicsraw Interface 44
Unsupported IDL Types 52
Overview of the Client Adapter 53

5
CONTENTS

Part 2 Configuring the CICS Server Adapter and the Orbix

Runtime in CICS
Chapter 3 Introduction to CICS Server Adapter Configuration 59
A CICS Server Adapter Sample Configuration 60
Configuration Summary of Adapter Plug-Ins 65

Chapter 4 CICS Server Adapter Configuration Details 77

CICS Server Adapter Service Configuration 78

Chapter 5 Configuring the CICS Server Adapter EXCI Plug-In 89

Setting Up EXCI for the CICS Server Adapter 90
Installing Support for IRC for the External Call Interface 91
Installing Sample Orbix CICS Resource Definitions 92
Updating Access Permissions for CICS Resources 93
EXCI Plug-In Configuration Items 94

Chapter 6 Configuring the CICS Server Adapter APPC Plug-In 97

Setting Up APPC for the CICS Server Adapter 98
Defining LUs to APPC 99
Defining an APPC Destination Name for the CICS LU 100
Defining LUs to VTAM 102
Defining the Required Resources to CICS 104
Additional RACF Customization Steps for APPC 105
Bind Time Security with APPC 106
Protecting LUs 108
Link Security & User Security with APPC 109
APPC Plug-In Configuration Items 110

Chapter 7 Configuring the CICS Server Adapter RRS Plug-In 113

Introduction to RRS 114
Setting up RRS for the CICS Server Adapter 115
RRS Plug-In Configuration Items 122

Chapter 8 Configuring the CICS Server Adapter for Client Principals 123

6
 CONTENTS

Activating Client Principal Support 125

Setting up the Required Privileges 129
Additional Requirements for CICS Protocol Plug-Ins 131

Chapter 9 Configuring the Orbix Runtime in CICS 135

Customizing CICS 136
Customizing Orbix Event Logging 138

Chapter 10 IDL Compiler Configuration 141

Orbix IDL Compiler Settings 142

Part 3 Configuring the Client Adapter and the Orbix

Runtime in CICS
Chapter 11 Introduction to Client Adapter Configuration 147
A Client Adapter Sample Configuration 148
Configuration Summary of Client Adapter Plug-Ins 151

Chapter 12 Client Adapter General Configuration 157

Client Adapter Configuration Settings 158

Chapter 13 Configuring the Client Adapter AMTP_APPC Plug-in 161

Setting Up APPC for the Client Adapter 162
Defining LUs to APPC 163
Defining an APPC Destination Name for the Client Adapter 166
Defining LUs to VTAM 170
Defining the Required Resources to CICS 175
Additional RACF Customization Steps for APPC 176
LU-to-LU Security Verification 177
Protecting LUs 179
AMTP_APPC Plug-In Configuration Items 180

Chapter 14 Configuring the Client Adapter AMTP_XMEM Plug-in 183

Prerequisites and Further Reading 184

7
CONTENTS

Running the Client Adapter APF-Authorized 185

Running the Client Adapter in Non-Swappable Address Space 187
Understanding the Impact of Cross Memory Communication 189
AMTP_XMEM Plug-In Configuration Items 191

Chapter 15 Configuring the Client Adapter Subsystem 193

Client Adapter Subsystem Configuration 194

Chapter 16 Configuring the Orbix Runtime in CICS 197

Customizing CICS 198
Customizing Orbix Configuration 200
Customizing Orbix Event Logging 202
Customizing Orbix Maximum Segment Size 204
Customizing Orbix Symbolic Destination 206

Part 4 Securing and Using the CICS Server Adapter

Chapter 17 Securing the CICS Server Adapter 211
Security Configuration Items 212
Common Security Considerations 220
EXCI-Based Security Considerations 222
CICS Security Mechanisms when Using EXCI 223
Orbix CICS Server Adapter Security Modes for EXCI 226
APPC-Based Security Considerations 229
CICS Security Mechanisms when Using APPC 230
Orbix CICS Server Adapter Security Modes for APPC 236

Chapter 18 Mapping IDL Interfaces to CICS 237

The Mapping File 238
Characteristics of the Mapping File 239
Generating a Mapping File 241
Using the IFR as a Source of Type Information 244
Introduction to Using the IFR 245
Registering IDL interfaces with the IFR 247
Informing CICS Server Adapter of a New Interface in the IFR 250
Using an IFR Signature Cache file 252

8
 CONTENTS

Using type_info store as a Source of Type Information 254

Introduction to Using a type_info Store 255
Generating type_info Files using the IDL Compiler 257
Informing CICS Server Adapter of a new type_info Store File 259

Chapter 19 Using the CICS Server Adapter 261

Preparing the Server Adapter 263
Starting the Server Adapter 267
Stopping the CICS Server Adapter 269
Running Multiple Server Adapters Simultaneously 270
Using the MappingGateway Interface 272
Locating CICS Server Adapter Objects Using itmfaloc 275
Adding a Portable Interceptor to the CICS Server Adapter 278
Developing the Portable Interceptor 279
Compiling the Portable Interceptor 284
Loading the Portable Interceptor into the CICS Server Adapter 286
Enabling the GIOP Request Logger Interceptor 289
Gathering Accounting Information in the Server Adapter 291
Customizing the Accounting DLL 292
Compiling the Customized Accounting DLL 296
Activating the Accounting DLL in the Server Adapter 297
Exporting Object References at Runtime 298
Configuration Items for Exporting Object References 299
Exporting Object References to a File 305
Exporting Object References to Naming Service Context 306
Exporting Object References to Naming Service Object Group 308

Part 5 Securing and Using the Client Adapter

Chapter 20 Securing the Client Adapter 315
Security Configuration Items 316
Common Security Considerations 321
APPC Security Considerations 323

Chapter 21 Using the Client Adapter 329

Starting the Client Adapter 330

9
CONTENTS

Stopping the Client Adapter 332

Running Multiple Client Adapters Simultaneously 333
Load Balancing with Multiple Client Adapters 334
Running Two Client Adapters on the Same z/OS Host 336

Part 6 Appendices
Appendix A Troubleshooting 341

Appendix B Glossary of Acronyms 345

Index 349

10
List of Figures
Figure 1: The Nature of Abstract CORBA Objects 25
Figure 2: Role of the ORB in the Basic CORBA Model 27
Figure 3: Invoking on a CORBA Object 29
Figure 4: Overview of a Simple Orbix Application 32
Figure 5: Graphical Overview of the Role of the CICS Server Adapter 41
Figure 6: Graphical Overview of the Role of the Client Adapter 55
Figure 7: CICS Security Mechanisms for EXCI-Based Server Adapter 223
Figure 8: CICS Security Mechanisms for APPC-Based Server Adapter 231
Figure 9: Graphical Overview of a Load Balancing Scenario 334
Figure 10: Running Two Client Adapters on the Same z/OS Host 337

11
LIST OF FIGURES

12
List of Tables
Table 1: Initial and Maximum Log Stream Sizes 117
Table 2: Client Principal Support and cicsa Plug-In Configuration Items 126
Table 3: Event Logging Settings for the CICS Server Adapter 138
Table 4: Server Adapter Mapping Member Configuration Settings 143
Table 5: Client Adapter ORB Names 148
Table 6: S390 Assembler Program Variables and Default Values 201
Table 7: Event Logging Settings for the Client Adapter 202
Table 8: Summary of user IDs used for the CICS Security Checks 227
Table 9: APPC LU Security System Base LU Keyword Definitions 324
Table 10: APPC LU Security Client Adapter LU Keyword Definitions 324
Table 11: Glossary of Acronym Extensions 345

13
LIST OF TABLES

14
 Preface
Orbix is a full implementation from of the Common Object Request Broker
Architecture (CORBA), as specified by the Object Management Group. Orbix
complies with the following specifications:
• CORBA 2.6
• GIOP 1.2 (default), 1.1, and 1.0
Orbix Mainframe is an implementation of the CORBA standard for the z/OS
platform. Orbix Mainframe documentation is periodically updated. New
versions between releases are available at:
http://www.iona.com/support/docs

Audience This guide is intended for CICS system programmers who want to configure,
secure, and use the ClCS server adapter and client adapter that are supplied
with Orbix Mainframe. It is assumed that the reader is familiar with the
basic concepts of CORBA 2.6 and CICS administration.

Related documentation Orbix Mainframe documentation includes the following related guides:
• IMS Adapters Administrator’s Guide
• COBOL Programmer’s Guide and Reference
• PL/I Programmer’s Guide and Reference
• CORBA Programmer’s Guide, C++
• CORBA Programmer’s Reference, C++
• CORBA Administrator’s Guide
• Mainframe Security Guide
• Mainframe Migration and Upgrade Guide

15
PREFACE

• Mainframe Management Guide

• Mainframe CORBA Concepts Guide
• Mainframe OTS Guide
• Artix Transport User’s Guide
The Orbix CICS Adapter Programmer’s Guide, which is based on Orbix
2.3.x rather than Orbix Mainframe 6.x, is also a useful reference. For
migration issues refer to the Mainframe Migration Guide.
For the latest versions of product documentation, see:
http://www.iona.com/support/docs

Organization of this guide This guide is divided into the following parts:

Part 1, “Introduction”
This part introduces Common Object Request Broker Architecture (CORBA),
and Orbix, IONA's implementation of CORBA. It also introduces the CICS
server adapter, which is an Orbix server that can connect with CICS; and the
client adapter, which enables CICS transactions to connect to CORBA
servers running on various platforms.

Part 2, “Configuring the CICS Server Adapter and the Orbix Runtime in
CICS”
This part describes how to configure the CICS server adapter and the Orbix
runtime inside CICS.

Part 3, “Configuring the Client Adapter and the Orbix Runtime in CICS”
This part describes how to configure the Orbix Mainframe client adapter and
the Orbix runtime inside CICS.

Part 4, “Securing and Using the CICS Server Adapter”

This part explains security considerations for the CICS server adapter, and
how the server adapter can be used as a bridge between CORBA based
messages and CICS programs. It also describes how IDL operation
signatures are mapped using the CICS server adapter to CICS.

Part 5, “Securing and Using the Client Adapter”

This part explains security considerations for the client adapter, and how the
client adapter can be used as a bridge between CORBA based messages
and CICS programs.

16
 PREFACE

Appendix A, “Troubleshooting”
This chapter provides an overview of the MCLOOKUP utility that can be used
for troubleshooting.

Appendix B, “Glossary of Acronyms”

This glossary provides an expansion for each of the acronyms used in this
guide.

Additional resources The Knowledge Base contains helpful articles, written by experts, about
Orbix Mainframe, and other products:
http://www.iona.com/support/kb/
If you need help with Orbix Mainframe or any other products, contact
technical support:
http://www.progress.com/support

Typographical conventions This guide uses the following typographical conventions:

Constant width Constant width (courier font) in normal text represents
portions of code, and literal names of items such as
classes, functions, variables, and data structures. For
example, text might refer to the CORBA::Object class.
Constant width paragraphs represent code examples
or information a system displays on the screen. For
example:
#include <stdio.h>
Italic Italic words in normal text represent emphasis and
new terms.
Code italic Italic words or characters in code and commands
represent variable values that you must supply; for
example:
install-dir/etc/domains
Code Bold Code bold is used to highlight a piece of code within a
particular code sample.

17
PREFACE

Keying conventions This guide might use the following keying conventions:

No prompt When a command’s format is the same for multiple

platforms, a prompt is not used.
% A percent sign represents the UNIX command shell
prompt for a command that does not require root
privileges.
$ A dollar sign represents the z/OS UNIX System
Services command shell prompt for a command that
does not require root privileges.
# A number sign represents the UNIX command shell
prompt for a command that requires root privileges.
... Horizontal or vertical ellipses in format and syntax
. descriptions indicate that material has been
. eliminated to simplify a discussion.
.
[] Brackets enclose optional items in format and syntax
descriptions.
{} Braces enclose a list from which you must choose an
item in format and syntax descriptions.

18
 Part 1
Introduction
In This part This part contains the following chapters:

Introduction to CORBA and Orbix page 21

Introduction to the CICS Adapters page 37

 CHAPTER 1

Introduction to
CORBA and Orbix
The Common Object Request Broker Architecture (CORBA)
standard is specified by the Object Management Group (OMG)
and provides the foundation for flexible and open systems. It
underlies some of the Internet’s most successful e-business
sites, and some of the world’s most complex and demanding
enterprise information systems. Orbix is a full implementation
of the CORBA standard. Orbix Mainframe is an
implementation of CORBA for the z/OS platform. This chapter
provides an introductory overview of both CORBA and Orbix.

In this chapter This chapter discusses the following topics:

Overview of CORBA page 22

Overview of Orbix page 31

21
CHAPTER 1 | Introduction to CORBA and Orbix

Overview of CORBA
Overview The Common Object Request Broker Architecture (CORBA) provides the
foundation for flexible and open systems. It underlies some of the Internet’s
most successful e-business sites and some of the world’s most complex and
demanding enterprise information systems. This section provides an
overview of CORBA in terms of the enterprise information solutions that it
provides and the basic principles on which it is based.

In this section This section discusses the following topics:

Why CORBA? page 23

CORBA Objects page 25

The ORB page 27

CORBA Application Basics page 28

22
 Overview of CORBA

Why CORBA?
Overview CORBA is a standard middleware architecture that can be used to develop
and integrate a wide variety of distributed systems that use a variety of
hardware, operating systems, and programming languages.
This subsection discusses the following topics:
• Need for open systems
• Need for high-performance systems
• Open standard solution
• Widely available solution

Need for open systems Today’s enterprises need flexible, open information systems. Most
enterprises must cope with a wide range of technologies, operating systems,
hardware platforms, and programming languages that need to work together
to make the enterprise function.

Need for high-performance Orbix is a CORBA development platform for building high-performance
systems systems. Its modular architecture supports the most demanding needs for
scalability, performance, and deployment flexibility. The Orbix architecture
is also language-independent, so you can implement Orbix applications in
COBOL, PL/I, C++, or Java that interoperate, via the standard IIOP
protocol, with applications built on any CORBA-compliant technology.

Open standard solution CORBA is an open, standard solution for distributed object systems. You can
use CORBA to describe your enterprise system in object-oriented terms,
regardless of the platforms and technologies used to implement its different
parts. CORBA objects communicate directly across a network, using
standard protocols, regardless of the programming languages used to create
objects or the operating systems and platforms on which the objects run.

23
CHAPTER 1 | Introduction to CORBA and Orbix

Widely available solution CORBA solutions are available for every common environment and are used
to integrate applications written in C, C++, Java, Ada, Smalltalk, COBOL,
and PL/I, COM, LISP, Python, and XML, running on embedded systems,
PCs, UNIX hosts, and mainframes. CORBA objects running in these
environments can cooperate seamlessly. Through COMet, IONA’s dynamic
bridge between CORBA and COM, they can also interoperate with COM
objects. CORBA offers an extensive infrastructure that supports all the
features required by distributed business objects. This infrastructure
includes important distributed services, such as transactions, messaging,
and security.

24
 Overview of CORBA

CORBA Objects
Overview This subsection describes the most basic components of a CORBA system.
It discusses the following topics:
• Nature of abstract CORBA objects
• Object references
• IDL interfaces
• Advantages of IDL

Nature of abstract CORBA objects A CORBA system provides distributed object capability between applications
in a network. A client in a CORBA system is any program that invokes the
services (or functions) of a CORBA object. A server in a CORBA system is
any program that contains instances of CORBA objects.
CORBA objects are abstract objects in a CORBA system that provide
distributed object capability between applications in a network. Figure 1
shows that any part of a CORBA system can refer to the abstract CORBA
object, but the object is only implemented in one place and time on some
server within the system.

A server
implements a
CORBA object
Clients access
CORBA objects
via object
references

IDL interface definitions

specify CORBA objects

Figure 1: The Nature of Abstract CORBA Objects

25
CHAPTER 1 | Introduction to CORBA and Orbix

Object references An object reference is used to identify, locate, and address a CORBA object.
Clients use an object reference to invoke requests on a CORBA object.
CORBA objects can be implemented by servers in any supported
programming language, such as COBOL, PL/I, C++, or Java.
For integration with existing transactions in CICS, you can:
• Use the Orbix CICS server adapter to receive CORBA client requests
and translate them to program invocations in CICS.
• Use the Orbix CICS client adapter to allow transactions in CICS to
initiate CORBA client requests to servers running outside of CICS.

IDL interfaces Although CORBA objects are implemented using standard programming
languages, each CORBA object has a clearly-defined interface, specified in
the CORBA Interface Definition Language (IDL). The interface definition
specifies which operations (member functions), data types, attributes, and
exceptions are available to a client, without making any assumptions about
an object’s implementation. Not all IDL data types are supported by the
CICS server and client adapters. Refer to “Unsupported IDL Types” on
page 52 for more information.

Advantages of IDL With a few calls to an Object Request Broker’s (ORB’s) application
programming interface (API), servers can make CORBA objects available to
client programs in your network.
To call member functions on a CORBA object, a client programmer needs
only to refer to the object’s interface definition. Clients use their normal
programming language syntax to call the member functions of a CORBA
object. A client does not need to know which programming language
implements the object, the object’s location on the network, or the operating
system in which the object exists.
Using an IDL interface to separate an object’s use from its implementation
has several advantages. For example, you can change the programming
language in which an object is implemented without affecting the clients
that access the object. You can also make existing objects available across a
network.

26
 Overview of CORBA

The ORB
Overview CORBA defines a standard architecture for object request brokers (ORBs).
An ORB is a software component that mediates the transfer of messages
from a program to an object located on a remote network host. The ORB
hides the underlying complexity of network communications from the
programmer.
This subsection discusses the following topics:
• Role of an ORB
• Graphical overview

Role of an ORB An ORB lets you create standard software objects whose member functions
can be invoked by client programs located anywhere in your network. A
program that contains instances of CORBA objects is often known as a
server. However, the same program can serve at different times as a client
and a server. For example, a server program might itself invoke calls on
other server programs, and so relate to them as a client.

Graphical overview When a client invokes a member function on a CORBA object, the ORB
intercepts the function call. As shown in Figure 2, the ORB redirects the
function call across the network to the target object. The ORB then collects
results from the function call and returns these to the client.

Client H ost Ser ver H ost

Server
O bject
Client

O bject Request Broker

Funct ion
Call

Figure 2: Role of the ORB in the Basic CORBA Model

27
CHAPTER 1 | Introduction to CORBA and Orbix

CORBA Application Basics

Overview This subsection describes the basics of how CORBA applications work. It
discusses the following topics:
• Developing application interfaces
• Client invocations on CORBA objects
• IDL operation parameters
• Parameter-passing mode qualifiers

Developing application interfaces The first step in developing a CORBA application is to define interfaces to
objects in your system, in CORBA IDL. Then compile these interfaces with
an IDL compiler. An IDL compiler can generate COBOL, PL/I, C++ or Java
from IDL definitions. The generated code includes client stub code
(excluding COBOL and PL/I), which you use to develop client programs; and
object skeleton code, which you use to implement CORBA objects in server
programs.

Note: With Orbix Mainframe, you can use the IDL compiler to generate
only COBOL or PL/I server skeleton code from IDL definitions. The IDL
compiler does not generate COBOL or PL/I client stub code.

Your installation of the CICS server adapter includes a server application

that runs on z/OS and acts as the CORBA gateway to the CICS system Your
installation of the CICS client adapter includes a client application that runs
on z/OS and acts as the CORBA gateway outbound from the CICS system.
Sample demonstrations are provided with both the CICS server and client
adapter installation programs. These demonstrations are located in the
orbixhlq.DEMO.CICS.** PDS range. Samples of both COBOL and PL/I CICS
servers and clients are provided. For more details about the COBOL
demonstrations, see the sections in the COBOL Programmer’s Guide and
Reference on developing a CICS server and a CICS client. For more details
about the PL/I demonstrations, see the sections in the PL/I Programmer’s
Guide and Reference on developing a CICS server and a CICS client.

28
 Overview of CORBA

Client invocations on CORBA When a client wants to invoke operations on a CORBA object, it invokes on
objects an object reference that it obtains from the server process. As shown in
Figure 3 on page 29, a client call is transferred through the client stub code
to the ORB. The ORB then passes the function call through the object
skeleton code to the target object. Because the implemented object is not
located in the client’s address space, CORBA objects are represented in
client code by proxy objects.

Client H ost Server H ost

O bject
Client

Client O bject
Stub Skeleton
Code Code

Function O bject Request Broker

Call

Figure 3: Invoking on a CORBA Object

IDL operation parameters Each parameter specifies the direction in which its arguments are passed
between client and object. Parameter-passing modes clarify operation
definitions and allow the IDL compiler to accurately map operations to a
target programming language. The Orbix CICS runtime uses
parameter-passing modes to determine in which direction (or directions) it
must marshal a parameter.

Parameter-passing mode There are three parameter-passing mode qualifiers:

qualifiers
in This means that the parameter is initialized only by the client and
is passed to the object.

29
CHAPTER 1 | Introduction to CORBA and Orbix

out This means that the parameter is initialized only by the object and
is passed to the client.
inout This means that the parameter is initialized by the client and
passed to the server; the server can modify the value before
returning it to the client

30
 Overview of Orbix

Overview of Orbix
Overview Orbix is IONA’s implementation of the CORBA standard. This section
provides an example of a simple Orbix application and an introduction to the
broader Orbix environment.

In this section This section discusses the following topics:

Simple Orbix Application page 32

Broader Orbix Environment page 35

31
CHAPTER 1 | Introduction to CORBA and Orbix

Simple Orbix Application

Overview A simple Orbix application might contain a client and a server along with
one or more objects (see Figure 4). In this model, the client obtains
information about the object it seeks, using object references. An object
reference uniquely identifies a local or remote object instance.
This subsection discusses the following topics:
• Graphical overview
• Explanation of simple application
• Portable object adapter
• Limitations of a simple application

Graphical overview Figure 4 provides a graphical overview of a simple Orbix application.

Client Host Server Host

Object
Client
2 Naming 1
Service
ORB ORB

3
Network

Figure 4: Overview of a Simple Orbix Application

32
 Overview of Orbix

Explanation of simple application Figure 4 on page 32 shows how an ORB enables a client to invoke on a
remote object:

Step Action

1 When a server starts, it creates one or more objects and

publishes their object references in a naming service. A naming
service uses simple names to make object references
accessible to prospective clients. Servers can also publish
object references to a file or as a URL.

2 The client program looks up the object reference by name in

the naming service. The naming service returns the server’s
object reference.

3 The client ORB uses the object reference to pass a request to

the server object.

Portable object adapter For simplicity, Figure 4 on page 32 omits details that all applications
require. For example, Orbix applications use a Portable Object Adapter
(POA), to manage access to server objects. A POA maps object references to
their concrete implementations on the server. Given a client request for an
object, a POA can invoke the referenced object locally.
The client request embeds the POA name and object ID taken from the
published object reference. The server then uses the POA name to invoke
the POA. The POA uses the object ID to invoke the desired object, if it exists
on the server.
Refer to either the COBOL Programmer’s Guide and Reference or the PL/I
Programmer’s Guide and Reference for details about the Orbix Mainframe
POA.

Limitations of a simple application This simple model uses a naming service to pass object references to
clients. The naming service has some limitations and does not support all
the needs of enterprise-level applications. For example, naming services are
often not designed to handle frequent updates. They are designed to store
relatively stable information that is not expected to change very often. If a
process stops and restarts frequently, a new object reference must be
published with each restart. In production environments where many

33
CHAPTER 1 | Introduction to CORBA and Orbix

servers start and stop frequently, this can overwork a naming service.
Enterprise applications also have other needs that are not met by this simple
model—for example, on-demand activation, and centralized administration.
These needs are met in a broader Orbix environment, as described in
“Broader Orbix Environment” on page 35.

34
 Overview of Orbix

Broader Orbix Environment

Overview Along with the naming service, Orbix offers a number of features that are
required by many distributed applications, for flexibility, scalability, and
ease of use. This subsection provides an overview of those features. It
discusses the following topics:
• Location domains
• Managing object availability
• Configuration domains
• Interface Repository

Location domains Location domains enable a server and its objects to move to a new process
or host, and to be activated on demand. An Orbix location domain consists
of two components—a locator daemon and a node daemon:
• locator daemon—This is a CORBA service that acts as the control
center for the entire location domain. The locator daemon has two
roles:
♦ Manage the configuration information used to find, validate, and
activate servers running in the location domain.
♦ Act as the contact point for clients trying to invoke on servers in
the domain.
• node daemon—This acts as the control point for a single host machine
in the system. Every machine that runs an application server must run
a node daemon. The node daemon starts, monitors, and manages
application servers on its machine. The locator daemon relies on node
daemons to start processes and tell it when new processes are
available.

35
CHAPTER 1 | Introduction to CORBA and Orbix

Managing object availability A server makes itself available to clients by publishing Interoperable Object
References (IORs). An IOR contains an object's identity and address. Refer
to “Sample configuration file” on page 265 for an example of an IOR.
When a client invokes on an object, Orbix locates the object as follows:
1. The ORB sends the invocation to the locator daemon.
2. The locator daemon searches the implementation repository for the
actual address of a server that runs this object.
3. The locator daemon returns this address to the client.
4. The client connects to the returned server address and directs this and
all subsequent requests for this object to that address.

Configuration domains Configuration domains allows you to organize ORBs into independently
manageable groups. This brings scalability and ease of use to the largest
environments.

Interface Repository The Interface Repository (IFR) provides a source of type information, and
allows clients to discover and use additional objects in the environment—
even if clients do not know about these objects at compile time. Orbix
Mainframe also supplies an alternative to using the IFR; refer to “Using
type_info store as a Source of Type Information” on page 254 for more
information.

36
 CHAPTER 2

Introduction to the
CICS Adapters
The Orbix Mainframe CICS server adapter provides a simple
way to integrate distributed CORBA and EJB clients on various
platforms with existing and new CICS transactions running on
z/OS. It allows you to develop and deploy Orbix COBOL and
Orbix PL/I servers in CICS, and to integrate these CICS servers
with distributed CORBA clients running on various platforms.
It also facilitates the integration of existing CICS transactions,
not developed using Orbix, with distributed CORBA clients,
without the need for code changes to these existing
transactions. The CICS server adapter itself can execute in a
native z/OS or UNIX System Services address space.
The Orbix Mainframe client adapter provides a simple way for
CICS transactions to act as clients of distributed CORBA
servers on various platforms. It allows you to develop and
deploy Orbix COBOL and Orbix PL/I clients in CICS. The client
adapter itself can execute in a native z/OS or UNIX Systems
Services address space
This chapter provides an introductory overview of both the CICS
server adapter and the client adapter that are supplied with
Orbix Mainframe.

37
CHAPTER 2 | Introduction to the CICS Adapters

In this chapter This chapter discusses the following topics:

Overview of the CICS Server Adapter page 39

Overview of the Client Adapter page 53

38
 Overview of the CICS Server Adapter

Overview of the CICS Server Adapter

Overview The CICS server adapter is an Orbix service that can be deployed in either a
native z/OS or UNIX System Services environment. Its function is to
integrate distributed CORBA or EJB clients (or both) running on various
platforms with existing or new CICS applications (or both) running on z/OS.

In this section This section discusses the following topics:

Role of the CICS Server Adapter page 40

CICS Server Adapter Processing of IDL Operations page 43

The CICS Server Adapter cicsraw Interface page 44

Unsupported IDL Types page 52

39
CHAPTER 2 | Introduction to the CICS Adapters

Role of the CICS Server Adapter

Overview The CICS server adapter acts as a bridge between CORBA/EJB clients and
CICS servers. It allows you to set up a distributed system that combines the
powerful online transaction processing capabilities of CICS with the
consistent and well-defined structure of a CORBA environment.
This subsection discusses the following topics:
• Characteristics of the CICS server adapter
• CICS server adapter functions
• Graphical overview
• Graphical overview explanation

Characteristics of the CICS server The CICS server adapter has the following characteristics:
adapter • It is a fully dynamic bridge, because the interfaces that it provides to
CORBA clients can be changed at runtime.
• It is an Orbix server that is used to allow CICS transactions to process
IDL-defined operations. Refer to “CICS Server Adapter Processing of
IDL Operations” on page 43 for more details.
• It implements the cicsraw IDL interface. Refer to “The CICS Server
Adapter cicsraw Interface” on page 44 for more details.

CICS server adapter functions The CICS server adapter performs the following functions:
1. It accepts an IDL request or an input COMMAREA from the client.
2. It provides accepted IDL requests or an input COMMAREA to CICS.
3. It runs the CICS program. If it is an IDL-based request, the server
adapter marshals the operation parameters for the implementation
server program in CICS, performing any necessary data conversion;
otherwise, it simply runs the requested program with the supplied
input COMMAREA.
4. In the same way, it receives the results from CICS and returns them to
the client.

40
 Overview of the CICS Server Adapter

Graphical overview Figure 5 provides a graphical overview of the role of the CICS server
adapter.

Windows Solaris Java

NT Client Client Client

IIOP
IIOP IIOP
over
over over
TCP/IP
TCP/IP TCP/IP

z/OS
(native or UNIX Orbix
System Services)
IIOP
Daemon

Orbix CICS File read Mapping

Server Adapter Repository
IIOP or
File rea
d
Type
EXCI or Information
APPC
using EXCI Repository
cicsraw or
APPC

CICS
COBOL
runtime
Existing New
or
Program Program PL/I
runtime

Figure 5: Graphical Overview of the Role of the CICS Server Adapter

41
CHAPTER 2 | Introduction to the CICS Adapters

Graphical overview explanation Figure 5 on page 41 provides an overview of the role of the CICS server
adapter in integrating distributed CORBA or EJB clients (or both) on
different platforms with CICS transactions running on z/OS. The CORBA or
EJB clients can be written in languages such as C++ or Java.
The CICS server adapter communicates with CICS using either IBM’s
External CICS Interface (EXCI) or Advanced Program to Program
Communications (APPC) protocol. A 32K data limit applies when using
EXCI, but does not apply when using APPC. As discussed, the CICS server
adapter acts as a bridge between CORBA/EJB clients that can be running on
various platforms and servers that are running in CICS.

42
 Overview of the CICS Server Adapter

CICS Server Adapter Processing of IDL Operations

Overview The CICS server adapter is an Orbix server that allows CICS programs to
process IDL-defined operations. When the server adapter receives a request
from a CORBA/EJB client, it looks up the appropriate CICS program name,
based on the requested interface and operation name. The server adapter
then marshals incoming data and submits the request to CICS with that
program name. When the CICS program receives control via the normal
CICS dispatching process, it uses the set of Orbix-provided services to read
in the operation’s parameters and marshal the return data, and returns the
result to the client.
This subsection discusses the following topics:
• List of required IDL interfaces
• CICS server adapter type information

List of required IDL interfaces The list of interfaces that the CICS server adapter needs to provide to its
clients is provided to the server adapter in the form of a mapping file. Refer
to “The Mapping File” on page 238 for more details.

CICS server adapter type The CICS server adapter obtains IDL interface information (operation
information signatures) from either the IFR or from a type_info store, depending on the
configuration values used. This enables the server adapter to unmarshal the
data received from client programs and marshal the response back to the
client. (Marshalling is the process whereby the communicated data is
converted to a byte stream, so that it can be sent between the client and the
server).
The exact manner in which information is loaded depends on the type
information mechanism employed (that is, IFR or type_info store). Refer to
“Mapping IDL Interfaces to CICS” on page 237 for more information on
these mechanisms.

43
CHAPTER 2 | Introduction to the CICS Adapters

The CICS Server Adapter cicsraw Interface

Overview This subsection provides an introductory overview of the cicsraw IDL
interface, which the CICS server adapter implements. It discusses the
following topics:
• What is the cicsraw interface?
• EXCI versus APPC
• Definition of the cicsraw IDL.
• Explanation of the cicsraw IDL.
• Demonstration of the cicsraw interface

What is the cicsraw interface? The CICS server adapter exposes a CORBA IDL interface, called cicsraw, to
its clients. The cicsraw IDL interface defines operations to:
• Specify a CICS program name and an input COMMAREA.
• Run the program in CICS.
• Receive the resulting output COMMAREA.

Note: If you used the previous versions of the CICS server adapter, the
cicsraw IDL interface has been modified to scope the cicsraw interface
inside a module called IT_MFA_CICS. However, to maintain backwards
compatibility with older client applications, the CICS server adapter can be
configured to expose the legacy unscoped cicsraw API (see the Mainframe
Migration and Upgrade Guide for more details). Also, as stated in the IDL
of previous adapter versions, the do_trans() operation has been removed.

EXCI versus APPC The cicraw interface is only supported by server adapters that are
communicating with CICS over EXCI. It is not supported by server adapters
that are communicating with CICS over APPC. In CICS, the called program
is responsible for conversation handling (unlike in IMS, where the IMS
system is responsible for conversation handling and simply passes the
segments to the called transaction). Therefore, when communicating with
CICS over APPC, you can only call a program that has been coded to be the
other partner in an APPC conversation, rather than a program that takes a
COMMAREA as input.

44
 Overview of the CICS Server Adapter

Definition of the cicsraw IDL The following shows the IDL definitions contained within the cicsraw IDL
interface:

Example 1: The cicsraw IDL Interface (Sheet 1 of 3)

//IDL
1 #pragma prefix "iona.com"

2 module IT_MFA_CICS
{
interface cicsraw {
3 typedef string<8> programName;
typedef sequence<char> CharBuffer;
typedef sequence<octet> ByteBuffer;
typedef string<4> CICSabend;
typedef char transid[4];

4 exception CICSunavailable
{
string reason;
};
exception unknownProgramName {};
exception commareaTooLarge {};
exception userNotAuthorized
{
string reason;
};
exception programFailed
{
unsigned long eibresp;
unsigned long eibresp2;
CICSabend abendCode;
};
exception internalError
{
string reason;
};

//
// Methods for invoking CICS server programs.
// The first uses CharBuffer, so data is subject
// to ASCII-EBCDIC conversion cross-platforms, the
// second uses a ByteBuffer so no conversion will be
// done.
//
5 void run_program(

45
CHAPTER 2 | Introduction to the CICS Adapters

Example 1: The cicsraw IDL Interface (Sheet 2 of 3)

in programName program_name,
inout CharBuffer commarea)
) raises (
commareaTooLarge,
CICSunavailable,
unknownProgramName,
userNotAuthorized,
programFailed,
internalError
};

5 void run_program_binary{
in programName program_name,
inout ByteBuffer commarea
) raises (
commareaTooLarge,
CICSunavailable,
unknownProgramName,
userNotAuthorized,
programFailed,
internalError
);

//
// Methods for invoking CICS server programs with the
// mirror transaction name specified.
//
// This is for the EXCI based CICS adapter only.
//
// The first uses a CharBuffer, so data is subject
// to ASCII-EBCDIC conversion cross-platforms, the
// second uses a ByteBuffer so no conversion will be
// done.
//
6 void run_program_with_tran(
in programName program_name,
in transid transaction_id,
inout CharBuffer commarea
) raises(
commareaTooLarge,
CICSunavailable,
unknownProgramName,
userNotAuthorized,
programFailed,
internalError

46
 Overview of the CICS Server Adapter

Example 1: The cicsraw IDL Interface (Sheet 3 of 3)

};

6 void run_program_binary_with_tran{
in programName program_name,
in transid transaction_id,
inout ByteBuffer commarea
) raises (
commareaTooLarge,
CICSunavailable,
unknownProgramName
userNotAuthorized,
programFailed,
internalError
};

7 readonly attribute unsigned long maxCommareaSize;

};
};

Explanation of the cicsraw IDL The cicsraw interface can be explained as follows:
1. This pragma prefix indicates that the IDL was developed by IONA.
2. The cicsraw interface is within the IT_MFA_CICS module scope. The
IT_ prefix is a naming convention that is used to signify IDL modules
developed by IONA. This helps to avoid naming clashes in the global
scope.
3. It defines five data types:
♦ programName, which is a bounded string of up to eight characters.
♦ CharBuffer, which is a sequence of char types.
♦ ByteBuffer, which is a sequence of octet types.
♦ CICSabend, which is a bounded string of up to four characters.
♦ transid, which is a bounded string of up to four characters.

47
CHAPTER 2 | Introduction to the CICS Adapters

4. It defines a series of exceptions that can be used to describe errors that

might occur when running a CICS program. Any such errors are
returned to the client, using this series of exceptions. This means that a
client program can catch and handle any errors that might be used for
diagnostic purposes or for which a useful response is possible. See
“Exception information for APPC” on page 50 and “Exception
information for EXCI” on page 51 for more details of these exceptions.
5. It defines operations called run_program() and
run_program_binary(). These operations are similar in that:
♦ They are both provided for passing COMMAREA data to a CICS
program.
♦ They both take an in parameter called program_name, and an
inout parameter called commarea. The program_name parameter
specifies the CICS program that the client wants to invoke. The
commarea parameter is used by the client to pass the COMMAREA
data to the CICS program. The commarea parameter is also used
by the CICS server adapter, to pass the processed data from the
CICS program back to the client.
The two operations differ in the type of the commarea parameter, as
follows:
♦ The commarea parameter for run_program() is of the CharBuffer
type. This means that the CICS server adapter performs
ASCII-to-EBCDIC translations when it is sending the buffer that
contains the COMMAREA across different platforms. However, if
the client input is a mixture of character and numeric data, the
numeric data might be corrupted by the ASCII-to-EBCDIC
conversion process, and the CICS program is then unable to
process the inputs. The easiest solution in this case is to have the
CICS program receive all its input in character format, and to
have the CICS server adapter use the run_program() operation to
convert the data to EBCDIC format before supplying it to CICS.

48
 Overview of the CICS Server Adapter

♦ The commarea parameter for run_program_binary() is of the

ByteBuffer type. This means that the data passed from a
non-EBCDIC platform to z/OS is not converted. In such cases,
where the COMMAREA contains a mixture of character and
non-character data, there are two possible solutions. The first
solution is to have the client call run_program_binary and
translate all the character data to EBCDIC. (However, this
translation is awkward and is not portable across different client
platforms.) The second solution is to modify the CICS program, so
that it only accepts character input.
6. It defines operations called run_program_with_tran() and
run_program_binary_with_tran(). These operations are similar to
run_program() and run_program_binary(). The only difference is that
they also have an extra in parameter called transaction_id, which
allows for the mirror transaction to be specified. The run_program()
and run_program_binary() operations pick up a default mirror
transaction specified in the configuration domain.
7. The readonly attribute, maxCommareaSize, allows the client to retrieve
the maximum COMMAREA length for which the CICS server adapter
was configured when it was started. Because this is a readonly
attribute, clients can read its value, but they cannot set it.
As long as your CICS program uses a COMMAREA for all input and
output, no changes are required to it.

49
CHAPTER 2 | Introduction to the CICS Adapters

Exception information for APPC For APPC, the exception information that can be raised by the cicsraw
interface can be explained as follows:
• reason
The reason string is usually created from a call to ATBEES3(), with
some other available information, such as the return code from the
ATBxxx call, added where applicable. For failures that do not involve
APPC, a reason string is generated by the adapter to describe the
failure.
• exception CICSunavailable { string reason; };
A CICSunavailable exception is thrown when ATBALC5() fails with
k_badDestname, k_remoteLUnotActive, or k_remoteLUnotActive2.
• exception unknownTransactionName {};
An unknownTransactionName exception is thrown when ATBSEND(),
ATBRCVW(), or ATBDEAL() fails with CM_TPN_NOT_RECOGNIZED.
• exception segmentTooLarge {};
A segmentTooLarge exception is thrown if one of the input segments
exceeds the maximum length specified for segments in the adapter
configuration file.
• exception userNotAuthorized { string reason; };
A userNotAuthorized exception is thrown when ATBSEND(),
ATBRCVW(), or ATBDEAL() fails with CM_SECURITY_NOT_VALID. It can
also be thrown if the plugins:cicsa:use_client_principal
configuration item is set to yes but the principal received does not look
like a valid RACF user ID.
• exception transactionFailed { string reason; };
A transactionFailed exception is thrown when ATBSEND() fails with
CM_PROGRAM_ERROR_NO_TRUNC.
• exception internalError { string reason; };
An internalError exception is thrown for all other failures. Refer to
the adapter event log output for more details on what caused a specific
exception.

50
 Overview of the CICS Server Adapter

Exception information for EXCI For EXCI, the exception information that can be raised by the cicsraw
interface can be explained as follows:
• exception CICSunavailable
A CICSunavailable exception is thrown when EXCI returns
NO_CICS_IRC_STARTED, NO_PIPE, or NO_CICS reason codes. It can also
be thrown for a reason code of IRC_CONNECT_FAILURE with a subreason
of IRERRNSS or -1.
• exception unknownProgramName
An unknownProgramName exception is thrown if the program name is
more than eight characters in length. It can also be returned if CICS
returns a DPL response code of EXEC_PGMIDERR.
• exception commareaTooLarge
A commareaTooLarge exception is thrown if the commarea received from
the client application is either larger than the limit specified in the
adapter configuration file or larger than 32K.
• exception userNotAuthorized
A userNotAuthorized exception is thrown if the adapter is configured
to use client principals for calls to CICS, but the received principal is
malformed. It can also be thrown for a reason code of
IRC_CONNECT_FAILURE with a subreason of IRERRSCF.
• exception programFailed
A programFailed exception is thrown for any error, except
EXEC_PGMIDERR, that is returned by DPL on the EXCI DPL_request call.
• exception interalError
An internalError exception is thrown for all other failures. Refer to
the adapter event log output for more details on what caused a specific
exception. This includes errors that are caused by the CICS adapter
being configured to use the client principal, but not subsequently being
able to log onto CICS with the principal provided by the client.

Demonstration of the cicsraw A C++ demonstration client for the cicsraw interface is supplied with the
interface other C++ demonstrations in your Orbix Mainframe installation. Follow the
instructions in the supplied readme to run the client application.

51
CHAPTER 2 | Introduction to the CICS Adapters

Unsupported IDL Types

Overview This section provides an overview of the IDL types that the CICS server
adapter does not support.

Unsupported types The following IDL types are not currently supported by the CICS server
adapter:
• Object references.
• Value types, and other Pseudo-object types.
• wchar and wstring
Refer to the COBOL Programmer's Guide and Reference and the PL/I
Programmer's Guide and Reference for details.

52
 Overview of the Client Adapter

Overview of the Client Adapter

Overview The Orbix Mainframe client adapter is an Orbix service that can be deployed
in a native z/OS or UNIX System Services environment. Its function is to
allow CICS transactions to act as clients of CORBA servers running on
various platforms.
The client adapter acts as a bridge between CICS client transactions and
CORBA servers. The client adapter allows you to set up a distributed system
that combines the powerful online transaction processing capabilities of
CICS with the consistent and well-defined structure of a CORBA
environment.
This section discusses the following topics:
• Characteristics of the client adapter
• Client adapter functions
• Graphical overview

Characteristics of the client The client adapter has the following characteristics:
adapter • It is a mirror implementation of the CICS server adapter in that it
adapts CORBA requests that originate in CICS, whereas the CICS
server adapter adapts CORBA requests destined for CICS. Figure 6 on
page 55 provides an overview of the role of the client adapter in
integrating CICS client transactions with distributed CORBA servers on
different platforms.
• It uses APPC or cross memory to communicate with CICS.
• It implements the CORBA invocation facility using the Orbix Dynamic
Invocation Interface (DII), and uses the IFR server or a type_info store
to obtain type information. Refer to the CORBA Programmer’s Guide,
C++ for more information on the DII.

53
CHAPTER 2 | Introduction to the CICS Adapters

• It provides an optional caching feature to improve performance. It can

cache target object references and type information for operations.
• It is a multi-threaded application that can service multiple concurrent
client requests.
• It can service multiple CICS regions.
• It supports two-phase commit processing initiated from CICS
transactions when using APPC communication.

Client adapter functions The client adapter performs the following functions:
• It accepts a request from a CICS client transaction.
• It locates the target CORBA object and invokes the requested
operation.
• It returns the CORBA object reply to the CICS client transaction.

Graphical overview Figure 6 on page 55 provides a graphical overview of the role of the client
adapter. It shows the role of the client adapter in integrating distributed
CORBA servers on different platforms with CICS client transactions running
on z/OS.
The CICS client transactions can be written in COBOL or PL/I. The clients
make a call to the COBOL or PL/I runtime that identifies both the target
object and the operation to perform, and supplies in, inout, and out
parameters. The COBOL or PL/I runtime uses the APPC protocol or cross
memory to communicate with the client adapter, and passes the client
request to it. The client adapter locates the target server object and invokes
the requested operation. The results are then returned back to the CICS
client transaction. A CICS client transaction can process requests to servers
using two-phase commit processing when using APPC for communication.

54
 Overview of the Client Adapter

Figure 6: Graphical Overview of the Role of the Client Adapter

55
CHAPTER 2 | Introduction to the CICS Adapters

56
 Part 2
Configuring the CICS Server
Adapter and the Orbix
Runtime in CICS
In this part This part contains the following chapters:

Introduction to CICS Server Adapter Configuration page 59

CICS Server Adapter Configuration Details page 77

Configuring the CICS Server Adapter EXCI Plug-In page 89

Configuring the CICS Server Adapter APPC Plug-In page 97

Configuring the CICS Server Adapter RRS Plug-In page 113

Configuring the CICS Server Adapter for Client Principals page 123

Configuring the Orbix Runtime in CICS page 135

IDL Compiler Configuration page 141

 CHAPTER 3

Introduction to
CICS Server
Adapter
Configuration
This chapter provides information needed to configure the
CICS server adapter and its components (plug-ins). It provides
descriptions of all the configuration items involved in running
the server adapter. It also provides details on configuring the
various system components used by the server adapter. These
components include CICS, EXCI, APPC/MVS, and RRMS.

In this chapter This chapter discusses the following topics:

A CICS Server Adapter Sample Configuration page 60

Configuration Summary of Adapter Plug-Ins page 65

59
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

A CICS Server Adapter Sample Configuration

Overview A sample configuration member is supplied with your Orbix Mainframe
installation that provides an example of how you might configure and deploy
the CICS server adapter on both native z/OS and UNIX System Services.
This section discusses the following topics:
• Location of configuration templates
• Configuration scope
• Configuration scope example

Location of configuration Sample configuration templates are supplied with your Orbix Mainframe
templates installation in the following locations:
• Non-TLS template—orbixhlq.CONFIG(BASETMPL)
• TLS template—orbixhlq.CONFIG(TLSTMPL)

Note: Further configuration resides in orbixhlq.CONFIG(ORXINTRL). This

contains internal configuration that should not usually require any
modifications.

Configuration scope An ORBname of iona_services.cicsa has been chosen for the CICS server
adapter service. Therefore, the corresponding configuration items that are
specific to the server adapter are scoped within an iona_services.cicsa
configuration scope.

60
 A CICS Server Adapter Sample Configuration

Configuration scope example The following is an example of the iona_services.cicsa configuration

scope.

Example 2: iona_services.cicsa Configuration Scope (Sheet 1 of 3)

iona_services
{
thread_pool:high_water_mark = "100";

orb_plugins = ["local_log_stream","iiop_profile", "giop", "iiop", "ots"];

generic_server:wto_announce:enabled = "true";
…
cicsa
{
event_log:filters = ["*=WARN+ERROR+FATAL", "IT_MFA=INFO_HI+WARN+ERROR+FATAL"];

plugins:cicsa:direct_persistence = "no";
plugins:cicsa:poa_prefix = "IT_MFA_CICS_";
#
# Settings for well-known addressing:
# (mandatory if direct_persistence is enabled)
# plugins:cicsa:iiop:port = "5007";
# plugins:cicsa:iiop:host = "%{LOCAL_HOSTNAME}";
#
# List of mappings of interface/operation -> CICS prog name
# PDS member or HFS filename may be specified
plugins:cicsa:mapping_file = "DD:MFAMAPS";
#
# The adapter may be configured to use type_info files or
# to contact the IFR to attain type information dynamically
# during runtime.
#
# * To configure to use type_info files:
# (note: source may be a PDS or HFS pathname)
# plugins:cicsa:repository_id = "type_info";
# plugins:cicsa:type_info:source = "%{LOCAL_HFS_ROOT}/info.txt";
#
# * To configure to use the IFR:
# plugins:cicsa:repository_id = "ifr";
# plugins:cicsa:ifr:cache = "";
#
plugins:cicsa:repository_id = "type_info";
plugins:cicsa:type_info:source = "DD:TYPEINFO";
plugins:cicsa:ifr:cache = "";

61
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

Example 2: iona_services.cicsa Configuration Scope (Sheet 2 of 3)

# Use the following to display timing information on adapter requests

# plugins:cicsa:display_timings = "yes";
#
# Choose a CICS protocol plugin: cics_exci or cics_appc
#
initial_references:IT_cicsraw:plugin = "cics_exci";
#initial_references:IT_cicsraw:plugin = "cics_appc";

plugins:cics_exci:applid = "CICSTS1";
plugins:cics_exci:pipe_name = "ORXPIPE1";
plugins:cics_exci:default_tran_id = "ORX1";
plugins:cics_exci:pipe_type = "SPECIFIC";
plugins:cics_exci:max_comm_area_length = "32000";

plugins:cics_appc:cics_destination_name = "ORBIXCIC";
plugins:cics_appc:appc_outbound_lu_name = "ORXLU02";
plugins:cics_appc:timeout = "6";
plugins:cics_appc:segment_length = "32767";

# Activate this to display accounting info

# plugins:cicsa:call_accounting_dll = "yes";
#
# Update the following to enable GIOP request logging:
# orb_plugins = ["local_log_stream", "request_logger", ...];
# binding:server_binding_list = ["request_logger", ""];
#
# For RRS/OTS support, add:
# event_log:filters = ["IT_REQUEST_LOGGER=*", ...];
#
# plugins:rrs:rm_name = "TEST.CICSRAW.IONA.UA";
# initial_references:IT_RRS:plugin = "rrs";
#
# For client principal support, add/update:
# plugins:cicsa:use_client_principal = "yes";
# plugins:cicsa:use_client_password = "no";
#
# And add the following if the client cannot send principals in a
# service context over GIOP 1.2 in a format recognised by the GIOP plugin
# policies:iiop:server_version_policy = "1.1";
#
# For publishing IORs from the adapter, add the following:
#
# Publishing to a USS file:
# plugins:cicsa:object_publishers = ["filesystem"];
# plugins:cicsa:object_publisher:filesystem:filename = "%{LOCAL_HFS_ROOT}/test.txt";

62
 A CICS Server Adapter Sample Configuration

Example 2: iona_services.cicsa Configuration Scope (Sheet 3 of 3)

#
# Publishing to a DD file that has to be defined in the JCL:
# plugins:cicsa:object_publishers = ["filesystem"];
# plugins:cicsa:object_publisher:filesystem:filename = "DD:MFAIORS";
#
# Publishing to a naming service context:
# plugins:cicsa:object_publishers = ["naming_service"];
# plugins:cicsa:object_publisher:naming_service:context = "test_context";
# plugins:cicsa:object_publisher:naming_service:context:auto_create = "true";
# plugins:cicsa:object_publisher:naming_service:update_mode = "current";
# plugins:cicsa:object_publisher:naming_service:nested_scopes = "false";
#
# Publishing to a naming service group:
# plugins:cicsa:object_publishers = ["naming_service"];
# plugins:cicsa:object_publisher:naming_service:group:prefix = "group1_";
# plugins:cicsa:object_publisher:naming_service:group:member_name = "adapter2";
# plugins:cicsa:object_publisher:naming_service:update_mode = "current";
# plugins:cicsa:object_publisher:naming_service:nested_scopes = "false";
#
# For the Adapter portable interceptor demo, please add "demo_sec"
# and "portable_interceptor" to your orb_plugins list.
# If you need an example, please refer to the orb_plugins list
# in the iona_services scope. Afterwards, please uncomment the next
# three configuration settings.
#
# orb_plugins = [ ... , "demo_sec", "portable_interceptor"];
#
# binding:server_binding_list = ["DemoPI"];
# plugins:demo_sec:shlib_name = "SECPI";
# plugins:demo_sec:shlib_version = "1";
#
# Performance management logging: enable the remote
# logging feature by updating/adding the following:
#
# orb_plugins = [ ..., "it_response_time_logger" ];
# binding:server_binding_list = ["it_response_time_logger"];
# plugins:it_response_time_collector:period = "60"; # secs
# plugins:it_response_time_collector:server-id = "cicsa_1";
# plugins:it_response_time_collector:remote_logging_enabled = "true";
# initial_references:IT_PerfLoggingReceiver:reference
# = "..."; # IOR or corbaloc of remote logger
};
…

63
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

Note: The configuration items shown in Example 2 can be used to deploy

an insecure server adapter. See “Securing and Using the CICS Server
Adapter” on page 209 for more details about the configuration items that
are involved in deploying a server adapter in secure mode.

Configuring a domain Refer to the CORBA Administrator’s Guide for more details on how to
configure an Orbix configuration domain.

64
 Configuration Summary of Adapter Plug-Ins

Configuration Summary of Adapter Plug-Ins

Overview Orbix configuration allows you to configure an application on a per-plug-in
basis. This section provides a summary of the configuration items
associated with plug-ins specific to the CICS server adapter.
This section discusses the following topics:
• CICS server adapter plug-ins
• Summary of items for the cicsa plug-in
• Summary of items for the cics_exci plug-in
• Summary of items for the cics_appc plug-in
• Summary of items for the rrs plug-in
• Summary of remaining configuration items

Note: See “Securing the CICS Server Adapter” on page 211 for more
details about the items relating to the iSF security plug-in.

CICS server adapter plug-ins There are four plug-ins associated with the CICS server adapter:
• The cicsa plug-in is the core CICS server adapter plug-in.
• The cics_exci plug-in is used specifically for communications with
CICS over EXCI.
• The cics_appc plug-in is used specifically for communications with
CICS over APPC.
• The rrs plug-in provides integration for the Object Transaction Service
(OTS) and CICS commit processing. This plug-in is optional and can
only be used if RRS is configured and RRS support in CICS is enabled.
It can only be used with the cics_exci plug-in.

Note: Either the EXCI or APPC plug-in should be selected with the
initial_references:IT_cicsraw:plugin configuration variable.

65
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

Summary of items for the cicsa The following is a summary of the configuration items associated with the
plug-in cicsa plug-in. Refer to “CICS Server Adapter Configuration Details” on
page 77 for more details.
iiop:port Specifies the TCP/IP port number that the
CICS server adapter uses to listen for
incoming requests. Valid values are in the
range 1025–65535. This is an optional item.
direct_persistence Specifies the persistence mode adopted by
the CICS server adapter service. This is an
optional item. iiop:port is required if this is
specified as yes.
poa_prefix Specifies the POA prefix name. This is an
optional item. The default value is IT_MFA_.
iiop:host Specifies the host name that is contained in
IORs exported by the CICS server adapter.
alternate_endpoint Allows requests to the MappingGateway
administrative interface to be processed by
threads on an alternate workqueue instead of
using the thread resources of the main
automatic workqueue.
mapping_file This file contains the mapping entries. Refer
to “The Mapping File” on page 238 for more
details. Optional.
repository_id Specifies the type information source to use.
This source supplies the CICS server adapter
with operation signatures as required. Valid
values are ifr, type_info, and none. The
default is ifr. Refer to “Type information
mechanism” on page 85 for more
information
ifr:cache This value is used if repository_id is set to
“ifr”. The ifr:cache configuration item is
optional, specifying the location of an
(operation) signature cache file. This
signature cache file contains a cache of
operation signatures from a previous run of
this server adapter. The default is no
signature cache file (“”).

66
 Configuration Summary of Adapter Plug-Ins

type_info:source This value is used if repository_id is set to

“type_info”. The type_info:source variable
denotes the location of a type_info store from
which the server adapter can obtain
operation signatures. Refer to “type_info
store” on page 86 for more information.
use_client_principal Indicates that the CICS server adapter should
verify the client principal user ID with SAF
before trying to start the target CICS program
under that ID. The default is no.
use_client_principal Used with the CICS EXCI plug-in. When set
_user_security to true, this indicates that the CICS server
adapter should provide the client principal
user ID on the request to start the target CICS
program. The default is false.
use_client_password Indicates that the CICS server adapter should
use a client password when it wants to
switch the thread that is making the request
to CICS to the user ID passed in the client
principal, instead of using SURROGAT rights.
display_timings Displays timestamps at various processing
points for a request with information being
written to SYSPRINT. Refer to “Displaying
transaction processing times” on page 83 for
more details.
display_timings_in_logfile Displays timestamps at various processing
points for a request with information being
written to the Orbix event log. This sends
messages to SYSOUT by default. Refer to
“Displaying transaction processing times” on
page 83 for more details.
call_accounting_dll If set to yes, this causes the accounting DLL
to be called and accounting statistics to be
displayed after each client request has been
processed by the adapter. The default is no.
Refer to “Activating the Accounting DLL in
the Server Adapter” on page 297 for more
details.

67
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

capture_first_argument_ If set to yes, this passes the first argument of

in_dynany the request to the IT_MFA_display_account_
information() function as a dynamic any.
The default is no. Refer to “Activating the
Accounting DLL in the Server Adapter” on
page 297 for more details.
object_publishers Specifies where the adapter can publish its
object references. Valid options are
naming_service to publish object references
to the Naming Service, and filesystem to
publish object references to file. The default
value is "". See “Exporting Object References
at Runtime” on page 298 for more details.
write_iors_to_file This item has now been deprecated and is
superseded by the plugins:cicsa:object_
publisher:filesystem:filename
configuration item described next.
object_publisher: This supersedes the plugins:cicsa:write_
filesystem:filename iors_to_file configuration item. It specifies
the file that should be used if you want the
adapter to export object references to a file.
You can specify the full path to an HFS
filename, a PDS member name, or a PDS
name as the value for this item. If this
configuration item is not included in the
adapter’s configuration, no object references
are exported to file. See “Exporting Object
References at Runtime” on page 298 for
more details.
write_iors_to_ns_context This item has now been deprecated and is
superseded by the plugins:cicsa:object_
publisher:naming_service:context
configuration item described next.

68
 Configuration Summary of Adapter Plug-Ins

object_publisher: This supersedes the plugins:cicsa:write_

naming_service: iors_to_ns_context configuration item. It
context specifies the Naming Service context that
should be used if you want the adapter to
export object references to a Naming Service
context. If this configuration item is not
included in the adapter’s configuration, no
object references are exported to a Naming
Service context. See “Exporting Object
References at Runtime” on page 298 for
more details.
object_publisher: This specifies whether the Naming Service
naming_service:context: context specified by
auto_create plugins:cicsa:object_publisher:
naming_service:context should be created
if it does not exist. Valid options are true and
false. The default value is true.
object_publisher: Specifies whether adapter-deployed objects
naming_service: should only be published during start-up, or
update_mode whether updates should also be published.
Valid values are startup and current. The
default value is startup. See “Exporting
Object References at Runtime” on page 298
for more details.
place_iors_in_nested_ns_sc This item has been deprecated and is
opes superseded by the plugins:cicsa:object_
publisher:naming_service:nested_scopes
configuration item described next.
When using Naming Service contexts and
plugins:cicsa:object_publisher:
naming_service:context:auto_create is set
to true, contexts are created for IDL module
scopes. For example, Simple/SimpleObject
with plugins:cicsa:object_publisher:
naming_service:context set to base creates
a context tree of /base/Simple for
SimpleObject.
The default for
plugins:cicsa:object_publisher:
naming_service:nested_scopes is false.

69
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

object_publisher:naming_se This supersedes the plugins:cicsa:place_

rvice:nested_scopes iors_in_nested_ns_scopes configuration
item. If this configuration item is set to
false, the IOR is stored in the specified
scope in the Naming Service. If this
configuration item is set to true, the module
name(s) of the interface for the IOR are used
to navigate subscopes from the configured
scope, with the same names as the module
names, and the IOR is then placed within the
relevant subscope. The default is false. See
“Exporting Object References at Runtime” on
page 298 for more details.
publish_all_iors If set to yes, this instructs the adapter to
export object references for the
MappingGateway interface, the cicsraw
interface, and all interfaces specified in the
adapter mapping file.
If set to no, this instructs the adapter to
export object references for the
MappingGateway and cicsraw interfaces only.
The default is no. See “Exporting Object
References at Runtime” on page 298 for
more details.
Note: This configuration item is only used
by the deprecated object publishing
configuration items. When using the new
object publishing configuration items, all
IORs are published.

70
 Configuration Summary of Adapter Plug-Ins

remove_ns_iors_on If set to yes, this instructs the adapter to

_shutdown unbind the object references from the
Naming Service when shutting down
normally. The default is no. See “Exporting
Object References at Runtime” on page 298
for more details.
Note: This configuration item is only used
by the deprecated object publishing
configuration items. When using the new
object publishing configuration items, the
setting of
plugins:cicsa:object_publisher:
naming_service:update_mode determines if
the server adapter attempts to unbind object
references from the Naming Service when it
shuts down normally. A setting of current
causes the server adapter to attempt to
unbind references at shutdown.
write_iors_to_ns_group This item has been deprecated and is
_with_prefix superseded by the plugins:cicsa:object_
publisher:naming_service:group:prefix
configuration item described next.
object_publisher:naming_se This supersedes the plugins:cicsa:write_
rvice:group:prefix iors_to_ns_group_with_prefix
configuration item. It specifies the prefix that
should be attached to each generated name
indicating an interface, if you want the
adapter to export object references to a
Naming Service object group. This prefix is
attached to the generated name, to specify
the object group that is to be used.
If this configuration item is not included in
the adapter’s configuration, no object
references are exported to any Naming
Service object groups. See “Exporting Object
References at Runtime” on page 298 for
more details.
write_iors_to_ns_group This item has been deprecated and is
_member_name superseded by the plugins:cicsa:object_
publisher:naming_service:group:member_
name configuration item described next.

71
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

object_publisher:naming_se This supersedes the plugins:cicsa:write_

rvice:group:member_name iors_to_ns_group_member_name
configuration item. It specifies the member
name that the adapter should use in the
object group. A unique member name must
be specified for each adapter; otherwise, one
adapter might end up replacing the object
group members of another adapter. See
“Exporting Object References at Runtime” on
page 298 for more details.

Summary of items for the The following is a summary of the configuration items associated with the
cics_exci plug-in cics_exci plug-in. Refer to “EXCI Plug-In Configuration Items” on page 94
for more details.
Applid Specifies the APPLID of the CICS region to which
the server adapter is to connect. The default is
CICSAPPL.
pipe_name Specifies the NETNAME of a CICS-specific EXCI
connection for the CICS server adapter to use.
The default is ORXPIPE1.
pipe_type Specifies whether specific or generic EXCI
sessions are to be used. Valid values are
SPECIFIC and GENERIC. The default is SPECIFIC.
default_tran_id Specifies the default EXCI mirror transaction ID
that is used on the CICS EXCI when the client
makes a request. The default is ORX1.
max_comm_area_length Specifies the maximum size, in bytes, of the
COMMAREA block (that is, the buffer that is to
be available to exchange data with the CICS
programs). The default value is 32000.
check_if_cics_available If this is set to yes, CICS must be available
before you start the CICS server adapter in EXCI
mode. The default is no, to allow the CICS server
adapter to start even if CICS is not available.

72
 Configuration Summary of Adapter Plug-Ins

Summary of items for the The following is a summary of the configuration items associated with the
cics_appc plug-in cics_appc plug-in. Refer to the “APPC Plug-In Configuration Items” on
page 110 for more details.
cics_destination_name Specifies a symbolic name that identifies the
APPC LU (Logical Unit) name for the CICS region
to which the CICS server adapter connects. The
default value is ORBXCICS.
appc_outbound_lu_name Specifies the CICS server adapter’s APPC LU
name. The default value is none, which means
that the system base LU is used.
timeout Specifies the number of minutes that the CICS
server adapter waits for a response from CICS
before cancelling the request. The default value is
no timeout.
segment_length Specifies the maximum size, in bytes, of each
APPC data segment. The default value is 32767,
which is also the maximum.

Summary of items for the rrs The following is a summary of the configuration items associated with the
plug-in rrs plug-in. Refer to “RRS Plug-In Configuration Items” on page 122 for
more details.
rm_name The resource manager name that
the CICS server adapter uses to
register with RRS. Ensure that
this variable is not specified in the
configuration scope of the CICS
server adapter, if you do not want
the RRS plug-in loaded.
initial_references:IT_RRS:plugin Indicates to the CICS server
adapter that it is the plug-in to
loaded to enable communication
with RRS. This is required if the
rrs plug-in is used.

73
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

Summary of remaining The following is a summary of the remaining configuration items. Refer to
configuration items “CICS Server Adapter Configuration Details” on page 77 and the CORBA
Administrator’s Guide for more details.
thread_pool:initial_threads Specifies the initial number of
threads that are created in the
thread pool to send requests to
CICS. This item is optional. The
default value is 5.
thread_pool:high_water_mark Specifies the maximum number
of threads created in the CICS
server adapter thread pool to
send requests to CICS. This item
is optional. Default value is -1.
event_log:filters Specifies the types of events that
the CICS server adapter logs.
orb_plugins List of standard ORB plug-ins the
CICS server adapter should load.
initial_references:IT_MFA:reference IOR used by itadmin to contact
the CICS server adapter—added
to configuration after the server
adapter has been run in prepare
mode.
initial_references:IT_cicraw:plugin Specifies the CICS transport-level
plug-in that is to be loaded. Valid
values are cics_exci and
cics_appc. When preparing the
CICS server adapter, using the
JCL in
orbixhlq.JCLLIB(PREPCICA),
this must be set to cics_exci to
allow the prepare JOB to
complete with condition codes of
zero.

74
 Configuration Summary of Adapter Plug-Ins

initial_references:IT_WTO_Announce: This is used in conjunction with

plugin generic_server:wto_announce:
enabled to enable the loading of
the WTO announce plug-in in an
Orbix service, such as the CICS
server adapter. This item must be
set to wto_announce to enable
messages to be written to the
operator console on starting or
shutting down successfully.
generic_server:wto_announce:enabled This is used in conjunction with
initial_references:IT_WTO_
Announce:plugin to enable the
loading of the WTO announce
plug-in in an Orbix service, such
as the CICS server adapter. This
item must be set to true to
enable messages to be written to
the operator console on starting
or shutting down successfully.
policies:iiop:server_version_policy If this is set to 1.1, the server
adapter publishes a version 1.1
IOR which instructs clients to
communicate over GIOP 1.1. If
this is set to 1.2 (the default), 1.2
is used as the default GIOP
version. See “Configuring the
CICS Server Adapter for Client
Principals” on page 123 for more
details.
policies:giop:interop_policy: For GIOP 1.2, if this is set to
enable_principal_service_context true, it instructs the CICS server
adapter to look for the principal
string in a service context. The
default is false. See “Configuring
the CICS Server Adapter for Client
Principals” on page 123 for more
details.

75
CHAPTER 3 | Introduction to CICS Server Adapter Configuration

policies:giop:interop_policy: If
principal_service_context_id principal_service_context_id
is set to true, this item specifies
the service context ID from which
the CICS server adapter attempts
to read the principal string. See
“Configuring the CICS Server
Adapter for Client Principals” on
page 123 for more details.

76
 CHAPTER 4

CICS Server
Adapter
Configuration
Details
This chapter provides details of the configuration items for the
CICS Server Adapter’s application service plug-in. These items
are used to specify parameters such as TCP/IP transport
details, the level of Orbix event logging, and mapping
information for mapping IDL operations to CICS programs.

In this chapter This chapter discusses the following topic:

CICS Server Adapter Service Configuration page 78

77
CHAPTER 4 | CICS Server Adapter Configuration Details

CICS Server Adapter Service Configuration

Overview This chapter discusses the following topics:
• Persistence mode
• Host name
• Well known addressing
• Initial threads in thread pool
• Maximum threads in thread pool
• Alternate workqueue for the MappingGateway
• IT_cicsraw initial reference
• IT_MFA initial reference
• Orbix event logging
• WTO announce plug-in
• ORB plug-ins list
• POA prefix
• Displaying transaction processing times
• Mapping file
• Type information mechanism
• IFR signature cache file
• type_info store

Persistence mode The related configuration item is plugins:cicsa:direct_persistence. It

specifies the persistence mode policy adopted by the CICS server adapter. If
you want the server adapter to run as a standalone service, set this to yes. If
you set this to no, the server adapter contacts and registers with the locator
service.

Host name The related configuration item is plugins:cicsa:iiop:host. It specifies the

name of the host on which the CICS server adapter is running. This host
name is contained in IORs exported by the CICS server adapter.

78
 CICS Server Adapter Service Configuration

Well known addressing Configuration items for well known addressing can be specified on the IIOP
and secure IIOP plug-ins that are loaded by the CICS server adapter. For
example, you can use plugins:cicsa:iiop:port to specify a fixed TCP/IP
port that the CICS server adapter uses to listen for insecure incoming
CORBA requests. If the adapter is running with direct persistence enabled,
the specified port number is published in the IORs generated by the adapter
in prepare mode, and in any IORs returned by the MappingGateway interface.
Refer to “Using the MappingGateway Interface” on page 272 for more
details. If the adapter is running in indirect persistent mode, the locator’s
addressing information is published in the IORs; however, in this case, the
adapter still listens on the specified port.
The specified port number cannot be less than 1025, because the TCP/IP
port numbers up to and including 1024 are reserved for TCP/IP services.
Therefore, ensure that you do not use a port that is allocated to some other
TCP/IP service on the machine. The server adapter checks to see if the port
is available before it attempts to use it.

Initial threads in thread pool The related configuration item is thread_pool:initial_threads. It specifies
the initial number of threads that are created in the thread pool to send
requests to CICS. This item is optional. The default value is 5.

Maximum threads in thread pool The related configuration item is thread_pool:high_water_mark. It specifies
the maximum number of threads created in the CICS server adapter thread
pool to send requests to CICS. This item is optional. Default value is -1.

Alternate workqueue for the The related configuration item is plugins:cicsa:alternate_endpoint. It

MappingGateway allows the CICS server adapter to be configured so that requests to the
MappingGateway administrative interface are processed by threads on an
alternate workqueue instead of using the thread resources of the main
automatic workqueue. This allows the main workqueue to remain dedicated
to processing requests that are destined for CICS.

79
CHAPTER 4 | CICS Server Adapter Configuration Details

The associated thread pool settings can then be configured as follows:

plugins:cicsa:alternate_endpoint:thread_pool:high_water_mark =
"-1";
plugins:cicsa:alternate_endpoint:thread_pool:low_water_mark =
"-1";
plugins:cicsa:alternate_endpoint:thread_pool:initial_threads =
"2";
plugins:cicsa:alternate_endpoint:thread_pool:max_queue_size =
"-1";

The preceding values correspond to the default settings that are assumed if
these items are omitted from the CICS server adapter configuration. See the
CORBA Administrator’s Guide for general information on thread pools and
workqueues.
If you have configured the CICS server adapter to use direct persistence, you
must specify the addressing information for the listener associated with the
MappingGateway interface’s alternate endpoint. You can specify well-known
addressing information as follows:

plugins:cicsa:alternate_endpoint:iiop:port = "5007";
plugins:cicsa:alternate_endpoint:iiop:host = "hostname";

The IOR that is published by the server adapter for the MappingGateway
interface now includes this addressing information.

IT_cicsraw initial reference The related configuration item is initial_references:IT_cicsraw:plugin.

The cicsa plug-in uses this configuration item to establish the name of the
CICS transport-level plug-in to be loaded. To load the CICS EXCI plug-in, set
this item to cics_exci. To load the CICS APPC plug-in, set this item to
cics_appc.
This plug-in is used by the CICS server adapter service to communicate with
CICS—it is therefore required for processing both the cicsraw interface and
mapped IDL interface requests. This item is required.

Note: When preparing the CICS server adapter, using the JCL in
orbixhlq.JCLLIB(PREPCICA), set this value to cics_exci. This allows the
prepare JOB to complete with condition codes of zero.

80
 CICS Server Adapter Service Configuration

IT_MFA initial reference The related configuration item is initial_references:IT_MFA:reference.

This specifies the IOR that is used by itadmin to contact the CICS server
adapter. This is added to the adapter configuration after the server adapter
has been run in prepare mode.

Orbix event logging The related configuration item is event_log:filters. It is used in Orbix
configuration to specify the level of event logging. To obtain events specific
to the CICS server adapter, the IT_MFA event logging subsystem can be
added to this list item. For example:

event_log:filters = ["*=WARN+ERROR+FATAL",
"IT_MFA=INFO_HI+INFO_MED+WARN+ERROR+FATAL"];

This then logs all IT_MFA events (except for INFO_LOW — low priority
informational events), and any warning, error, and fatal events from all other
subsystems (for example, IT_CORE, IT_GIOP, and so on). The level of detail
that is provided for IT_MFA events can therefore be controlled by setting the
relevant logging levels. Refer to the CORBA Administrator’s Guide for more
details.
The following is a categorization of the informational events associated with
the IT_MFA subsystem.
INFO_HI Configuration settings and CICS server adapter startup
and shutdown messages
INFO_MED Mapping gateway actions and CICS EXCI/APPC calls,
including return codes
INFO_LOW CICS segment data streams and RRS actions

Note: To enable the logging of user ID details sent into CICS via EXCI
when the plugins:cicsa:use_client_principal_security configuration
item is set to true, the event_log:filters configuration item must
contain INFO_MED in its list of values for the IT_MFA filter, as shown in the
preceding example.

81
CHAPTER 4 | CICS Server Adapter Configuration Details

WTO announce plug-in Orbix applications may be configured to write messages to the operator
console on starting or shutting down successfully. This can be useful for
automated operations software to keep track of these events. The WTO
announce plug-in is used to implement this feature.
To enable the loading of the WTO announce plug-in in an Orbix service,
such as the CICS server adapter, add the following two configuration items
in the iona_services.cicsa scope:
• initial_references:IT_WTO_Announce:plugin = "wto_announce";
• generic_server:wto_announce:enabled = "true";

Note: For customer-developed Orbix applications (for example, a batch

COBOL or PL/I server), the wto_announce plug-in should be added to the
end of the orb_plugins list in that particular application’s ORB
configuration. (See “ORB plug-ins list” next for more details.) However, for
all Orbix services (by default, within the iona_services configuration
scope), it is recommended that you load the wto_announce plug-in by
specifying the two preceding configuration items rather than by adding the
wto_announce plug-in to the orb_plugins list.

When you load the WTO announce plug-in, a WTO message is issued when
the server adapter ORB starts up and shuts down. Messages take the
following format:

+ORX2001I ORB iona_services.cicsa STARTED (HOSTNAME:<process id>)

+ORX2002I ORB iona_services.cicsa ENDED (HOSTNAME: <process id>)

On UNIX System Services, <process id> is a PID. On native z/OS,

<process id> is a job name and an A=xxxx job identifier.

ORB plug-ins list The related configuration item is orb_plugins. It specifies the ORB-level
plug-ins that should be loaded in your application at ORB_init() time. On
z/OS, you can add the WTO announce plug-in support to any
customer-developed Orbix application by updating this list in the relevant
configuration scope. For example:

orb_plugins = ["iiop_profile", "giop", "iiop",

"local_log_stream", "wto_announce"];

82
 CICS Server Adapter Service Configuration

In the case of the CICS server adapter’s configuration (that is, in the
iona_services.cicsa scope itself) the wto_announce plug-in should not be
included in this list, as discussed in “WTO announce plug-in” on page 82.
If RRS support is required, you can add the OTS plug-in to this list. For
example, in the iona_services.cicsa scope:

orb_plugins = ["iiop_profile", "giop", "iiop",

"local_log_stream", "ots"];

POA prefix The related configuration item is plugins:cicsa:poa_prefix. It specifies

the prefix to be assigned to the POA name used by the CICS server adapter.
The default value is IT_MFA_. This POA name is embedded in the object key
of the IOR that is published by the server adapter in prepare mode, and
obtained with resolve from the Mapping Gateway interface. The POA name
is not significant in a server that runs in direct persistent mode; however, it
can be useful for the purposes of keeping track of IORs in an environment
where multiple CICS server adapters are being deployed.

Displaying transaction processing The related configuration items are plugins:cicsa:display_timings and
times plugins:cicsa:display_timings_in_logfile. Both items are set to no by
default. The difference between these settings is where the data is printed.
display_timings sends timing information to SYSPRINT.
display_timings_in_logfile sends timing information to the Orbix event
log, which sends messages to SYSOUT by default.
If you set plugins:cicsa:display_timings or
plugins:cicsa:display_timings_in_logfile to yes, the server adapter
produces output similar to the following:

2005-05-20 02:07:46: Simple/SimpleObject: call_me: 1: +0 ms, 2: +37ms, 3: +45ms, 4: +51ms

Each item of output contains one line. Each line shows the date and time
when the corresponding request was completed, the name of the interface
and operation, and the timestamps at each of the four measurement points
(in milliseconds). All timestamps are relative to the first measurement point.
Therefore, the first measurement point always shows zero milliseconds.

83
CHAPTER 4 | CICS Server Adapter Configuration Details

The four measurement points taken are:

1. After the dispatching handler thread gets the request from the server
adapter's pending request work queue.
2. Before sending the request to CICS.
3. After receiving the response from CICS.
4. Before sending the response back to the client, using IIOP.
The times measured do not include any time that the request has waited for
a server adapter processing thread to become available. If you therefore
have five threads in the server adapter, and send six requests at exactly the
same moment, the times displayed for the sixth request do not include the
time it waited in the server adapter input queue for a thread to become
available.
The first measurement point is taken before the data is marshalled from the
IIOP request buffer, and is exactly the same point in the source code for
each version of the server adapter.
The second and third measurement points are only approximately the same
point in the source code for each version of the server adapter CICS
transport (EXCI or APPC) plug-ins.
The fourth point is taken after the data has been marshalled back into the
IIOP request buffer, but before it is transmitted to the client. It is also exactly
the same point in the source code for each version of the server adapter.
No information is displayed for threads with IDs greater than 99. The use of
plugins:cicsa:display_timings or
plugins:cicsa:display_timings_in_logfile can cause a small decrease
in the performance of server adapters, compared to when the server
adapters are running without these configuration settings.

Mapping file The related configuration item is plugins:cicsa:mapping_file. You can

use this to specify either a native z/OS dataset name or a fully qualified
pathname to a z/OS UNIX System Services file. The contents of the specified
file represent the mappings between IDL operations that the adapter
supports and target CICS program names. The mapping file is read by the
adapter when it starts. Refer to “The Mapping File” on page 238 for more
details.

84
 CICS Server Adapter Service Configuration

Type information mechanism The related configuration item is plugins:cicsa:repository_id. It specifies

the repository used by the CICS server adapter to store operation signatures.
Two repositories are supported: ifr and type_info store. The default is ifr.
Refer to “Using type_info store as a Source of Type Information” on
page 254 for more information on the role of type information. You can also
set this item to none, to indicate that the adapter should only support
cicsraw and not attempt to read type information from anywhere.

IFR signature cache file If the CICS server adapter is configured to use the IFR as the type
information repository (a store of operation signatures), an IFR signature
cache file can be used to improve performance. The related configuration
item is plugins:cicsa:ifr:cache. Refer to “Using an IFR Signature Cache
file” on page 252 for more information on how IFR signature cache files
work.
The filename specification for the signature cache file can take one of
several forms:
• The following example reads the mappings from a file in the z/OS UNIX
System Services hierarchical file system (HFS):

plugins:cicsa:ifr:cache = "/home/user/sigcache.txt;"

• The following example shows the syntax to indicate that the mappings
are cached in a flat file (PS) data set, which is created with the default
attributes used by the LE runtime:

plugins:cicsa:ifr:cache = "//orbixhlq.DEMO.IFRCACHE";

The data set is created with the default attributes used by the LE runtime.
Depending on the number of interfaces and the complexity of the types
used, this might not be large enough. In this case, the CICS server adapter
saves as many cache entries as possible and then issues error messages. If
this occurs, you should preallocate a larger data set with the same
attributes, and use this name the next time you start the server adapter.

Note: Do not use members of partitioned data sets as a signature cache

file.

85
CHAPTER 4 | CICS Server Adapter Configuration Details

type_info store If the CICS server adapter is configured to use a type_info store as the type
information repository (a store of operation signatures), the location of the
store must be supplied. The related configuration item is
plugins:cicsa:type_info:source.
The plugins:cicsa:type_info:source variable can be set to one of the
following:
• An HFS file (z/OS UNIX System Services)
Specifies a file to use as a type_info source. Operation signatures are
read from this file during start-up. If a refresh is requested (via itadmin
mfa refresh for example), this file is re-read. For example:

plugins:cicsa:type_info:source = "/home/bob/type_info.txt";

• An HFS directory (z/OS UNIX System Services)

Specifies a directory to use as a type_info source. Operation signatures
are read from all files in this directory during start-up. If a refresh is
requested, all files in the directory are browsed until the relevant
operation signature(s) are found. For example:

plugins:cicsa:type_info:source = "/home/bob/typeinfo_store";

• A PDS member (native z/OS)

Specifies a PDS member (batch) to use as a type_info source.
Operation signatures are read from this member during start-up. If a
refresh is requested, this member is re-read. For example:

plugins:cicsa:type_info:source = "//MY1.TYPEINFO(MYINFS)";

• A PDS (native z/OS)

Specifies a dataset to use as a type_info source. Operation signatures
are read from all members in this dataset during start-up. If a refresh is
requested, all members in the dataset are browsed until the relevant
operation signature(s) are found. For example:

plugins:cicsa:type_info:source = "//MY1.TYPEINFO";

86
 CICS Server Adapter Service Configuration

For PDS names, you can use a DD name, as long as this is defined to the
CICS server adapter start JCL, orbixhlq.JCLLIB(CICSA).

Note: The use of HFS directories or a PDS is preferable to the use of flat
files, because these methods are better suited to the dynamic addition or
removal of interface information, and they can also address IDL versioning.

87
CHAPTER 4 | CICS Server Adapter Configuration Details

88
 CHAPTER 5

Configuring the
CICS Server
Adapter EXCI
Plug-In
This chapter describes how to configure the CICS server
adapter to use EXCI to communicate with CICS.

In this chapter This chapter discusses the following topics:

Setting Up EXCI for the CICS Server Adapter page 90

EXCI Plug-In Configuration Items page 94

89
CHAPTER 5 | Configuring the CICS Server Adapter EXCI Plug-In

Setting Up EXCI for the CICS Server Adapter

Overview This section describes the steps to set up EXCI for the CICS server adapter.
It discusses the following topics:

Installing Support for IRC for the External Call Interface page 91

Installing Sample Orbix CICS Resource Definitions page 92

Updating Access Permissions for CICS Resources page 93

Further reading Refer to the manual CICS/ESA 4.1 Intercommunication Guide or the
equivalent CICS TS manuals for details on installing IRC support in CICS.
Refer to the manual CICS/ESA 4.1 External CICS Interface or the equivalent
CICS TS manuals (CICS TS External Interfaces Guide) for details on EXCI
used by the Orbix CICS server adapter.
Refer to the section on security in the IBM publication EXCI reference,
SC26-8743 for details on security-related questions.

90
 Setting Up EXCI for the CICS Server Adapter

Installing Support for IRC for the External Call Interface

Overview Support for Inter Region Communication (IRC) must be installed in CICS,
and a number of definitions must be made in CICS to support the EXCI
mechanism used by Orbix CICS.
This subsection discusses the following topics:
• Enabling IRC
• Confirmation IRC is activated

Enabling IRC In general, IRC can be enabled by specifying the CICS parameter IRC=YES or
IRCSTRT=YES (depending on the version), and by using the default CICS
definitions in the CICS System Definition Data Set (CSD) group DFH$EXCI
that are delivered with CICS by default. These definitions are sufficient to get
started and they can be used as models for any future requirements you
might have.

Confirmation IRC is activated The following message is issued if this support is active and installed
correctly within CICS:

DFHSI1519I CICS The interregion communication session was

successfully started.

If this message is not issued, the CICS server adapter cannot use EXCI to
communicate with the CICS region.

91
CHAPTER 5 | Configuring the CICS Server Adapter EXCI Plug-In

Installing Sample Orbix CICS Resource Definitions

Overview This subsection discusses the following topics:
• Location of sample JCL to run DFHCSDUP
• Using the sample JCL
• Achieving optimal performance

Location of sample JCL to run The orbixhlq.JCLLIB(ORBIXCSD) data set contains a job to run DFHCSDUP,
DFHCSDUP which is the CICS offline resource definition utility, to define the CICS
resources used by the sample jobs and demonstrations.

Using the sample JCL You can run the sample ORBIXCSD JCL as is, or just use it as a reference
when defining the resources online with the CEDA transaction. When the
resources have been defined, use CEDA to install the whole group.

Achieving optimal performance To achieve optimal performance, update the value of RECEIVECOUNT in the
definition of the ORX1 session to ensure that it matches the maximum
number of threads specified for the CICS server adapter via the
thread_pool:high_water_mark configuration item.

92
 Setting Up EXCI for the CICS Server Adapter

Updating Access Permissions for CICS Resources

Overview To use the CICS server adapter with a secured CICS region, a number of
RACF definitions must be added or changed. Details of the relevant CICS
security mechanisms are described in the chapter “Securing the CICS Server
Adapter” on page 211. The following are some examples of RACF
commands that are needed to establish the necessary permissions.
This subsection discusses the following topics:
• Prerequisites
• Running the server adapter in default mode

Prerequisites Depending on what security options are enabled in your CICS region, or if
the region uses SECPRFX=YES, or if you use group instead of member RACF
classes, the commands for your region might differ.

Running the server adapter in When you run the server adapter in default mode, it requires access to the
default mode EXCI connection, the CICS region, and the EXCI mirror transaction. If user
security is enabled on the EXCI connection (ATTACHSEC(IDENTIFY)), clients
of the server adapter might need access to the EXCI mirror transaction.
The following is an example of the commands for the default mode:

RDEFINE FACILITY (DFHAPPL.ORXPIPE1) UACC(NONE)

PERMIT DFHAPPL.ORXPIPE1 CLASS(FACILITY) ID(Adapter)
ACCESS(UPDATE)

RDEFINE FACILITY (DFHAPPL.CICS) UACC(NONE)

PERMIT DFHAPPL.CICS CLASS(FACILITY) ID(Adapter) ACCESS(READ)

RDEFINE TCICSTRN ORX1 UACC(NONE)

PERMIT ORX1 CLASS(TCICSTRN) ID(Adapter) ACCESS(READ)
PERMIT ORX1 CLASS(TCICSTRN) ID(client1, client2,…) ACCESS(READ)

93
CHAPTER 5 | Configuring the CICS Server Adapter EXCI Plug-In

EXCI Plug-In Configuration Items

In this section This section provides a detailed description of the EXCI plug-in configuration
items. It discusses the following topics:
• CICS APPLID
• CICS connection name
• CICS connection type
• CICS mirror transaction
• CICS COMMAREA length
• CICS availability

CICS APPLID The related configuration item is plugins:cics_exci:applid. It specifies

the APPLID of the CICS region to which the server adapter is to connect. The
CICS server adapter communicates with only one CICS region. If
cics_exci:check_if_cics_available is set to yes, the specified APPLID is
verified when the server adapter starts. This means that the CICS region has
to be available when you start the server adapter in prepare mode. The CICS
region does not have to be available, however, if
cics_exci:check_if_cics_available is set to no.

CICS connection name The related configuration item is plugins:cics_exci:pipe_name. It specifies

the NETNAME of a CICS-specific EXCI connection for the CICS server adapter
to use. By default, the server adapter uses the specific connection that is
defined to EXCI for communicating with CICS. You can also use the CICS
generic connection. However, because this resource must be shared by all
the EXCI programs in your system, there might be times when it is
temporarily unavailable to the CICS server adapter. In such cases, the CICS
server adapter might not be able to process an incoming client request.
Better availability can be achieved by specifying a specific EXCI connection
that is dedicated to each server adapter.

CICS connection type The related configuration item is plugins:cics_exci:pipe_type. It specifies

whether specific or generic EXCI sessions are to be used. Valid values are
SPECIFIC and GENERIC.

94
 EXCI Plug-In Configuration Items

CICS mirror transaction The related configuration item is plugins:cics_exci:default_tran_id. It

specifies the default CICS mirror transaction ID that is used on the CICS
EXCI when the client calls run_program() or run_program_binary() on the
cicsraw interface to invoke a CICS program or for a mapped transaction.

CICS COMMAREA length The related configuration item is

plugins:cics_exci:max_comm_area_length. It specifies the maximum size,
in bytes, of the COMMAREA block (that is, the buffer that is to be available
to exchange data with the CICS programs). IDL operations with a large
number of arguments, or with large data values for arguments, might be
rejected if the CICS server adapter cannot marshal their values into this
buffer. When the CICS server adapter uses EXCI, a single COMMAREA is
used for the request buffer. The standard EXCI limitation on request size
(that is, 32K) therefore applies. The default is 3200 bytes per buffer.

CICS availability The related configuration item is

plugins:cics_exci:check_if_cics_available. If this is set to yes, CICS
must be available before you start the CICS server adapter in EXCI mode.
The default is no, to allow the CICS server adapter to start even if CICS is not
available.

95
CHAPTER 5 | Configuring the CICS Server Adapter EXCI Plug-In

96
 CHAPTER 6

Configuring the
CICS Server
Adapter APPC
Plug-In
The APPC plug-in for the CICS Server Adapter uses APPC to
pass data into and out of a CICS region. Using this plug-in
therefore enables you to avoid the 32K limit imposed by the
EXCI plug-in. This chapter describes how to configure the CICS
server adapter to use APPC to communicate with CICS.

In this chapter This chapter discusses the following topics:

Setting Up APPC for the CICS Server Adapter page 98

Additional RACF Customization Steps for APPC page 105

APPC Plug-In Configuration Items page 110

97
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Setting Up APPC for the CICS Server Adapter

Prerequisites to using APPC Before you can run an Orbix CICS application in your CICS region, you must
perform a number of additional steps to enable the required APPC
functionality on your z/OS system. Depending on your installation, one or all
of these tasks might already have been completed.

Further reading For more information on setting up APPC/MVS, refer to the IBM publication
MVS Planning: APPC/MVS Management, GC28-107.
Additionally, you can find specific information about defining APPC links in
CICS in the chapter on “Defining APPC Links" in the IBM publication CICS
Intercommunication Guide, SC33-1695.

In this section This section discusses the following topics:

Defining LUs to APPC page 99

Defining an APPC Destination Name for the CICS LU page 100

Defining LUs to VTAM page 102

98
 Setting Up APPC for the CICS Server Adapter

Defining LUs to APPC

Overview An LU (Logical Unit) name identifies each side of an APPC conversation. It
is defined to APPC/MVS in the APPCPMxx member of SYS1.PARMLIB. You must
define at least one LU name to use the CICS server adapter. If you want to
run multiple server adapters you might want to set up separate LUs for each
one.
This subsection discusses the following topics:
• Specifying the LU name
• Specifying the VSAM dataset name
• Location of sample JCL to create a VSAM dataset name
• RACF APPCLU profile name requirement

Specifying the LU name The LU name to be used by the server adapter is only used for outbound
communication. It can therefore be specified as follows:

LUADD ACBNAME(ORXLU02) NOSCHED

Specifying the VSAM dataset The only other requirement in SYS1.PARMLIB(APPCPMxx) is the specification
name of the name of the VSAM data set where APPC-side information can be
found. This data set is used to define APPC destination names. For
example:

SIDEINFO DATASET(SYS1.APPCSI)

Location of sample JCL to create If your installation does not already have one, see SYS1.SAMPLIB(ATBSIVSM)
a VSAM dataset name for sample JCL to create a VSAM dataset name.

RACF APPCLU profile name If you define a new LU for the server adapter’s use (for example, ORXLU02),
requirement that name must be used for the RACF APPCLU profile name. You can use the
plugins:cics_appc:appc_outbound_lu_name configuration item to define a
new LU.

99
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Defining an APPC Destination Name for the CICS LU

Overview The CICS server adapter connects to a CICS region through an APPC
destination name rather than directly through the CICS LU name. This
destination name is used to establish various default characteristics for the
APPC conversation being initiated; including the name of the partner LU,
the transaction program name, and a logon mode name.
This subsection discusses the following topics:
• Storage of the APPC destination name
• Example of the APPC-side information JCL
• Explanation of example JCL

Storage of the APPC destination All this information is stored in the APPC-side information data set. This
name data set is updated using the ATBSDFMU APPC/MVS utility program.

Example of the APPC-side The following is an example of JCL to load an entry into the APPC-side
information JCL information data set.

Example 3: Example of APPC-Side Information JCL

//SIADDEXEC PGM=ATBSDFMU
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=SYS1.APPCSI,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD DATA
SIADD
1 DESTNAME(ORBXCICS)
2 TPNAME(CICS)
3 MODENAME(APPCHOST)
4 PARTNER_LU(CICSTS1)
/*

100
 Setting Up APPC for the CICS Server Adapter

Explanation of example JCL The example APPC-side information JCL can be explained as follows:
1. For the purposes of the CICS server adapter, DESTNAME names the
string that is to be passed to the server adapter when it starts up. The
associated configuration item is
plugins:cics_appc:cics_destination_name.
2. The TPNAME specification names a CICS transaction to run. However,
the server adapter overrides this for each conversation. Therefore, its
value here is not important.
3. The MODENAME parameter names an entry in the VTAM logon mode
table. This specifies other characteristics that are to be used in the
conversation. See the SYS1.SAMPLIB(ATBLMODE)data set for a definition
of the APPCHOST logon mode, and the SYS1.SAMPLIB(ATBLJOB) data set
for the JCL to install it.
4. PARTNER_LU must specify the APPLID of the CICS region to which you
want to connect.

101
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Defining LUs to VTAM

Overview APPC/MVS expects its LUs to be defined as VTAM resources, so that they
can access a SNA network. This subsection discusses the following topics:
• VTAM requirements for LUs
• Using SYS1.SAMPLIB(ATBAPPL)

VTAM requirements for LUs Although the CICS server adapter is only intended to run on the same
system as the CICS region it communicates with (that is, an LU=LOCAL
conversation), VTAM application program definition (APPL) macros must
still be coded for each LU. See SYS1.SAMPLIB(ATBAPPL) for a sample APPL
definition of an APPC LU.

Using SYS1.SAMPLIB(ATBAPPL) The following definitions for the CICS server adapter LU use the
SYS1.SAMPLIB(ATBAPPL) definition, with some changes (which are
highlighted):

Example 4: Example of APPL Definitions for CICS and CICS Server

Adapter LUs

1 ORXLU02 APPL ACBNAME=ORXLU02, C

APPC=YES, C
2 SECACPT=CONV, C
3 VERIFY=OPTIONAL, C
AUTOSES=0, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=LOGMODES, C
PARSESS=YES, C
SRBEXIT=YES, C
VPACING=1

102
 Setting Up APPC for the CICS Server Adapter

1. Both the ACBNAME= parameter and the APPL statement label should
match the LU name defined to APPC. This LU must be supplied to the
APPC-based CICS server adapter via the
plugins:cics_appc:appc_outbound_lu_name configuration item.
2. SECACPT= and VERIFY=, in conjunction with some CICS start-up
options, specify what authentication and access checks are made
when initiating conversations between the LU and CICS. SECACPT=CONV
indicates that a partner LU must provide user and password
information to authenticate itself before being allowed access to
resources on the local system. This protects your CICS region from
unauthorized access by users on other systems in your SNA network.
3. VERIFY=OPTIONAL indicates that the password requirement can be
bypassed if LU-LU session-level verification can be performed. This
allows the server adapter to get access (via the session keys in the
APPCLU profiles described in “Session key” on page 107) to the CICS
region without having to know the passwords of all its clients.

Security considerations If there is no possibility of unauthorized access from other systems in your
SNA network, you might prefer to code SECACPT=ALREADYV and
VERIFY=NONE, indicating that partner LUs do not need to be authenticated.
This is safe for LU=LOCAL conversations, because user information is
provided directly by APPC/MVS, with no opportunity for the programmer of
the partner LU to fabricate his identity.
Refer to “Securing the CICS Server Adapter” on page 211 for more details
about APPC conversation security and session-level verification.

103
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Defining the Required Resources to CICS

Overview This subsection provides the location of the JCL used to define required
APPC resources to CICS. It also provides information about prerequisites to
using this JCL.
This subsection discusses the following topics:
• Location of required JCL
• Prerequisites

Location of required JCL The orbixhlq.JCLLIB(ORBIXCSD) JCL member runs the CICS offline
resource definition utility to define the required APPC resources to CICS.

Prerequisites You might need to change the STEPLIB and DFHCSD DD cards to match your
CICS installation.

104
 Additional RACF Customization Steps for APPC

Additional RACF Customization Steps for

APPC
Overview There are a number of RACF definitions related to APPC that you might
need to add or change to run the CICS server adapter. Refer to “Securing the
CICS Server Adapter” on page 211 for more details about how the server
adapter fits into a secure system environment.
Much of the information provided in this section can be found in the chapter
on “Implementing LU 6.2 Security” in the IBM publication CICS RACF
Security Guide, SC33-1701 CICS RACF Security Guide.

In this section This section discusses the following topics:

Bind Time Security with APPC page 106

Protecting LUs page 108

Link Security & User Security with APPC page 109

105
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Bind Time Security with APPC

Overview When a request to establish an APPC session is received from or sent to a
remote system (that is, when the session is bound), a security check can be
applied. This is called bind-time security and its purpose is to prevent an
unauthorized system from binding a session to one of your CICS systems.
This subsection discusses the following topics:
• Specifying session security at both ends of a connection
• Bind request prerequisites
• Implementing bind-time security
• APPCLU profile name
• Session key
• User IDs and APPCLU profiles

Specifying session security at both When you define an LU 6.2 connection to a remote system, you assume
ends of a connection that all inbound bind requests originate in that remote system, and that all
outbound bind requests are routed to the same system. However, where
there is a possibility that a transmission line might be switched or broken
into, you can guard against unauthorized session binds by specifying session
security at both ends of the connection.

Bind request prerequisites For a bind request to succeed, both ends must hold the same session key,
which is defined to RACF in an APPCLU definition.

Implementing bind-time security To implement bind-time security for your APPC connection, you need to:
• Specify SEC=YES and XAPPC=YES in your system initialization table (SIT)
and recycle CICS to effect the change.
• Change the BINDSECURITY option to YES on the CONNECTION resource
definition in the CSD.
• Define APPCLU RACF definitions with shared session keys as outlined
below.

106
 Additional RACF Customization Steps for APPC

APPCLU profile name Each APPCLU profile name has the form:

’networkid.local-lu-name.partner-lu-name’

and contains information to be used by APPC/MVS on one side of a

conversation between the two named LUs. This means each side of a
conversation has its own specific profile. For example, if LU ORXLU02
initiates a conversation with the CICS region whose APPLID is CICSTS1,
APPC/MVS on the initiating (outbound) side examines the following profile:

‘networkid.ORXLU02.CICSTS1’

and APPC/MVS on the receiving (inbound) side examines this profile:

‘networkid.CICSTS1.ORXLU02’

Session key Each profile includes a session key, which is a string of letters or numbers,
and a CONVSEC setting. When a conversation is initiated between these
two LUs, APPC/MVS on the outbound side passes the session key found in
its profile to APPC/MVS on the inbound side. If APPC/MVS on the inbound
side finds that the received session key matches the session key in its own
profile, it overrides the VTAM SECACPT= setting with the CONVSEC setting
from its profile. In summary, for a bind request to succeed, both ends must
hold the same session key, which is defined to RACF as follows:

RDEFINE APPCLU P390.ORXLU02.CICSTS1

UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))
RDEFINE APPCLU P390.CICSTS1.ORXLU02
UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))

SETROPTS CLASSACT(APPCLU)

User IDs and APPCLU profiles It is not necessary to permit the server adapter or CICS region to have user
IDs for the APPCLU profiles. However, access to the profiles should be tightly
controlled to ensure that only appropriate users can read or change the
session keys.

107
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

Protecting LUs
Overview This subsection discusses the following topics:
• User access to LU names
• Creating RACF APPCPORT profiles

User access to LU names If you have set up the APPCLU profiles that allow a conversation between two
specific LU names to bypass password checking, you should limit the users
that can initiate or received conversations using those LU names.

Creating RACF APPCPORT You can do this by creating RACF APPCPORT profiles for each LU name and
profiles by permitting only certain users access to those profiles. For example:

RDEFINE APPCPORT ORXLU02 UACC(NONE)

PERMIT ORXLU02 CLASS(APPCPORT) ID(Adapter) ACCESS(READ)

SETROPTS CLASSACT(APPCPORT) RACLIST(APPCPORT)

By having an ORXLU02 profile, you are restricting the users that can take
advantage of the session-level verification provided by the APPCLU profiles.

108
 Additional RACF Customization Steps for APPC

Link Security & User Security with APPC

Overview Link security and user security further restricts the resources a user can
access, depending on the remote system from which they are accessed.
This subsection discusses the following topics:
• A bound APPC session
• Specifying ATTACHSEC=

A bound APPC session When an APPC session is bound, each side tells the other the level of
attach-security user verification that is be performed on its incoming
requests. The ATTACHSEC operand on the CONNECTION resource
definition in the CSD specifies the sign-on requirements for incoming
transaction-attach requests.

Specifying ATTACHSEC= If you specify ATTACHSEC=LOCAL, no user ID is supplied by the remote

system. However, if you specify ATTACHSEC=IDENTIFY, a user ID is expected
on every attach request. Depending on how you want to protect your CICS
resources, you might want to change this option. Refer to the CICS RACF
Security Guide for more information.

109
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

APPC Plug-In Configuration Items

Overview This section discusses the following topics:
• CICS APPC destination LU name
• Server adapter outbound LU name
• APPC/CICS transaction request timeout
• Data segment length

CICS APPC destination LU name The related configuration item is

plugins:cics_appc:cics_destination_name. This specifies a symbolic
name that identifies the APPC LU name for the CICS region that the CICS
server adapter connects to. All incoming client requests are forwarded into
the specific CICS region that is associated with this destination name. The
default value is ORBXCICS.
The specified APPC destination name is verified only when the server
adapter first attempts to issue a request to the specified CICS region. This
means that the CICS region does not have to be available when you start the
APPC-based server adapter.

Server adapter outbound LU name The related configuration item is

plugins:cics_appc:appc_outbound_lu_name. This specifies the APPC LU
name that the server adapter uses to initiate communication with CICS. This
is useful when security considerations prohibit APPC connections between
the system base LU and CICS. Refer to “APPC-Based Security
Considerations” on page 229 for more details. Refer to “Defining LUs to
APPC” on page 99 for an example where the LU name is created as
ORXLU02.

APPC/CICS transaction request The related configuration item is plugins:cics_appc:timeout. It specifies

timeout the number of minutes that the CICS server adapter waits for a response
from CICS before cancelling the request. It prevents the server adapter from
having to wait indefinitely for a response from CICS if the transaction has
stopped for some reason. The default is no timeout.

110
 APPC Plug-In Configuration Items

Data segment length The related configuration item is plugins:cics_appc:segment_length. The

CICS server adapter builds up APPC segments of this size. For APPC,
multiple buffers of up to this specified length are used to transmit the data.
The 32K limit for APPC for a single buffer therefore applies, but all the
buffers together can be more than 32K. The default is 32767 bytes per
buffer.

111
CHAPTER 6 | Configuring the CICS Server Adapter APPC Plug-In

112
 CHAPTER 7

Configuring the
CICS Server
Adapter RRS
Plug-In
The RRS plug-in provides integration facilities between the
CORBA OTS service in the CICS server adapter and the
commit/rollback processing of CICS. This chapter provides an
introduction to RRS functionality, shows you how to set up
RRS for the CICS server adapter, and provides details of the
RRS plug-in configuration items.

In this chapter This chapter discusses the following topics:

Introduction to RRS page 114

Setting up RRS for the CICS Server Adapter page 115

RRS Plug-In Configuration Items page 122

113
CHAPTER 7 | Configuring the CICS Server Adapter RRS Plug-In

Introduction to RRS
RRS plug-in functionality This plug-in can only be used in conjunction with the EXCI transport plug-in.
Also, RRS support is only available when using CICS TS 1.3 or higher. The
RRS plug-in only becomes involved in the request if the client sends the
request with a transaction context. The server adapter therefore supports
both transactional and non-transactional requests when the RRS plug-in is
enabled. The transactional performance overheads only affect transactional
requests. With RRS support, the server adapter only commits or rolls back
transactions in CICS when the client program issues the commit or rollback
call for a transactional request.
This section discusses the following topics:
• IORs and transaction support
• Further reading

IORs and transaction support IORs for IDL interfaces that support transactional processing have an extra
component to indicate to the client that transactional support is available in
the server (the server adapter in this case). Ensure that you obtain new IORs
from the CICS server adapter using prepare and resolve, and so on, after you
have enabled the RRS plug-in. This is because transactional communication
between the client program and the server adapter only works with these
new IORs with the transaction support component.

Further reading For further information, refer to the IBM publication OS/390 MVS Setting
up a Sysplex, GC28-1779.
Further information about System Logger is available in the IBM publication
OS/390 MVS Setting up a Sysplex, GC28-1779.

114
 Setting up RRS for the CICS Server Adapter

Setting up RRS for the CICS Server Adapter

Overview This section describes what you need to do to use the RRS plug-in with the
CICS server adapter. It discusses the following topics:
• IPL your z/OS system in Sysplex mode
• Defining the required log streams
• Managing log streams
• Starting RRS
• Stopping RRS
• Restarting CICS when RRS is available on the system

IPL your z/OS system in Sysplex RRS requires the use of a sysplex couple data set, which means that your
mode z/OS system must be configured as part of a single-system or multi-system
sysplex.
The following steps are required:

Step Action

1 Change the PLEXCFG parameter in SYS1.PARMLIB(IEASYSxx) to

PLEXCFG=MONOPLEX for a single-system sysplex or
PLEXCFG=MULTISYSTEM for a multi-system sysplex. PLEXCFG=ANY
is also valid.

2 Specify COUPLExx in SYS1.PARMLIB(IEASYSxx) to identify the

COUPLExx parmlib member that describes the sysplex
environment.

115
CHAPTER 7 | Configuring the CICS Server Adapter RRS Plug-In

Step Action

3 Use the XCF couple dataset format utility (IXCL1DSU) to create

and format all sysplex couple data sets prior to IPLing a system
that is to use them. The following JCL can be used:
//STEP1 EXEC PGM=IXCL1DSU
//STEPLIB DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DEFINEDS SYSPLEX(IONAPLEX)
DSN(SYS1.XCF.CDS01) VOLSER(S27VL1)
MAXSYSTEM(8)
CATALOG
DATA TYPE(SYSPLEX)
ITEM NAME(GROUP) NUMBER(50)
ITEM NAME(MEMBER) NUMBER(120)
ITEM NAME(GRS) NUMBER(1)
DEFINEDS SYSPLEX(IONAPLEX)
DSN(SYS1.XCF.CDS02) VOLSER(S27VL2)
MAXSYSTEM(8)
CATALOG
DATA TYPE(SYSPLEX)
ITEM NAME(GROUP) NUMBER(50)
ITEM NAME(MEMBER) NUMBER(120)
ITEM NAME(GRS) NUMBER(1)
/*

4 Create a COUPLExx member in SYS1.PARMLIB that includes the

couple data sets you have just defined. For example:
COUPLE SYSPLEX(IONAPLEX)
PCOUPLE(SYS1.XCF.CDS01)
ACOUPLE(SYS1.XCF.CDS02)

5 IPL your system for the above changes to take effect.

Defining the required log streams There are two types of log streams:
• Coupling facility log streams.
• DASD-only log streams.
The main difference between the two types of log streams is the storage
medium used to hold interim log data. In a coupling facility log stream,
interim storage for log data is contained in coupling facility list structures. In

116
 Setting up RRS for the CICS Server Adapter

a DASD-only log stream, interim storage for log data is contained in local
storage buffers on the system. For the purposes of this demonstration,
DASD-only log streams are used.

Prerequisites to running the log RRS requires five log streams to be defined to System Logger. The IBM
streams publication OS/390 MVS Programming: Resource Recovery, GC28-1739
lists the following initial and recommended sizes for the log streams:

Table 1: Initial and Maximum Log Stream Sizes

Log Stream Initial Size Maximum Size

RM.Data 1 MB I MB

MAIN.UR 5 MB 50 MB

DELAYED.UR 5 MB 50 MB

RESTART 1 MB 5 MB

ARCHIVE 5 MB 50 MB

The initial sizes listed should be sufficient to run the demonstration, but the
log streams should be set up with the maximum sizes, if possible, to
facilitate future use of RRS on the system. This is because production- level
applications require the maximum sizes listed. Also, the ARCHIVE stream is
not required, but setting it up could help to trace any problems with RRS
later on.

117
CHAPTER 7 | Configuring the CICS Server Adapter RRS Plug-In

Managing log streams Log streams are managed based on the policy information that is placed in
the LOGR couple data set. To do this perform the following steps:

Step Action

1 Create and format the LOGR couple data set. The following JCL
can be used:
//STEP1 EXEC PGM=IXCL1DSU
//STEPLIB DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINEDS SYSPLEX(IONAPLEX)
DSN(SYS1.SLC.FDSS1) VOLSER(S27VL1)
DATA TYPE(LOGR)
ITEM NAME(LSR) NUMBER(100)
ITEM NAME(LSTRR) NUMBER(50)
ITEM NAME(DSEXTENT) NUMBER(20)
DEFINEDS SYSPLEX(IONAPLEX)
DSN(SYS1.SLC.FDSS2) VOLSER(S27VL2)
DATA TYPE(LOGR)
ITEM NAME(LSR) NUMBER(100)
ITEM NAME(LSTRR) NUMBER(50)
ITEM NAME(DSEXTENT) NUMBER(20)
/*

2 Update the SYS1.PARMLIB(COUPLExx) member to include the

LOGR data sets you have just defined. For example:
DATA
TYPE(LOGR)
PCOUPLE(SYS1.SLC.FDSS1)
ACOUPLE(SYS1.SLC.FDSS2)

118
 Setting up RRS for the CICS Server Adapter

Step Action

3 Make the LOGR couple data sets available. You can use either of
the following ways to make the LOGR datasets available to the
system:
♦ IPL the system to activate the newly defined
specifications in the COUPLxx member.
♦ Issue the following SETXCF operator commands to
bring the LOGR data sets online without an IPL:
SETXCF COUPLE,TYPE=LOGR,PCOUPLE=(SYS1.SLC.FDSS1)
SETXCF COUPLE,TYPE=LOGR,ACOUPLE=(SYS1.SLC.FDSS2)

119
CHAPTER 7 | Configuring the CICS Server Adapter RRS Plug-In

Step Action

4 Define the log streams using the IXCMIAPU utility provided in

SYS1.MIGLIB. The following JCL can be used:
//STEP1 EXEC PGM=IXCMIAPU
//STEPLIB DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DATA TYPE(LOGR) REPORT(YES)
DEFINE LOGSTREAM
NAME(ATR.IONAPLEX.ARCHIVE)
HLQ(IXGLOGR) MODEL(NO) LS_SIZE(1024)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(15) AUTODELETE(YES)
DASDONLY(YES)

DEFINE LOGSTREAM
NAME(ATR.IONAPLEX.RM.DATA)
HLQ(IXGLOGR) MODEL(NO) LS_SIZE(1024)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(15) AUTODELETE(YES)
DASDONLY(YES)

DEFINE LOGSTREAM
NAME(ATR.IONAPLEX.MAIN.UR)
HLQ(IXGLOGR) MODEL(NO) LS_SIZE(1024)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(15) AUTODELETE(YES)
DASDONLY(YES)

DEFINE LOGSTREAM
NAME(ATR.IONAPLEX.DELAYED.UR)
HLQ(IXGLOGR) MODEL(NO) LS_SIZE(1024)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(15) AUTODELETE(YES)
DASDONLY(YES)

DEFINE LOGSTREAM
NAME(ATR.IONAPLEX.RESTART)
HLQ(IXGLOGR) MODEL(NO) LS_SIZE(1024)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(15) AUTODELETE(YES)
DASDONLY(YES)
/*

120
 Setting up RRS for the CICS Server Adapter

Starting RRS Perform the following steps to start RRS:

Step Action

1 Update the IEFSSNxx member of SYS1.PARMLIB to add RRS as

a z/OS subsystem as follows:
SUBSYS SUBNAME(RRS)

An IPL is required to activate this change. Dynamic subsystem

definition is not supported by RRS, so you cannot use the
SETSSI ADD,SUBNAME=RRS command to define RRS.

2 Copy SYS1.SAMPLIB(ATRRRS) to SYS1.PROCLIB(RRS)

3 Start RRS by issuing the following operator command:

S RRS

Stopping RRS To stop RRS, issue the following command:

SETRRS CANCEL

Restarting CICS when RRS is Add RRMS=YES to the CICS SIT table. Restart the CICS region. The following
available on the system message must appear in the CICS region output to indicate that CICS has
attached to RRS:

The Resource Recovery Services (RRS) exit manager ATR.EXITMGR.IBM

is now available.

121
CHAPTER 7 | Configuring the CICS Server Adapter RRS Plug-In

RRS Plug-In Configuration Items

Overview This section discusses the following topics:
• Server adapter resource manager name
• Initial reference name for RRS plug-in

Server adapter resource manager The related configuration item is plugins:rrs:rm-name. It specifies the
name resource manager name that the CICS server adapter uses to register with
RRS. The server adapter registers with RRS as a communications resource
manager, because it only forwards transactional requests and does not itself
manage incoming data on a transactional basis (that is, it supports only
communication and is not a database). Each server adapter should have its
own resource manager name that it uses to register with RRS. The resource
manager name should also be in a dot-separated format; for example, as
follows: TEST.CICSADAP1.IONA.UA
According to the rules of RRS on the naming of resource managers, the
resource manager name for the server adapter must be suffixed with .UA.
This indicates to RRS that the server adapter might run without APF
authorization and that it does not use any of the RRS services that require
APF authorization. The second last item in the name should be the
company name that provides this resource manager. Depending on the
naming schemes in your company, this should either be IONA or the name
of your company. Using IONA is usually the best option, to ensure that the
resource manager names do not conflict with resource managers provided
by other companies. The rest of the name should be specified in such a way
that it is unique for each server adapter.
The presence of this configuration item instructs the server adapter to
attempt to load RRS.

Initial reference name for RRS The related configuration item is initial_references:IT_RRS:plugin. It
plug-in specifies that the RRS plug-in should be used for RRS services in the server
adapter. This should always be set to rrs and is a required item if RRS is
used.

122
 CHAPTER 8

Configuring the
CICS Server
Adapter for Client
Principals
The CICS server adapter can be configured to read the client
principal from incoming GIOP 1.0 and 1.1 requests. It can
also be configured to read the principal from a service context
for GIOP 1.2. If the server adapter reads the principal from
the GIOP request, it passes it into CICS for mapped requests.
The server adapter can also run the transaction in CICS under
the user principal obtained from the client. This chapter
explains how to configure the server adapter to use client
principals.

In this chapter This chapter discusses the following topics:

Activating Client Principal Support page 125

Setting up the Required Privileges page 129

123
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

Additional Requirements for CICS Protocol Plug-Ins page 131

Note: See “Securing and Using the CICS Server Adapter” on page 209 for
more details about the use of client principals when running the server
adapter in secure mode.

124
 Activating Client Principal Support

Activating Client Principal Support

Overview For IDL mapped requests, the server adapter marshals the principal data
into CICS, making it available to the Orbix server inside CICS. The server
adapter can also be configured to run the transaction in CICS under this
client’s user ID for both cicsraw requests and mapped requests.
This section discusses the following topics:
• Using CORBA::Principal
• Configuring the cicsa plug-in

Using CORBA::Principal CORBA::Principal has been deprecated by the OMG in GIOP 1.2 and
higher. Hence the principal can only be made available to the server adapter
via GIOP 1.0 or 1.1 client requests. However, GIOP 1.2 can still be used. In
this case, the client must pass the principal string in a service context and
the server adapter must be configured to read the principal from this service
context.

Configuring the cicsa plug-in To configure client_principal support, the following items within the
server adapter’s configuration scope must be reviewed.

125
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

Table 2: Client Principal Support and cicsa Plug-In Configuration Items

(Sheet 1 of 3)

Configuration Item Description

plugins:cicsa:use_client_principal When this item is set to true, the principal is be obtained from
GIOP, truncated to eight characters and converted to uppercase.
The CICS server adapter then also runs the transaction under the
user ID. If no principal is available or it is invalid, the transaction
fails.
Setting this item to true, therefore, instructs the CICS server
adapter to use z/OS services, to assume the identity of the client
when communicating with CICS. This results in CICS and either
APPC or EXCI making their security checks against that user ID. If
this option is not specified, the security checks are made against
the user ID of the server adapter itself. The use of this option
requires that the server adapter has special privileges set up. See
“Securing the CICS Server Adapter” on page 211 for more details
about using this configuration item. When this item is set to
false, the transaction runs under the server adapter's user ID.
When this item is set to true or false, the principal is still
obtained from GIOP and passed as is (apart from being converted
from ASCII to EBCDIC) to the transaction inside CICS, if cicsraw
is not being used. If the client principal is not available from
GIOP, it is not passed as part of the request to CICS, but the
transaction is still executed.
The default is false.

plugins:cicsa:use_client_principal_ This is used only with CICS EXCI. When this item is set to true,
user_security the CICS server adapter is to provide the client principal user ID
rather than its own user ID on the request to start the target CICS
program.
The default is false.

126
 Activating Client Principal Support

Table 2: Client Principal Support and cicsa Plug-In Configuration Items

(Sheet 2 of 3)

Configuration Item Description

plugins:cicsa:use_client_password When this item is set to yes, it indicates that the CICS server
adapter should use a client password when it wants to switch the
thread that is making the request to CICS to the user ID passed in
the client principal, instead of using SURROGAT rights. The format
of the principal sent by the client application must then take the
form userid;password (that is, user ID and password separated
by a colon) instead of the normal userid format.
When using this option, there is a risk that the password might be
displayed in the CICS server adapter output or that the password
might be obtained from the IIOP message on the network if TLS is
not used. You should therefore consider these security
implications before using this configuration item to send
passwords from the client. The default is no.

policies:iiop:server_version_policy If this is set to 1.1, the server adapter publishes a version 1.1 IOR
which instructs clients to communicate over GIOP 1.1. In this
case, the principal is transmitted in the CORBA::Principal field.
If this is set to 1.2 (the default), 1.2 is used as the default GIOP
version. In this case, the principal must be transmitted in the
request message using an alternative mechanism (that is, a
service context).
Note: Orbix does not support publishing 1.0 version IORs.
Therefore, this configuration item must be set to 1.1 or 1.2.
Note: Even if this configuration item is set to 1.2, clients may
still choose to communicate using a lower GIOP version, if the
client ORB is capable of parsing a 1.2 IOR. For example, Orbix
clients can use the policies:iiop:client_version_policy
configuration item to communicate with the server adapter over
GIOP 1.0 or 1.1.

policies:giop:interop_policy:enable For GIOP 1.2, if this item is set to true, it instructs the CICS
_principal_service_context server adapter to look for the principal string in a service context.
The default value is false.

127
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

Table 2: Client Principal Support and cicsa Plug-In Configuration Items

(Sheet 3 of 3)

Configuration Item Description

policies:giop:interop_policy: This item specifies the service context ID from which the CICS
principal_service_context_id server adapter attempts to read the principal string if
policies:giop:interop_policy:enable_principal_service
_context is set to true. The default service context ID where the
server adapter looks for the principal string is 0x49545F44.

128
 Setting up the Required Privileges

Setting up the Required Privileges

Overview If the CICS server adapter is to be run using the use_client_principal
configuration item in the APPC or EXCI plug-ins, the user ID under which
the server adapter runs might need to be granted special privileges to enable
thread-level security environments. The requirements vary, depending on
whether the FACILITY RACF class profile BPX.SERVER is defined on your
system.
This section discusses the following topics:
• Requirements when BPX.SERVER is defined
• Requirements when BPX.SERVER is not defined
• Impersonating users

Requirements when If BPX.SERVER is defined, the user ID does not need to have a UID of 0, but it
BPX.SERVER is defined must have READ access to the BPX.SERVER profile. In addition, the server
adapter executable must reside in a z/OS load library that is PADS-defined.
(PADS is the acronym for Program Access to Data Sets.)

Requirements when If BPX.SERVER is not defined, this user ID must have a UID of 0 assigned to it
BPX.SERVER is not defined in the OMVS segment of its RACF user profile.

Impersonating users Additionally, because the CICS server adapter is processing requests for
users without having their passwords, you must activate the SURROGAT RACF
class and define profiles in it that allow the server adapter’s user ID to
impersonate particular users. You can do this by establishing a profile for
each potential client user. For example:

RDEFINE SURROGAT BPX.SRV.client1 UACC(NONE)

PERMIT BPX.SRV.client1 CLASS(SURROGAT) ID(Adapter) ACCESS(READ)
RDEFINE SURROGAT BPX.SRV.client2 UACC(NONE)
PERMIT BPX.SRV.client2 CLASS(SURROGAT) ID(Adapter) ACCESS(READ)

129
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

Alternatively, you might want to use a generic profile that allows the CICS
server adapter to impersonate any client user. For example:

RDEFINE SURROGAT BPX.SRV.* UACC(NONE)

PERMIT BPX.SRV.* CLASS(SURROGAT) ID(Adapter) ACCESS(READ)

Access to such profiles should be very tightly controlled.

130
 Additional Requirements for CICS Protocol Plug-Ins

Additional Requirements for CICS Protocol

Plug-Ins
Overview When running authorized and using the use_client_principal
configuration item in the APPC or EXCI plug-in, the CICS server adapter
changes the ID of the thread processing the request to that of the client
principal. It then makes the request under the new ID; so, in this case, the
request should start the CICS transaction with an ACEE for the client ID.
This section discusses the following topics:
• Switching threads
• Making the CICS server adapter program-controlled
• Further Reading

Switching threads The CICS server adapter uses the pthread_security_np() call on the thread
that is processing the client request, to switch that thread to run under the
requested user ID (client principal). For EXCI, it then issues the EXCI call,
providing this ID in the request. For APPC, it issues the APPC calls now that
the thread is running under this user ID. For this to work, an EXCI or APPC
server adapter must be program-controlled.

131
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

Making the CICS server adapter To make the CICS server adapter program-controlled, you need to consider
program-controlled the following issues:

Step Action

1 If the CICS server adapter user ID does not have READ access
to the BPX.SERVER RACF resource, in the FACILITY class, you
get the EPERM errors when the server adapter is trying to switch
identities on the thread. The server adapter user ID also needs
access to the BPX.SRV.userid resource in the RACF SURROGAT
class where userid is the client principal in question. If the
user ID under which the server adapter runs is well controlled,
you could possibly give it read access to the BPX.SRV.*
resource, to enable the server adapter to handle requests from
any client principal.

2 When deploying in UNIX System Services, the CICS server

adapter must run in its own address space. You must ensure
that the _BPX_SHAREAS variable is not set in the server adapter's
environment. The itcicsa shell script supplied by Orbix
Mainframe handles this, by unsetting this variable before
running the server adapter program.

3 When deploying in UNIX System Services, you must ensure

that any UNIX System Services files that are involved in
running the server adapter have the appropriate extended
attributes set. Your systems programmer might execute the
extattr command, as follows, to make these files
program-controlled:
$ cd $IT_PRODUCT_DIR
$ extattr +p shlib/* asp/Version/bin/itcicsa
The command ls -E can be used to display the extended file
attributes in the UNIX System Services shell.
Note: If, at this point, the address space is still not
program-controlled, the server adapter throws an exception
back to the client and logs an error message to indicate that it
could not switch to that user ID, and that it is therefore not
going to attempt to start the transaction in CICS.

132
 Additional Requirements for CICS Protocol Plug-Ins

Further Reading Refer to the IBM publication Planning: OpenEdition MVS, SC23-3015 for
more information on enabling thread-level security for servers.

133
CHAPTER 8 | Configuring the CICS Server Adapter for Client Principals

134
 CHAPTER 9

Configuring the
Orbix Runtime in
CICS
This chapter provides information on configuring the Orbix
runtime that is used by Orbix servers running in CICS.

In this chapter This chapter discusses the following topics:

Customizing CICS page 136

Customizing Orbix Event Logging page 138

135
CHAPTER 9 | Configuring the Orbix Runtime in CICS

Customizing CICS
Overview Before you can run Orbix CICS applications in your region, you must perform
a number of additional steps to enable your CICS system to support Orbix
servers. Depending on your installation, one or all of these tasks might
already have been completed. You must verify this with the systems
programmer responsible for CICS at your site.
This section discusses the following topics:
• Installing language environment support
• Installing support for C++ classes in CICS
• Installing sample Orbix CICS resource definitions
• Updating the CICS region

Installing language environment CICS Language Environment (LE) support is not installed as standard. To
support enable LE support in CICS you must perform a number of steps. Refer to the
IBM manual Language Environment for OS/390 Customization for details
on installing LE support in CICS.
If LE support has been successfully installed in CICS, the following message
is written to the console:

DFHAP1203I CICS Language Environment is being initialized

If you cannot see this message, LE support is not available under CICS and
any Orbix activities fail.

Installing support for C++ classes Support for the C++ standard classes must be explicitly defined to CICS.
in CICS Refer to the IBM manual OS/390 C/C++ Programming Guide for details of
the steps required to run C++ application programs under CICS. In
particular, note that the standard C++ DLLs such as IOSTREAM must be
defined to CICS.
Failure to do this results in the following messages being issued from CICS
when attempting to run an Orbix CICS transaction:

EDC6063I DLL name is IOSTREAM

EDC5207S Load request for DLL load module unsuccessful.

136
 Customizing CICS

C++ support is required by Orbix itself, which is written in C++.

Note: From the Orbix CICS programming perspective, servers can only be
written in COBOL or PL/I at this time.

Installing sample Orbix CICS The data set orbixhlq.JCLLIB(ORBIXCSD) contains a job to run DFHCSDUP,
resource definitions which is the CICS offline resource definition utility, to define the CICS
resources used by the sample jobs and demonstrations. You can run this as
is, or just use it as a reference when defining the resources online with the
CEDA transaction. When the resources have been defined, use CEDA to
install the whole group.

Updating the CICS region To update the CICS region perform the following steps.

Step Action

1 Add five libraries to the CICS region’s DFHRPL concatenation as

follows:
DD DSN=orbixhlq.DEMO.CICS.CBL.LOADLIB,DISP=SHR
DD DSN=orbixhlq.DEMO.CICS.PLI.LOADLIB,DISP=SHR
DD DSN=orbixhlq.MFA.LOADLIB,DISP=SHR
DD DSN=CEE.SCEERUN,DISP=SHR
DD DSN=CBC.SCLBDLL,DISP=SHR

2 Add CEE.SCEERUN to the STEPLIB concatenation.

3 Recycle the regions to pick up these libraries.

137
CHAPTER 9 | Configuring the Orbix Runtime in CICS

Customizing Orbix Event Logging

Overview For the Orbix runtime in CICS, most of the configuration settings are fixed.
However, the level of event logging performed by the runtime can be
customized for the server adapter.
This section discusses the following topics:
• Customizing the level of event logging
• Event logging settings
• ORXMFACx DLL setting
• Modifying the ORXMFACx DLL setting

Customizing the level of event This is done by modifying the ORXMFACx DLL. This DLL contains an S390
logging Assembler CSECT that supplies the event logging string to the runtime.

Event logging settings The event logging settings are as follows:

Table 3: Event Logging Settings for the CICS Server Adapter

Value Description

0 LOG_NONE— no logging in CICS is performed.

1 LOG_ERROR—only log errors.

2 LOG_WARNING—log warnings and errors.

3 LOG_INFO_HIGH—log high priority informational messages,

warnings and errors.

4 LOG_INFO_MED—log medium priority informational messages,

high priority informational messages, warnings and errors.

5 LOG_INFO_LOW—log low priority informational messages,

medium priority informational messages, high priority
informational messages, warnings and errors.

6 LOG_INFO_ALL—log all messages.

138
 Customizing Orbix Event Logging

ORXMFACx DLL setting The ORXMFACx DLL shipped with the CICS server adapter has a setting of 2
for event logging in CICS.
This can be modified to some other setting. For example, to help trace a
problem with a transaction in CICS, it can be changed to 6.

Modifying the ORXMFACx DLL This is done using the MFACLINK JCL member supplied in orbixhlq.JCLLIB.
setting In this JCL, the LOGLVL variable can be modified to contain the new event
logging value. It can then be run to create a new version of the ORXMFACx
DLL with this new value. Ensure that you make a backup copy of ORXMFACx,
before running this JCL member. After this re-link of the DLL, make it
available to the CICS region in which you are testing, for the new setting to
come into effect. After the testing is complete, consider copying back the
original DLL, to revert to the normal logging levels.

139
CHAPTER 9 | Configuring the Orbix Runtime in CICS

140
 CHAPTER 10

IDL Compiler
Configuration
This chapter describes Orbix IDL compiler settings for the mfa
plug-in, which is used to generate CICS server adapter
mapping files and type_info files.

In this chapter This chapter discusses the following topics:

Orbix IDL Compiler Settings page 142

141
CHAPTER 10 | IDL Compiler Configuration

Orbix IDL Compiler Settings

Overview The -mfa plug-in allows the Orbix IIDL compiler to generate CICS server
adapter mapping members and CICS server adapter type_info files from IDL.
The behavior of the Orbix IDL compiler is defined by the IDL compiler
configuration file, orbixhlq.CONFIG(IDL). This chapter details the default
settings used and describes how these can be modified.

Note: IDL compiler configuration is separate from standard Orbix

configuration and is contained in its own configuration member
(orbixhlq.CONFIG(IDL)).

Configuration settings The CICS server adapter mapping member configuration is listed under
MFAMappings as follows:

MFAMappings
{
Switch = "mfa";
ShlibName = "ORXBMFA";
ShlibMajorVersion = "6";
IsDefault = "NO";
PresetOptions = "";

# Mapping & Type Info file suffix and ext. can be overridden
# The default mapping file suffix is A
# The default mapping file ext. is .map and none for OS/390
# The default type info file suffix is B
# The default type info file ext. is .inf and none for OS/390
# MFAMappingExtension = "";
# MFAMappingSuffix = "";
# TypeinfoFileExtension = "";
# TypeinfoFileSuffix = "";

};

Note: Settings listed with a # are considered to be comments and are not
in effect.

142
 Orbix IDL Compiler Settings

Mandatory settings The first three of the preceding settings are mandatory and must not be
altered. They inform the Orbix IDL compiler how to recognize the server
adapter mapping member switch, and what name the DLL plug-in is stored
under.

User-defined settings All but the first three settings are user-defined and can be changed. The
reason for these user-defined settings is to allow you to change, if you want,
default configuration values that are set during installation. To enable a
user-defined setting, use the following format:

setting_name = "value";

List of available settings Table 4 provides an overview and description of the available settings.

Table 4: Server Adapter Mapping Member Configuration Settings

Setting Name Description Default

IsDefault Indicates whether the Orbix IDL NO

compiler generates CICS server
adapter mapping members by
default from IDL. If this is set to
YES, you do not need to specify
the -mfa switch when running
the compiler.

PresetOptions The arguments that are passed

by default as parameters to the
Orbix IDL compiler for the
purposes of generating CICS
server adapter mapping
members.

MFAMappingExtension Extension for the CICS server

adapter mapping file (on UNIX map
System Services).

TypeinfoFileExtension Extension for the CICS server inf

adapter type_info files (on
UNIX System Services).

143
CHAPTER 10 | IDL Compiler Configuration

Table 4: Server Adapter Mapping Member Configuration Settings

Setting Name Description Default

TypeinfoFileSuffix Suffix for CICS server adapter

type_info files (on both native B
z/OS and UNIX System
Services). If you do not supply a
value for this, a default suffix of B
is used.

MFAMappingSuffix Suffix for the CICS server adapter

mapping member on z/OS. If you A
do not specify a value for this, a
default suffix of A is used.

144
 Part 3
Configuring the Client
Adapter and the Orbix
Runtime in CICS
In this part This part contains the following chapters:

Introduction to Client Adapter Configuration page 147

Client Adapter General Configuration page 157

Configuring the Client Adapter AMTP_APPC Plug-in page 161

Configuring the Client Adapter AMTP_XMEM Plug-in page 183

Configuring the Client Adapter Subsystem page 193

Configuring the Orbix Runtime in CICS page 197

 CHAPTER 11

Introduction to
Client Adapter
Configuration
This chapter provides information needed to configure the
client adapter and its components (plug-ins). It provides
descriptions of all the configuration items involved in running
the client adapter. It also provides details on configuring the
various system components used by the client adapter.

In this chapter This chapter discusses the following topics:

A Client Adapter Sample Configuration page 148

Configuration Summary of Client Adapter Plug-Ins page 151

147
CHAPTER 11 | Introduction to Client Adapter Configuration

A Client Adapter Sample Configuration

Overview A sample configuration member is supplied with your Orbix Mainframe
installation that provides an example of how you might configure and deploy
the client adapter on both native z/OS and UNIX System Services.
This section discusses the following topics:
• Location of configuration templates
• Configuration scope
• Configuration scope example
• Configuring a domain

Location of configuration Sample configuration templates are supplied with your Orbix Mainframe
templates installation in the following locations:
• Non-TLS: orbixhlq.CONFIG(BASETMPL)
• TLS: orbixhlq.CONFIG(TLSTMPL).

Note: Further configuration resides in orbixhlq.CONFIG(ORXINTRL). This

contains internal configuration that should not usually require any
modifications.

Configuration scope The client adapter uses one of the following ORB names:

Table 5: Client Adapter ORB Names

ORBname Transport

iona_services.cics_client APPC

iona_services.cics_client.cross_memory Cross memory

communication

The items specific to the client adapter configuration are scoped in these
configuration scopes.

148
 A Client Adapter Sample Configuration

Configuration scope example The following is an example of the iona_services.cics_client

configuration scope. It includes the cross_memory sub-scope, which is used
for the cross memory communication transport.

Example 5: An iona_services.cics_client Configuration Scope Example

iona_services
{…
cics_client
{
event_log:filters = ["*=WARN+ERROR+FATAL","IT_MFA=INFO_HI+WARN+ERROR+FATAL",
"IT_MFU=INFO_HI+WARN+ERROR+FATAL"];

plugins:cicsa:direct_persistence = "yes";
plugins:cicsa:iiop:host = "%{LOCAL_HOSTNAME]";
plugins:cicsa:iiop:port = "5072";

plugins:client_adapter:repository_id = "type_info";
plugins:client_adapter:type_info:source = "DD:TYPEINFO";

orb_plugins = ["local_log_stream", "iiop_profile", "giop", "iiop", "ots",

"amtp_appc"];

# Client Adapter amtp_appc plugin

plugins:amtp_appc:symbolic_destination = "ORXCLNT1";
plugins:amtp_appc:appc_function_wait = "5";
plugins:amtp_appc:min_comm_threads = "5";
plugins:amtp_appc:max_comm_threads = "10";

#For two-phase commit support uncomment the following lines:

#plugins:amtp_appc:maximum_sync_level = "2";
#initial_references:TransactionFactory:reference = "%{LOCAL_OTSTM_REFERENCE}";

# Client Adapter mfu plugin

plugins:ots_lite:use_internal_orb = "true";
plugins:ots_lite:orb_name= "iona_services.cics_client.ots";

ots
{
orb_plugins = ["local_log_stream", "iiop_profile", "giop", "iiop"];
};

149
CHAPTER 11 | Introduction to Client Adapter Configuration

Example 5: An iona_services.cics_client Configuration Scope Example

# Cross memory transport

cross_memory
{
orb_plugins = ["local_log_stream", "iiop_profile", "giop"
"iiop", "amtp_xmem"];

plugins:amtp_xmem:symbolic_destination = "ORXCLNT1";
plugins:amtp_xmem:min_comm_threads = "5";
plugins:amtp_xmem:max_comm_threads = "10";
plugins:amtp_xmem:max_segment_size = "32760";
};
}
};

Configuring a domain Refer to the CORBA Administrator’s Guide for details on how to configure
an Application Server Platform domain.

150
 Configuration Summary of Client Adapter Plug-Ins

Configuration Summary of Client Adapter

Plug-Ins
Overview Orbix configuration allows you to configure an application on a per-plug-in
basis. This section provides a summary of the configuration items
associated with plug-ins specific to the client adapter.
This section discusses the following topics:
• Client adapter components
• Summary of items for the amtp_appc plug-in
• Summary of items for the amtp_xmem plug-in
• Summary of items for the client adapter subsystem
• Summary of remaining configuration items

Client adapter components The main components of the client adapter include:
• A client adapter subsystem, which is loaded by the adapter executable
(many subsystems can be run by the same application).
• The amtp_appc plug-in, which is used to provide APPC transport
between CICS client transactions and the client adapter.
• The amtp_xmem plug-in, which is used to provide cross memory
communication transport between CICS client transactions and the
client adapter.
• The common_adapter plug-in, which exposes common functionality
such as support for different signature repositories (that is, type_info,
IFR, and so on).

151
CHAPTER 11 | Introduction to Client Adapter Configuration

Summary of items for the The following is a summary of the configuration items associated with the
amtp_appc plug-in amtp_appc plug-in. Refer to “AMTP_APPC Plug-In Configuration Items” on
page 180 for more details.
symbolic_destination Specifies the APPC/MVS symbolic destination name
the client adapter uses for APPC services. The Orbix
Runtime in CICS uses the symbolic destination to
send CICS client transaction requests to the client
adapter. The default value is “ORXCLNT1”.
appc_function_wait Specifies the number of minutes that the client
adapter can wait for a response from a CICS client
transaction before canceling the request. Valid
values are in the range 0–1440. The default value is
5 minutes.
min_comm_threads Specifies the minimum number of client adapter
threads used to service requests from CICS client
transactions. Each thread processes a request from
a CICS client transaction. A valid value is greater
than 0. The default value is 5 threads.
max_comm_threads Specifies the maximum number of client adapter
threads that can be used to service requests from
CICS client transactions. If all client adapter threads
are busy, and the client adapter receives another
request, it dynamically starts more threads up to
this maximum number. The default value is 10
threads.
maximum_sync_level Specifies the maximum APPC synchronization level
supported by the client adapter. The value can be 0
or 2. A value of 0 does not allow CICS client
transactions to perform two-phase commit
processing. A value of 2 allows CICS client
transactions to perform two-phase commit
processing. The default value is 0.

152
 Configuration Summary of Client Adapter Plug-Ins

Summary of items for the The following is a summary of the configuration items associated with the
amtp_xmem plug-in amtp_xmem plug-in. Refer to “AMTP_XMEM Plug-In Configuration Items” on
page 191 for more details.

Note: The cross memory transport does not support two-phase commit
processing.

symbolic_destination This is a symbolic name that identifies the CICS

client adapter. It can be up to eight characters in
length. The Orbix runtime in CICS is configured to
use this destination. CICS client transactions have
their requests sent to the client adapter using this
symbolic destination. The default value is
ORXCLNT1.
Note: The value for this configuration item must
be unique for each instance of the client adapter.
Unlike APPC, the cross memory communication
plug-in does not allow multiple instances of the
client adapter to use the same symbolic
destination.
min_comm_threads Specifies the minimum number of client adapter
threads used to service requests from CICS client
transactions. Each thread processes a request from
a CICS client transaction. A valid value is greater
than 0. The default value is 5 threads.
max_comm_threads Specifies the maximum number of client adapter
threads that can be used to service requests from
CICS client transactions. If all client adapter
threads are busy, and the client adapter receives
another request, it dynamically starts more threads
up to this maximum number. The default value is
10 threads.

153
CHAPTER 11 | Introduction to Client Adapter Configuration

max_segment_size Specifies the maximum segment size that the

client adapter can receive from a client. The Orbix
runtime in CICS is configured with a maximum
segment size. The client adapter might be
servicing one or more CICS regions. The value for
plugins:amtp_xmem:max_segment_size must be
equal to or greater than the largest segment size
defined in the configuration for the Orbix runtime
in CICS.

Summary of items for the client The following is a summary of the configuration items associated with the
adapter subsystem client adapter subsystem. Refer to “Configuring the Client Adapter
Subsystem” on page 193 for more details.
repository_id Specifies the type information source to use. This
source supplies the CICS client adapter with
operation signatures as required. Valid values are
ifr and type_info. The default is ifr. Refer to
“Type information mechanism” on page 194 for
more information.
ifr:cache This value is used if repository_id is set to ifr.
The ifr:cache configuration item is optional. It
specifies the location of an (operation) signature
cache file. This signature cache file contains a cache
of operation signatures from a previous run of this
client adapter. The default is no signature cache file
(" ").
type_info:source This value is used if repository_id is set to
type_info. The type_info:source variable denotes
the location of a type_info store from which the
client adapter can obtain operation signatures. Refer
to “type_info store” on page 195 for more
information.

154
 Configuration Summary of Client Adapter Plug-Ins

Summary of remaining The following is a summary of the remaining configuration items. Refer to
configuration items “Client Adapter General Configuration” on page 157 and the CORBA
Administrator’s Guide for more details.
event_log:filters Specifies the types of events the client adapter
logs.
orb_plugins List of standard ORB plug-ins the client adapter
should load.
initial_references: Specifies the IOR of the RRS OTSTM service that
TransactionFactory: coordinates two-phase commit processing
reference initiated by CICS client transactions. The IOR is
obtained by running orbixhlq.JCLLIB(DEPLOY3).
See the Mainframe Installation Guide for more
details. The RRS OTSTM service must be running
if a CICS client transaction is to be able to perform
two-phase commit processing.

155
CHAPTER 11 | Introduction to Client Adapter Configuration

156
 CHAPTER 12

Client Adapter
General
Configuration
This chapter provides details of the configuration items for the
core client adapter. These details specify the level of Orbix
event logging and plug-ins to be loaded when the ORB is
initializing.

In this chapter This chapter discusses the following topics:

Client Adapter Configuration Settings page 158

157
CHAPTER 12 | Client Adapter General Configuration

Client Adapter Configuration Settings

Overview This section discusses the following topics:
• Orbix event logging
• WTO announce plug-in
• ORB plug-ins list

Orbix event logging The related configuration item is event_log:filters. It specifies the level of
event logging. To obtain events specific to the client adapter, the IT_MFU
event logging subsystem can be added to this list. For example:

event_log:filters = ["*=WARN+ERROR+FATAL", "IT_MFU=INFO_HI+INFO_MED+WARN+ERROR+FATAL"];

This logs all IT_MFU events (except for INFO_LOW — low priority informational
events), and any warning, error, and fatal events from all other subsystems
(for example, IT_CORE, IT_GIOP, and so on). The level of detail provided for
IT_MFU events can be controlled by setting the relevant logging levels. Refer
to the CORBA Administrator’s Guide for more details.
The following is a categorization of the informational events associated with
the IT_MFU subsystem.
INFO_HI Configuration settings and client adapter start-up and shutdown
messages
INFO_MED APPC informational messages
INFO_LOW CICS segment data streams and two-phase commit events.

158
 Client Adapter Configuration Settings

WTO announce plug-in Orbix applications may be configured to write messages to the operator
console on starting or shutting down successfully. This can be useful for
automated operations software to keep track of these events. The WTO
announce plug-in is used to implement this feature.
To enable the loading of the WTO announce plug-in in an Orbix service,
such as the client adapter, add the following two configuration items in the
iona_services.cics_client scope:
• initial_references:IT_WTO_Announce:plugin = "wto_announce";
• generic_server:wto_announce:enabled = "true";

Note: For customer-developed Orbix applications (for example, a batch

COBOL or PL/I server), the wto_announce plug-in should be added to the
end of the orb_plugins list in that particular application’s ORB
configuration. (See “ORB plug-ins list” next for more details.) However, for
all Orbix services (by default, within the iona_services configuration
scope), it is recommended that you load the wto_announce plug-in by
specifying the two preceding configuration items rather than by adding the
wto_announce plug-in to the orb_plugins list.

When you load the WTO announce plug-in, a WTO message is issued when
the server adapter ORB starts up and shuts down. Messages take the
following format:

+ORX2001I ORB iona_services.cics_client STARTED

(HOSTNAME:<process id>)
+ORX2002I ORB iona_services.cics_client ENDED (HOSTNAME:
<process id>)

On z/OS UNIX System Services, <process id> is a PID. On native z/OS,

<process id> is a job name and an A=xxxx job identifier.

159
CHAPTER 12 | Client Adapter General Configuration

ORB plug-ins list The related configuration item is orb_plugins. It specifies the ORB-level
plug-ins that should be loaded into your application at ORB_init() time. On
z/OS, you can add the WTO announce plug-in support to any Orbix
application by updating this list in the relevant configuration scope. For
example, in the iona_services.cics_client scope:

orb_plugins = ["local_log_stream", "iiop_profile", "giop",

"iiop", "ots", "amtp_appc", "wto_announce"];

In the case of the CICS client adapter’s configuration (that is, in the
iona_services.cics_client scope) the wto_announce plug-in should not
be included in this list, as discussed in “WTO announce plug-in” on
page 159.

160
 CHAPTER 13

Configuring the
Client Adapter
AMTP_APPC
Plug-in
The AMTP_APPC plug-in for the client adapter uses APPC to
communicate with client transactions. This chapter describes
how to configure APPC for CICS, and the client adapter
AMTP_APPC plug-in configuration.

In this chapter This chapter discusses the following topics:

Setting Up APPC for the Client Adapter page 162

Additional RACF Customization Steps for APPC page 176

AMTP_APPC Plug-In Configuration Items page 180

161
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Setting Up APPC for the Client Adapter

Prerequisites to using APPC Before you can run the client adapter, you must first enable the required
APPC functionality on your z/OS system. Depending on your installation, one
or all of these tasks might already have been completed.

Further reading For more information on setting up APPC/MVS, refer to the IBM publication
MVS Planning: APPC/MVS Management, GC28-107.
Additionally, you can find specific information about defining APPC links in
CICS in the chapter on “Defining APPC Links" in the IBM publication CICS
Intercommunication Guide, SC33-1695.

In this section This section discusses the following topics:

Defining LUs to APPC page 163

Defining an APPC Destination Name for the Client Adapter page 166

Defining LUs to VTAM page 170

Defining the Required Resources to CICS page 175

162
 Setting Up APPC for the Client Adapter

Defining LUs to APPC

Overview A Logical Unit (LU) name identifies each side of an APPC conversation. It is
defined to APPC/MVS in the APPCPMxx member of SYS1.PARMLIB. You must
define at least one LU name to use the client adapter—the LU used by the
client adapter.

Note: CICS client transactions use the system base LU for their side of
the conversations with the client adapter.

This subsection discusses the following topics:

• CICS local LU
• Client adapter LU
• Specifying the APPC/MVS-side information dataset name
• Client adapter LU name and security
• Running multiple client adapters

CICS local LU CICS does not define a local LU for transactions that use APPC/MVS. When
a CICS transaction issues a request to allocate a conversation, APPC/MVS
determines which local LU to use. For CICS client transactions, this is the
system base LU.
For information on how APPC/MVS chooses its local LU, see the description
on the allocate callable service in the chapter on “APPC/MVS TP
Conversation Callable Services” in the IBM publication Writing Transaction
Programs for APPC/MVS, GC28-1775.
An example of a system base LU is:

LUADD ACBNAME(MVSLU01)
SCHED(ASCH)
BASE
TPDATA(SYS1.APPCTP)
TPLEVEL(USER)

The definition of MVSLU01—the system base LU—is provided here as an

example. This LU (perhaps with a different name) should already be
defined.

163
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Client adapter LU The client adapter LU is used by the client adapter to receive requests from
CICS client transactions, and to return replies back to CICS client
transactions. It can be defined as follows:

LUADD ACBNAME(ORXLUCA1)
NOSCHED

Specifying the APPC/MVS-side The APPC/MVS side information dataset contains APPC symbolic
information dataset name destination names. If your installation does not have a side information
dataset, see SYS1.SAMPLIB(ATBSIVSM) for sample JCL to create one.
The name of the side information dataset must be defined in
SYS1.PARMLIB(APPCPMxx) (for example, SIDEINFO DATASET(SYS1.APPCSI)).

Note: If you are using the CICS APPC plug-in for the CICS server adapter,
this step might already have been performed.

Client adapter LU name and If you choose to secure the LU used by the client adapter, be aware that the
security LU name is used as part of the APPCLU RACF profile name for the LU. Refer
to “Bind Time Security with APPC” on page 106 for more information.

Running multiple client adapters If you want to run multiple client adapters, you must first decide if you want
the client adapters to share APPC/MVS allocation queues.
APPC/MVS allocation queues hold requests to start APPC conversations. As
client transactions initiate requests to the client adapter, they are first
placed in an APPC/MVS allocation queue. The requests designate which LU
and Transaction Program Name (TPN) they are destined for. The client
adapter registers with APPC/MVS and specifies the LU and TPN requests it
expects to process. (Refer to “Defining an APPC Destination Name for the
Client Adapter” on page 166 for details of how to set up the LU and TPN
name used by the client adapter.) APPC/MVS delivers the requests from the
allocation queue to the client adapter.
You can choose to run multiple client adapters that specify the same LU and
TPN. The client adapters all share the same APPC/MVS allocation queue.
APPC/MVS chooses one of the client adapters to deliver the request to. This
approach can be used as a form of load balancing where the load is spread

164
 Setting Up APPC for the Client Adapter

over multiple client adapters. This approach also provides a measure of fault
tolerance. If a client adapter is stopped or goes down, allocation requests
from client transactions can still be processed by the other client adapters.
You can alternatively choose to run multiple client adapters where each
client adapter specifies a different LU and TPN. The client adapters all have
their own APPC/MVS allocation queue. This approach is useful for setting up
a test client adapter along with a production client adapter. The Orbix
runtime inside the test CICS region is configured to direct allocation requests
to the test client adapter, while the Orbix runtime inside the production CICS
region is configured to direct allocation requests to the production client
adapter.

165
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Defining an APPC Destination Name for the Client Adapter

Overview A CICS client transaction connects to the client adapter through an APPC
destination name rather than directly through the client adapter LU name.
The APPC destination name is used to establish various default
characteristics for the APPC conversation being initiated, including the
name of the partner LU, the TPN, and a logon mode name.
This subsection discusses the following topics:
• Storage of the APPC destination name
• Example of the APPC destination name JCL
• Explanation of the APPC destination name JCL
• Example of multiple APPC destination names JCL
• Explanation of multiple APPC destination names JCL

Storage of the APPC destination The APPC destination name information is stored in the APPC-side
name information data set. This data set is updated using the ATBSDFMU
APPC/MVS utility program.

Example of the APPC destination The following is an example of defining an APPC destination name.
name JCL

Example 6: JCL Example for Defining an APPC Destination Name

//SIADDEXEC PGM=ATBSDFMU
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=SYS1.APPCSI,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD DATA
SIADD
1 DESTNAME(ORXCLNT1)
2 TPNAME(ORXCLNT1)
3 MODENAME(APPCHOST)
4 PARTNER_LU(ORXLUCA1)
/*

166
 Setting Up APPC for the Client Adapter

Explanation of the APPC The JCL example for defining an APPC destination name can be explained
destination name JCL as follows:
1. The DESTNAME is a symbolic name that contains the TPNAME, MODENAME,
and PARTNER_LU. It is used in two places:
♦ The Orbix runtime inside CICS configuration specifies which
destination name the CICS region uses for APPC communication
with the client adapter.
♦ The amtp_appc plug-in configuration item symbolic_destination,
which tells the client adapter which LU and TPN to use for APPC
communication. The LU/TPN define the APPC/MVS allocation
queue from which the client adapter receives allocation requests.
2. The TPNAME specification forms part of the APPC/MVS allocation queue
designation. If you want to run a test client adapter along with a
production client adapter, two symbolic destinations can be defined.
They can each specify the same MODENAME and PARTNER_LU, but each
can specify a different TPNAME. (Refer to “Explanation of multiple APPC
destination names JCL” on page 168 for more information.)
3. The MODENAME parameter is used to name an entry in the VTAM logon
mode table. This specifies other characteristics that are to be used in
the conversation. See the SYS1.SAMPLIB(ATBLMODE) data set for a
definition of the APPCHOST logon mode, and the
SYS1.SAMPLIB(ATBLJOB) data set for the JCL to install it.
4. PARTNER_LU must specify the client adapter LU name.

167
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Example of multiple APPC You might want to define multiple APPC destination names to allow
destination names JCL multiple client adapters that do not share APPC/MVS allocation queues. A
good example of this is to have a production client adapter processing
requests from a production CICS region, and a test client adapter processing
requests from a test CICS region.

Example 7: JCL Example for Defining Multiple APPC Destination Names

//SIADDEXEC PGM=ATBSDFMU
//SYSPRINT DD SYSOUT=*
//SYSSDLIB DD DSN=SYS1.APPCSI,DISP=SHR
//SYSSDOUT DD SYSOUT=*
//SYSIN DD DATA
1 SIADD
DESTNAME(ORXCLNT1)
TPNAME(ORXCLNT1)
MODENAME(APPCHOST)
PARTNER_LU(ORXLUCA1)
SIADD
2 DESTNAME(ORXTEST)
3 TPNAME(ORXTEST)
4 MODENAME(APPCHOST)
5 PARTNER_LU(ORXLUCA1)
/*

Explanation of multiple APPC The JCL example for defining multiple APPC destination names can be
destination names JCL explained as follows:
1. The first SIADD statement defines the production destination, as
explained in “Explanation of the APPC destination name JCL” on
page 167.
2. A second DESTNAME is defined for the test destination. It defines a
different name from the production DESTNAME. The production CICS
region and production client adapter is configured to use the
production DESTNAME. The test CICS region and test client adapter is
configured to use the test DESTNAME.

168
 Setting Up APPC for the Client Adapter

3. The test DESTNAME defines a TPNAME that is different from the

production TPNAME. This causes APPC/MVS to use separate allocation
queues for the production and test client adapters.
4. The test MODENAME is the same as the production MODENAME.
5. The test PARTNER_LU is the same as the production PARTNER_LU. This
means you can run multiple client adapters that do not share
APPC/MVS allocation queues, yet still use the same LU name for each.

169
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Defining LUs to VTAM

Overview APPC/MVS expects its LUs to be defined as VTAM resources, so that they
can access a SNA network.
This subsection discusses the following topics:
• VTAM requirements for LUs
• Using SYS1.SAMPLIB(ATBAPPL)
• APPC definition parameter security requirements

VTAM requirements for LUs Although the client adapter is usually run on the same system as the CICS
region with which it communicates (that is, an LU=LOCAL conversation),
VTAM application program definition (APPL) macros must still be coded for
each LU. See SYS1.SAMPLIB(ATBAPPL) for a sample APPL definition of an
APPC LU.

Using SYS1.SAMPLIB(ATBAPPL) The following definitions for the system base LU and client adapter LUs use
the SYS1.SAMPLIB(ATBAPPL) definition, with some changes (which are
highlighted).

Example 8: Example of APPL Definitions for Client Adapter LUs

1 MVSLU01 APPL ACBNAME=MVSLU01, C

APPC=YES, C
2 SECACPT=CONV, C
3 VERIFY=OPTIONAL, C
AUTOSES=0, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=LOGMODES, C
PARSESS=YES, C
SRBEXIT=YES, C
VPACING=1
1 ORXLUCA1 APPL ACBNAME=ORXLCA1, C
APPC=YES, C

170
 Setting Up APPC for the Client Adapter

Example 8: Example of APPL Definitions for Client Adapter LUs

2 SECACPT=CONV, C
3 VERIFY=OPTIONAL, C
AUTOSES=0, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=LOGMODES, C
PARSESS=YES, C
SRBEXIT=YES, C
VPACING=1

APPC definition parameter The code for APPL definitions for client adapter LUs can be explained as
security requirements follows:
1. Both the ACBNAME= parameter and the APPL statement label should
match the LU name defined to APPC.
2. The VERIFY= and SECACPT= parameters specify the security levels for
each LU. Determining the correct values for these parameters depends
on the environment in which CICS and the client adapter are running.
A test environment might not require the same level of security that a
production environment does.
SECACPT= specifies the greatest level of security information passed on
a conversation allocation request from a CICS client transaction to the
client adapter. If the LUs are secured using RACF APPCLU profiles, this
level of security information can be overridden to the value set in the
APPCLU profile. Refer to “Additional RACF Customization Steps for
APPC” on page 176 for more details. Each LU should have the same
value for SECACPT.
♦ SECACPT=NONE—No security information is passed on conversation
allocation requests. Use this value if security is not required,
such as in a development environment.
♦ SECACPT=CONV—APPC/MVS passes security information (if
available) on conversation allocation requests. Use this value
when security is desired, such as in a production environment.

171
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

The security information that can be passed is:

♦ User ID
♦ Security profile name (treated as a group ID by APPC/MVS)
♦ Already verified indicator
• SECACPT=ALREADYV—Conversation allocation requests with security
information, and conversation allocation requests with an indication
that security information is already verified. Use this value when the
system base LU used by CICS and the client adapter LU are both
trusted. See below.

Note: There are other values for the SECACPT parameter that are not
described here, because they do not apply.

3. VERIFY= specifies that VTAM should verify the identity of partner LUs
that attempt to establish sessions with this LU. Generally each LU has
the same value for VERIFY=, but there are valid cases where the values
can be different.
♦ VERIFY=NONE—VTAM should not verify partner LUs. Use this
value if security is not required.
♦ VERIFY=OPTIONAL—VTAM should verify those LUs that have
session keys defined. The session keys are defined in the RACF
APPCLU profile. Refer to the topic on LU 6.2 Security in the IBM
publication SNA Network Implementation Guide, SC31-8562 for
more information on how VTAM verifies the partner LU. Use this
value when security is desired.
♦ VERIFY=REQUIRED—VTAM should verify every partner LU. This
provides even tighter security control. The system base LU used
by CICS can be defined with VERIFY=OPTIONAL, and the client
adapter LU can be defined with VERIFY=REQUIRED.
This provides two benefits:
♦ Compatibility with the CICS server adapter if it is being used.
♦ Only those LUs defined with a proper RACF APPCLU profile can
connect to the client adapter.

172
 Setting Up APPC for the Client Adapter

If there is no possibility of unauthorized access from other systems in your

SNA network, you might prefer to code SECACPT=ALREADYV and VERIFY=NONE
to indicate that partner LUs do not need to be authenticated. This is safe for
LU=LOCAL conversations because user information is provided directly by
APPC/MVS. Therefore, there is no opportunity for the programmer of the
partner LU to fabricate his or her identity. Refer to “Securing the Client
Adapter” on page 315 for more details about APPC conversation security
and session-level verification.

Note: The definition of MVSLU01—the system base LU—is provided here

as an example. This LU (perhaps with a different name) should already be
defined. You might want to modify the security parameters as described
above.

APPC definitions for two-phase To support two-phase commit processing, define the VTAM LUs with the
commit ATNLOSS and SYNCLVL operands as follows:

Example 9: Example of APPL Definitions for Two-Phase Commit

1 MVSLU01 APPL ACBNAME=MVSLU01, C

APPC=YES, C
2 SECACPT=CONV, C
3 VERIFY=OPTIONAL, C
AUTOSES=0, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=LOGMODES, C
PARSESS=YES, C
SRBEXIT=YES, C
VPACING=1 C
ATNLOSS=ALL, C
SYNCLVL=SYNCPT
1 ORXLUCA1 APPL ACBNAME=ORXLCA1, C
APPC=YES, C
2 SECACPT=CONV, C

173
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Example 9: Example of APPL Definitions for Two-Phase Commit

3 VERIFY=OPTIONAL, C
AUTOSES=0, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=LOGMODES, C
PARSESS=YES, C
SRBEXIT=YES, C
VPACING=1, C
ATNLOSS=ALL, C
SYNCLVL=SYNCPT

174
 Setting Up APPC for the Client Adapter

Defining the Required Resources to CICS

Overview This subsection provides the location for the required JCL to define the
required APPC resources to CICS. It also describes the contents of the JCL
and how it is to be used. It discusses the following topics:
• Location of required JCL
• Description of the contents of the JCL
• Using the JCL

Location of required JCL The orbixhlq.JCLLIB(ORBIXCSD) JCL member runs the CICS offline
resource definition utility to define the required APPC resources to CICS. You
might need to change the STEPLIB and DFHCSD DD cards to match your CICS
installation.

Description of the contents of the The sample JCL defines the following for the client adapter:
JCL • A Connection definition which identifies the LU used by the client
adapter.
• A Sessions definition which defines session characteristics for sessions
between CICS and the client adapter.
• A Partner definition which defines information needed for
conversations between CICS and the client adapter.
• Demonstration programs and transactions.

Using the JCL Make the appropriate changes to the JCL and run it to define the client
adapter CICS resources.

Note: If you are using the CICS server adapter with the APPC plug-in, this
step might already have been performed.

175
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

Additional RACF Customization Steps for

APPC
Overview There are a number of RACF definitions related to APPC that you might
need to add or change to run the client adapter. Refer to “Securing the
Client Adapter” on page 315 for more details about how the client adapter
fits into a secure system environment.
Much of the information provided in this section can be found in the
sections relating to LU Security and Conversation Security in the IBM
publication MVS Planning: APPC/MVSManagement, GC28-1807, as well
as in the chapter on “Implementing LU 6.2 Security” in the IBM publication
CICS RACF Security Guide, SC33-1701.

In this section This section discusses the following topics:

LU-to-LU Security Verification page 177

Protecting LUs page 179

176
 Additional RACF Customization Steps for APPC

LU-to-LU Security Verification

Overview LU-LU security verification provides a means of controlling which LUs can
establish sessions with a particular LU. RACF provides the APPCLU class for
this purpose. CICS uses the term “Bind Time Security” when referring to
LU-to-LU security verification.
This subsection discusses the following topics:
• Enable LU-to-LU security verification in CICS
• APPCLU profiles
• APPCLU profile contents and operation
• Accessing APPCLU profiles

Enable LU-to-LU security CICS requires definitions in the System Initialization Table (SIT) and the
verification in CICS client adapter CONNECTION definition to enable LU-to-LU security verification.
The required changes to the SIT are that you specify SEC=YES and
XAPPC=YES.
After the changes to the SIT are made, CICS must be recycled for the
changes to take effect.

Note: If you are using the CICS server adapter APPC plug-in, this step
might already have been performed.

The required change to the client adapter CONNECTION is that you specify
BINDSECURITY=YES.

APPCLU profiles APPCLU profiles can be defined to control which LUs can establish sessions
with a particular LU.
Each APPCLU profile name has the form:
‘networkid.local-lu-name.partner-lu-name’.
Each profile contains information to be used by APPC/MVS on one side of a
session between the two named LUs. This means each side of a session has
its own specific profile. CICS requires the system base LU to communicate
with the client adapter. However, when defining APPCLU profiles to secure
the CICS LU, the LU defined on the APPLID parameter of the SIT is the LU
that must be secured.

177
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

For example, if LU CICSTS1 attempts to establish a session with LU

ORXLUCA1, APPC/MVS on the initiating (outbound) side examines the
‘networkid.CICSTS1.ORXLUCA1’ profile, and APPC/MVS on the receiving
(inbound) side examines the ‘networkid.ORXLUCA1.CICSTS1’ profile. LU
CICSTS1 was defined on the APPLID parameter of the SIT.

APPCLU profile contents and Each APPCLU profile contains a session key, which is a string of letters or
operation numbers, and a CONVSEC setting. When a session is initiated between two
LUs, APPC/MVS on the initiating (outbound) side passes the session key
found in its APPCLU profile to APPC/MVS on the receiving (inbound) side. If
APPC/MVS on the inbound side finds that the received session key matches
the session key in its own APPCLU profile, it overrides the VTAM SECACPT=
setting with the CONVSEC setting from its profile. Thus, to allow a CICS client
transaction to authenticate itself to the client adapter, the following
definitions might be used:

RDEFINE APPCLU P390.ORXLUCA1.CICSTS1

UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))

RDEFINE APPCLU P390.CICSTS1.ORXLUCA1

UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))

SETROPTS CLASSACT(APPCLU)

To refresh the profiles in VTAM, use the following VTAM commands:

F VTAM,PROFILES,ID=CICSTS1
F VTAM,PROFILES,ID=ORXLUCA1

Accessing APPCLU profiles It is not necessary to permit the client adapter or CICS region to have user
IDs for the APPCLU profiles. However, access to the profiles should be tightly
controlled to ensure that only appropriate users can read or change the
session keys.

178
 Additional RACF Customization Steps for APPC

Protecting LUs
Overview Protecting LUs involves controlling the users that are permitted to use the
CICS local LU that initiates requests to the client adapter LU, and
controlling the users that are permitted to use the client adapter LU that
receives requests from CICS.
This subsection discusses the following topics:
• Controlling access to the CICS local LU
• Controlling access to the client adapter LU

Controlling access to the CICS The CICS local LU initiates requests to allocate conversations with the client
local LU adapter. This LU is considered the APPC port of entry. It can be secured by
controlling the users that are permitted to use the LU. The RACF APPCPORT
class provides this security control. First, a profile is defined for the CICS
local LU that permits no access. A PERMIT is then issued for each user that
requires access to the CICS local LU. For example:

RDEFINE APPCPORT CICSTS1 UACC(NONE)

PERMIT CICSTS1 CLASS(APPCPORT) ID(USER1) ACCESS(READ)
PERMIT CICSTS1 CLASS(APPCPORT) ID(USER2) ACCESS(READ)
…
SETROPTS CLASSACT(APPCPORT) RACLIST(APPCPORT)

Controlling access to the client The client adapter LU receives requests initiated by the CICS local LU. The
adapter LU client adapter LU can be secured by controlling the users that are permitted
to use this LU. The RACF APPL class provides this security control. First, a
profile is defined for the client adapter LU that permits no access. A PERMIT
is then issued for each user that requires access to the client adapter LU.
For example:

RDEFINE APPL ORXLUCA1 UACC(NONE)

PERMIT ORXLUCA1 CLASS(APPL) ID(USER1) ACCESS(READ)
PERMIT ORXLUCA1 CLASS(APPL) ID(USER2) ACCESS(READ)

SETROPTS CLASSACT(APPL) RACLIST(APPL)

SETROPTS RACLIST(APPL) REFRESH

179
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

AMTP_APPC Plug-In Configuration Items

Overview This section discusses the following topics:
• APPC destination
• AMTP function timeout
• APPC minimum communication threads
• APPC maximum communication threads

APPC destination The related configuration item is

plugins:amtp_appc:symbolic_destination. This specifies the APPC/MVS
symbolic destination name that identifies the LU, TPN, and LOGMODE the
client adapter uses. The Orbix runtime in CICS is configured to use this
destination. Refer to “Customizing Orbix Symbolic Destination” on page 206
for more information on configuring the destination in the Orbix runtime in
CICS. CICS client transactions haves their requests sent to the client adapter
using this symbolic destination. The default value is ORXCLNT1.
The specified symbolic destination name is verified only when a CICS client
transaction attempts to send a request to the client adapter. This means the
CICS region does not have to be available when you start the client adapter.
Refer to “Example of the APPC destination name JCL” on page 166 for
details of how to define the symbolic destination to APPC/MVS.

AMTP function timeout The related configuration item is plugins:amtp_appc:function_wait. It

specifies the number of minutes the client adapter waits for a response from
the CICS client transaction before canceling the request. It prevents the
client adapter from having to wait indefinitely for a response from the CICS
client transaction if the transaction has stopped for some reason. The
default is 5 minutes.

APPC minimum communication The related configuration item is plugins:amtp_appc:min_comm_threads. It

threads specifies the minimum number of client adapter threads that are used to
service CICS client transaction requests. Each thread services a single client
transaction request. Multiple threads allow for multiple concurrent client
requests to be processed. The default is 5 threads.

180
 AMTP_APPC Plug-In Configuration Items

APPC maximum communication The related configuration item is plugins:amtp_appc:max_comm_threads. It

threads specifies the maximum number of client adapter threads that can be used to
service CICS client transaction requests. If all client adapter threads are
busy, and another request arrives, further threads are started dynamically
up to this maximum number. The default is 10 threads.

AMTP maximum sync level The related configuration item is plugins:amtp_appc:maximum_sync_level.

It specifies the maximum APPC synchronization level supported by the
client adapter. The value can be 0 or 2. A value of 0 indicates that
two-phase commit processing is not used by CICS transactions. A value of 2
indicates that two-phase commit processing is available for CICS
transactions to use. Transactions that do not require two-phase commit
processing can still function correctly if the maximum sync level is set to 2.
The default value is 0.

181
CHAPTER 13 | Configuring the Client Adapter AMTP_APPC Plug-in

182
 CHAPTER 14

Configuring the
Client Adapter
AMTP_XMEM
Plug-in
The AMTP_XMEM plug-in for the client adapter uses cross
memory communication to communicate with client
transactions. This chapter describes how to set up and
configure the client adapter for cross memory communication.

In this chapter This chapter discusses the following topics:

Prerequisites and Further Reading page 184

Running the Client Adapter APF-Authorized page 185

Running the Client Adapter in Non-Swappable Address Space page 187

Understanding the Impact of Cross Memory Communication page 189

AMTP_XMEM Plug-In Configuration Items page 191

183
CHAPTER 14 | Configuring the Client Adapter AMTP_XMEM Plug-in

Prerequisites and Further Reading

Prerequisites to using cross Cross memory communication is integrated into the z/OS operating system.
memory communication Before using cross memory communication as the transport mechanism
between CICS and the client adapter, be aware of the following restrictions.
• The client adapter must be run APF-authorized.
• The client adapter must run in a non-swappable address space.
• After the client adapter is stopped, its address space ID becomes
unavailable until the next IPL.
• CICS and the client adapter must be running on the same LPAR.
• Two-phase commit processing is not supported when using the cross
memory communication transport.

Further reading For more information on cross memory communication, refer to the IBM
publication MVS Programming: Extended Addressability Guide,
SA22-7614.

184
 Running the Client Adapter APF-Authorized

Running the Client Adapter APF-Authorized

Overview To enable the CICS client adapter to use cross memory communication, its
load libraries must be APF-authorized. This section discusses the following
topics:
• “Data sets that must be APF-authorized”
• “Authorizing the data sets”

Data sets that must be All data sets in the STEPLIB concatenation of the orbixhlq.JCLLIB(CICSCA)
APF-authorized JCL, which is used to run the CICS client_adapter, must be
APF-authorized. These data sets include:
• orbixhlq.ADMIN.LOADLIB
• orbixhlq.LOADLIB
• orbixhlq.LPALIB
• cpphlq.SCLBDLL
• lehlq.SCEERUN

In the preceding list, cpphlq represents the high-level qualifier for the C++
data sets; and lehlq represents the high-level qualifier for the LE (Language
Environment) data sets).

Note: If the STEPLIB contains other data sets, they must also be
APF-authorized

Authorizing the data sets Your systems programmer can authorize the necessary data sets. There are
two methods available to authorize a data set. Users with the relevant
authority can do either of the following:
• Issue the SETPROG command to dynamically make a data set
APF-authorized. For example, to dynamically authorize an
SMS-managed data set, issue the following command:

SETPROG APF,ADD,DSNAME=orbixhlq.LOADLIB,SMS

185
CHAPTER 14 | Configuring the Client Adapter AMTP_XMEM Plug-in

After issuing the command, authorization can be verified by issuing the

following command:

D PROG,APF

If the data set is authorized, it appears in the command output.

• Add the dataset name to the PROGxx parmlib member and issue the
SET PROG=xx command. This method ensures that the data set is
authorized across IPLs if the PROGxx member is referenced during the
IPL.

186
 Running the Client Adapter in Non-Swappable Address Space

Running the Client Adapter in Non-Swappable

Address Space
Overview The CICS client adapter provides a Program Call (PC) routine when running
in client mode. The CICS address space calls this PC routine to transfer data
between CICS and the CICS client adapter. A PC routine must run in an
address space that cannot be swapped out.
This section discusses the following topics:
• “Defining the client adapter to run in non-swappable address space”
• “Skipping the definition”

Defining the client adapter to run The CICs client adapter can be defined to the system as a non-swappable
in non-swappable address space address space by providing a PPT definition in the SCHEDxx member of
SYS1.PARMLIB. Your systems programmer can set up this definition:

PPT PGMNAME(ORXCICSA)
NOSWAP
NOPREF

For this change to take effect, issue the SET SCH=xx z/OS command.

Skipping the definition The preceding PPT definition is not required for the CICS client adapter to
run in a non-swappable address space. The client adapter issues a SYSEVENT
TRANSWAP macro to put itself into non-swap mode. This works regardless of
whether or not a PPT definition exists.
Even though it is not required, a PPT definition might prove useful for the
purposes of providing documentation on programs that run on in a
non-swappable address space.

187
CHAPTER 14 | Configuring the Client Adapter AMTP_XMEM Plug-in

However, you might choose to not provide a PPT definition if the CICS client
adapter and CICS server adapter both run on the same LPAR. Both adapters
use the same program name of ORXCICSA.
A PPT definition causes both adapters to run in a non-swappable address
space. Because the server adapter does not require the non-swap property,
an installation might want to skip the PPT definition, resulting in only the
client adapter running in a non-swappable address space.

188
 Understanding the Impact of Cross Memory Communication

Understanding the Impact of Cross Memory

Communication
Overview The use of cross memory communication involves multiple address spaces
communicating with each other. The address spaces communicate by
calling PC routines. For example, the CICS address space communicates
with the CICS client adapter by calling a PC routine provided by the CICS
client adapter.

Two ways to set up authorization To enable one CICS address space to call a PC routine in another address
space, proper authorization must be granted, and system tables must be
connected between the two address spaces. This setup can be shared
between the client address space (CICS), and the server address space
(CICS client adapter). Alternatively, the server address space can perform
the entire setup.

Shared setup If the setup is shared between address spaces, this requires the client
(CICS) to run with its entire set of load libraries APF-authorized. If it is not
desirable in a particular installation to run CICS with APF-authorized load
libraries, you can avoid shared setup by allowing the server address space
perform the entire setup.

Server address space setup To avoid the need to have CICS load libraries APF-authorized, the client
adapter currently supports server address space setup only.
However, allowing the server address space to perform the entire cross
memory communication setup comes at a cost. When the CICS client
adapter is started, it is assigned an address space ID (ASID). When the CICS
client adapter is subsequently stopped, its ASID becomes unavailable until
the next IPL. A message similar to the following appears in the system log:

IEF352I ADDRESS SPACE UNAVAILABLE

189
CHAPTER 14 | Configuring the Client Adapter AMTP_XMEM Plug-in

Because the CICS client adapter is intended to be a long-running service,

and not frequently stopped and restarted between IPLs, this should not
result in many ASIDs becoming unavailable.
For more information on cross memory communication, and why ASIDs
become unavailable, refer to the following IBM publication:
MVS Programming: Extended Addressability Guide, SA22-7614.

ASID reuse Since z/OS 1.9, the operating system can reuse an ASID. This facility is
enabled by adding the following to the SYS1.PARMLIB(DIAGxx) member:

REUSASID(YES)

You must perform the following steps when starting the client adapter:
1. Place the client adapter JCL in a suitable PROCLIB.
2. Use the START command to start the client adapter.

Note: Simply submitting a job to start the client adapter results in a lost
ASID when the client adapter is stopped.

3. Use the REUSASID parameter of the START command.

For example, to start an instance of the client adapter in
SYS1.PROCLIB(MYXFRMR), issue the following command:

START MYXFRMR, REUSASID=YES

For more information on reusable ASIDs, see the following IBM publication:
MVS Programming: Extended Addressability Guide, SA22-7614.

190
 AMTP_XMEM Plug-In Configuration Items

AMTP_XMEM Plug-In Configuration Items

Overview This section discusses the following topics:
“Cross memory communication destination”
“Cross memory communication minimum threads”
“Cross memory communication maximum threads”
“Cross memory communication maximum segment size”

Cross memory communication The related configuration item is

destination plugins:amtp_xmem:symbolic_destination. This is a symbolic name that
identifies the CICS client adapter. It can be up to eight characters in length.
The Orbix runtime in CICS is configured to use this destination. CICS client
transactions have their requests sent to the client adapter using this
symbolic destination. The default value is ORXCLNT1.

Note: The value for this configuration item must be unique for each
instance of the client adapter. Unlike APPC, the cross memory
communication plug-in does not allow multiple instances of the client
adapter to use the same symbolic destination.

Cross memory communication The related configuration item is plugins:amtp_xmem:min_comm_threads. It

minimum threads specifies the minimum number of client adapter threads that are used to
service CICS client transaction requests. Each thread services a single client
transaction request. Multiple threads allow for multiple concurrent client
requests to be processed. The default is 5 threads.

Cross memory communication The related configuration item is plugins:amtp_xmem:max_comm_threads. It

maximum threads specifies the maximum number of client adapter threads that can be used to
service CICS client transaction requests. If all client adapter threads are
busy, and another request arrives, further threads are started dynamically
up to this maximum number. The default is 10 threads.

191
CHAPTER 14 | Configuring the Client Adapter AMTP_XMEM Plug-in

Cross memory communication The related configuration item is plugins:amtp_xmem:max_segment_size. It

maximum segment size specifies the maximum segment size that the client adapter can receive
from a client. The Orbix runtime in CICS is configured with a maximum
segment size. The client adapter might be servicing one or more CICS
regions. The value for plugins:amtp_xmem:max_segment_size must be
equal to or greater than the largest segment size defined in the configuration
for the Orbix runtime in CICS.

192
 CHAPTER 15

Configuring the
Client Adapter
Subsystem
The client adapter receives CICS client transaction requests
from the AMTP_APPC or AMTP_XMEM plug-ins, locates target
objects, invokes operations, and returns results to the
AMTP_APPC or AMTP_XMEM plug-ins. This functionality is
implemented as a client adapter subsystem that is
dynamically loaded by the adapter application. This chapter
describes how to configure the client adapter subsystem.

In this chapter This chapter discusses the following topic:

Client Adapter Subsystem Configuration page 194

193
CHAPTER 15 | Configuring the Client Adapter Subsystem

Client Adapter Subsystem Configuration

Overview This chapter discusses the following topics:
• Type information mechanism
• IFR signature cache file
• type_info store

Type information mechanism The related configuration item is plugins:client_adapter:repository_id.

It specifies the repository used by the client adapter to store operation
signatures. Two repositories are supported: ifr and type_info. The default
is type_info. Refer to “Using type_info store as a Source of Type
Information” on page 254 for more information on the role of type
information.

IFR signature cache file If the client adapter is configured to use the IFR as the type information
repository (a store of operation signatures), an IFR signature cache file can
be used to improve performance. The related configuration item is
plugins:client_adapter:ifr:cache. Refer to “Using an IFR Signature
Cache file” on page 252 for more information on how IFR signature cache
files work.
The filename specification for the signature cache file can take one of
several forms:
• The following example reads the mappings from a file in the z/OS UNIX
System Services hierarchical file system (HFS):

plugins:client_adapter:ifr:cache =
"/home/user/sigcache.txt;"

• The following example shows the syntax to indicate that the mappings
are cached in a flat file (PS) data set, which is created with the default
attributes used by the LE runtime:

plugins:client_adapter:ifr:cache =
"//orbixhlq.DEMO.IFRCACHE";

194
 Client Adapter Subsystem Configuration

The data set is created with the default attributes used by the LE runtime.
Depending on the number of interfaces and the complexity of the types
used, this might not be large enough. In this case, the client adapter saves
as many cache entries as possible and then issues error messages. If this
occurs, you should preallocate a larger data set with the same attributes,
and use this name the next time you start the client adapter.

Note: Do not use members of partitioned data sets as a signature cache

file.

type_info store If the client adapter is configured to use a type_info store as the type
information repository (a store of operation signatures), the location of the
store must be supplied. The related configuration item is
plugins:client_adapter:type_info:source.
The plugins:client_adapter:type_info:source variable can be set to one
of the following:
• An HFS file (z/OS UNIX System Services)
Specifies a file to use as a type_info source. Operation signatures are
read from this file during start-up. If a refresh is requested (via itadmin
mfa refresh for example), this file is re-read. For example:

plugins:client_adapter:type_info:source =
"/home/bob/type_info.txt";

• An HFS directory (z/OS UNIX System Services)

Specifies a directory to use as a type_info source. Operation signatures
are read from all files in this directory during start-up. If a refresh is
requested, all files in the directory are browsed until the relevant
operation signature(s) are found. For example:

plugins:client_adapter:type_info:source =
"/home/bob/typeinfo_store";

• A PDS member (native z/OS)

195
CHAPTER 15 | Configuring the Client Adapter Subsystem

Specifies a PDS member (batch) to use as a type_info source.

Operation signatures are read from this member during start-up. If a
refresh is requested, this member is re-read. For example:

plugins:client_adapter:type_info:source =
"//MY1.TYPEINFO(MYINFS)";

• A PDS (native z/OS)

Specifies a dataset to use as a type_info source. Operation signatures
are read from all members in this dataset during start-up. If a refresh is
requested, all members in the dataset are browsed until the relevant
operation signature(s) are found. For example:

plugins:client_adapter:type_info:source = "//MY1.TYPEINFO";

For PDS names, you can use a DD name, as long as this is defined to the
client adapter start JCL, orbixhlq.JCLLIB(CICSCA).

Note: The use of HFS directories or a PDS is preferable to the use of flat
files, because these methods are better suited to the dynamic addition or
removal of interface information, and they can also address IDL versioning.

196
 CHAPTER 16

Configuring the
Orbix Runtime in
CICS
This chapter provides information on configuring the Orbix
runtime that is used by Orbix clients running in CICS.

In this chapter This chapter discusses the following topics:

Customizing CICS page 198

Customizing Orbix Configuration page 200

Customizing Orbix Event Logging page 202

Customizing Orbix Maximum Segment Size page 204

Customizing Orbix Symbolic Destination page 206

197
CHAPTER 16 | Configuring the Orbix Runtime in CICS

Customizing CICS
Overview Before you can run Orbix CICS applications in your region, you must perform
a number of additional steps to enable your CICS system to support Orbix
clients. Depending on your installation, one or all of these tasks might
already have been completed. You must verify this with the systems
programmer responsible for CICS at your site.
This section discusses the following topics:
• Installing language environment support
• Installing support for C++ classes in CICS
• Installing sample Orbix CICS resource definitions
• Updating the CICS region

Installing language environment CICS Language Environment (LE) support is not installed as standard. To
support enable LE support in CICS you must perform a number of steps. Refer to the
IBM manual Language Environment for OS/390 Customization for details
on installing LE support in CICS.
If LE support has been successfully installed in CICS, the following message
is written to the console:

DFHAP1203I CICS Language Environment is being initialized

If you cannot see this message, LE support is not available under CICS and
any Orbix activities fail.

Installing support for C++ classes Support for the C++ standard classes must be explicitly defined to CICS.
in CICS Refer to the IBM manual OS/390 C/C++ Programming Guide for details of
the steps required to run C++ application programs under CICS. In
particular, note that the standard C++ DLLs such as IOSTREAM must be
defined to CICS.
Failure to do this results in the following messages being issued from CICS
when attempting to run an Orbix CICS transaction:

EDC6063I DLL name is IOSTREAM

EDC5207S Load request for DLL load module unsuccessful.

198
 Customizing CICS

C++ support is required by Orbix itself, which is written in C++.

Note: From the Orbix CICS programming perspective, clients can only be
written in COBOL or PL/I at this time.

Installing sample Orbix CICS The data set orbixhlq.JCLLIB(ORBIXCSD) contains a job to run DFHCSDUP,
resource definitions which is the CICS offline resource definition utility, to define the CICS
resources used by the sample jobs and demonstrations. You can run this as
is, or just use it as a reference when defining the resources online with the
CEDA transaction. When the resources have been defined, use CEDA to
install the whole group.

Updating the CICS region To update the CICS region perform the following steps:

Step Action

1 Add five libraries to the CICS region’s DFHRPL concatenation

as follows:
DD DSN=orbixhlq.DEMO.CICS.CBL.LOADLIB,DISP=SHR
DD DSN=orbixhlq.DEMO.CICS.PLI.LOADLIB,DISP=SHR
DD DSN=orbixhlq.MFA.LOADLIB,DISP=SHR
DD DSN=CEE.SCEERUN,DISP=SHR
DD DSN=CBC.SCLBDLL,DISP=SHR
Where hlq and version represents the location of your
Orbix installation.

2 Add CEE.SCEERUN to the STEPLIB concatenation.

3 Recycle the regions to pick up these libraries.

Note: If you are using the CICS server adapter, this step might have
already been performed.

199
CHAPTER 16 | Configuring the Orbix Runtime in CICS

Customizing Orbix Configuration

Overview The Orbix configuration inside CICS is DLL-based. (DLL is the acronym for
Dynamic Link Library.) The Orbix runtime inside CICS does not access a file
for configuration information, but instead gets configuration information
from a DLL. The DLL resides in the Orbix CICS runtime library that was
added to the CICS region’s DFHRPL. The ORXMFACx member is the
configuration DLL.
This section discusses the following topics:
• How the configuration is changed
• Steps to change the configuration
• S390 Assembler program variables

How the configuration is changed Changing the configuration involves updating the configuration DLL. The
DLL is updated by assembling and linking an S390 Assembler program that
defines the configuration settings. See orbixhlq.JCLLIB(MFACLINK) for
sample JCL to update the DLL. The sample JCL runs the Assembler and
re-links the configuration in the DLL. The JCL contains the S390 Assembler
program that defines the configuration settings.

Steps to change the configuration Perform the following steps to update the configuration DLL:

Step Action

1 Make a backup of your current configuration DLL. The

configuration DLL is in orbixhlq.MFA.LOADLIB(ORXMFACx).

2 Make the appropriate changes to the

orbixhlq.JCLLIB(MFACLINK) JCL, as outlined in the JCL
comments.

3 Change the S390 Assembler program to define the new

configuration settings.

4 Submit the JCL.

200
 Customizing Orbix Configuration

Step Action

5 Make the updated DLL available to your CICS region for the
configuration changes to take effect.

S390 Assembler program The following table lists the Assembler variables that can be changed in
variables order to change the configuration:

Table 6: S390 Assembler Program Variables and Default Values

Assembler Variable Description Default Value

LOGLVL Event logging level. 2

MAXSEG Maximum segment size. 32760

TIMEOUT Maximum time for a client request to complete. Applies only 5

when cross memory communication is used.

SYMBDST Symbolic destination. ORXCLNT1

LOCALLU Used to specify if cross memory is to be used for IMSLU01

communication. Ignored when APPC communication is
used.

201
CHAPTER 16 | Configuring the Orbix Runtime in CICS

Customizing Orbix Event Logging

Overview For the Orbix runtime in CICS, most of the configuration settings are fixed.
However, the level of event logging performed by the runtime can be
customized for the client adapter.
This section discusses the following topics:
• Customizing the level of event logging
• ORXMFACx DLL setting
• Modifying the ORXMFACx DLL setting

Customizing the level of event This is done by modifying the ORXMFACx DLL. This DLL contains an S390
logging Assembler CSECT that supplies the event logging string to the runtime.

Event logging settings The event logging settings are as follows:

Table 7: Event Logging Settings for the Client Adapter

Value Description

0 LOG_NONE—no logging in CICS is performed.

1 LOG_ERROR—only log errors.

2 LOG_WARNING—log warnings and errors.

3 LOG_INFO_HIGH—log high priority informational messages,

warnings and errors.

4 LOG_INFO_MED—log medium priority informational messages,

high priority informational messages, warnings and errors.

5 LOG_INFO_LOW—log low priority informational messages,

medium priority informational messages, high priority
informational messages, warnings and errors.

6 LOG_INFO_ALL—log all messages.

202
 Customizing Orbix Event Logging

ORXMFACx DLL setting The ORXMFACx DLL shipped with the client adapter has a setting of 2 for
event logging in CICS. This means that all warning and error messages are
displayed, but none of the informational messages are displayed.

Modifying the ORXMFACx DLL The ORXMFACx DLL setting can be modified to some other value. For
setting example, to help trace a problem with a transaction in CICS, it can be
changed to 6.

203
CHAPTER 16 | Configuring the Orbix Runtime in CICS

Customizing Orbix Maximum Segment Size

Overview The Orbix runtime in CICS sends client transaction data to the client adapter
in a stream of segments. The maximum size of these segments can be
customized.
This section discusses the following topics:
• ORXMFACx DLL setting
• Modifying the ORXMFACx DLL setting
• Maximum segment size constraints

ORXMFACx DLL setting The ORXMFACx DLL shipped with the client adapter has a setting of 32760 for
the maximum segment size. (This is 32K rounded down to be a multiple of
eight.)

Modifying the ORXMFACx DLL The Orbix runtime in CICS builds up segments of this size. For APPC,
setting multiple segments of this size are used to transmit data. The 32K APPC
limit for a single segment applies, but all the segments together can be more
than 32K. Depending on your network definitions, these segments can be
further broken up into smaller segments by VTAM and chained when they
are transmitted.
For cross memory, segments of this size are moved directly between CICS
and the client adapter address space.
The ORXMFACx DLL setting can be modified to be some other value if, for
example, your installation has restrictions on the size of APPC buffers. For
example, it might be changed to 4096 to meet an installation requirement.
Change MAXSEG in the Assembler program to modify the maximum segment
size.

204
 Customizing Orbix Maximum Segment Size

Maximum segment size When choosing a value for the maximum segment size consider the
constraints following:
• The value must be a multiple of 8
• The minimum value is 32
• The maximum value is 32760
• The default value is 32760

205
CHAPTER 16 | Configuring the Orbix Runtime in CICS

Customizing Orbix Symbolic Destination

Overview The Orbix runtime in CICS uses APPC or cross memory when
communicating with the client adapter.
When using APPC, an APPC allocate is used to initiate an APPC
conversation with the client adapter. The APPC allocate must identify the
client adapter as the target of the allocate request. An APPC symbolic
destination is used to identify the client adapter. The symbolic destination
can be customized.
When using cross memory, the PC (program call) number of the PC routine
residing in the client adapter address space is determined by using
name/token services. The symbolic destination is the name portion of the
name/token. The PC number is found in the token portion of the name
token. The client adapter publishes the name token, and the runtime in
CICS uses the symbolic destination to lookup the name/token.
This section discusses the following topics:
• ORXMFACx DLL setting
• Modifying the ORXMFACx DLL setting
• Symbolic destination restrictions

ORXMFACx DLL setting The ORXMFACx DLL shipped with the client adapter has a setting of ORXCLNT1
for the symbolic destination.

Modifying the ORXMFACx DLL The ORXMFACx DLL setting can be modified to some other value.
setting When using APPC, if your installation has naming standards for symbolic
destinations, it can be changed to, for example, PRODCADP. Change SYMBDST
in the Assembler program to modify the APPC symbolic destination.
When using cross memory, use a name that corresponds to a valid
name/token pair name.

206
 Customizing Orbix Symbolic Destination

Symbolic destination restrictions When using APPC, consider the following when choosing a value for the
symbolic destination:
• The default value is ORXCLNT1.
• The value must match the setting of the client adapter’s AMTP_APPC
plug-in configuration item
(plugins:amtp_appc:symbolic_destination). Refer to “APPC
destination” on page 180 for more information on the AMTP_XMEM
plug-in configuration setting.
• Refer to “Defining an APPC Destination Name for the Client Adapter”
on page 166 for more information on how to define a symbolic
destination to APPC/MVS.
When using cross memory, consider the following when choosing a value for
the symbolic destination:
• The default value is ORXCLNT1.
• The value must match the setting of the client adapter’s AMTP_XMEM
plug-in configuration item
(plugins:amtp_xmem:symbolic_destination). Refer to “Cross memory
communication destination” on page 191 for more information on the
AMTP_XMEM plug-in configuration setting.

207
CHAPTER 16 | Configuring the Orbix Runtime in CICS

208
 Part 4
Securing and Using the CICS
Server Adapter
In this part This part contains the following chapters:

Securing the CICS Server Adapter page 211

Mapping IDL Interfaces to CICS page 237

Using the CICS Server Adapter page 261

 CHAPTER 17

Securing the CICS

Server Adapter
This chapter provides details of security considerations
involved in using the CICS server adapter. It provides a review
of general Orbix security implications and the relevant CICS
security mechanisms. It describes the various security modes
that the EXCI-based and APPC-based server adapters support,
with particular emphasis on how each mode affects the
existing CICS security mechanisms.

In this chapter The following topics are discussed in this chapter:

Security Configuration Items page 212

Common Security Considerations page 220

EXCI-Based Security Considerations page 222

APPC-Based Security Considerations page 229

211
CHAPTER 17 | Securing the CICS Server Adapter

Security Configuration Items

Overview This section provides an example and details of how to configure the CICS
server adapter to run with Transport Layer Security (TLS) enabled. The
sample configuration includes an isf sub-scope that highlights the
configuration items required to integrate with the IONA Security Framework
(iSF) and, in particular, enable CSIv2-based authentication using the
off-host Security service. The isf sub-scope also includes configuration
items that allow you to deploy a fully standalone CICS adapter service.

Sample configuration Example 10 provides an overview of the configuration items used to enable
security with the server adapter.

Example 10: Sample Security Configuration for CICS Server Adapter

(Sheet 1 of 4)

plugins:security:share_credentials_across_orbs = "true";

# By default, use TLS V1. Downgrade to SSL V3 if the remote

# peer is unable to support TLS V1.
policies:mechanism_policy:protocol_version = ["TLS_V1", "SSL_V3"];

# Please change the following if you have only export strength

# encryption available on the machine.
policies:mechanism_policy:ciphersuites = ["RSA_WITH_RC4_128_SHA",
"RSA_WITH_RC4_128_MD5"];

plugins:systemssl_toolkit:saf_keyring
= "%{LOCAL_SSL_USER_SAF_KEYRING}";

principal_sponsor:use_principal_sponsor = "true";
principal_sponsor:auth_method_id = "security_label";

# By default, use the 'iona_services' certificate from the keyring

principal_sponsor:auth_method_data = ["label=iona_services"];

# By default the following policies are used to deploy a

# fully secure domain where client authentication is not required:
#
policies:target_secure_invocation_policy:requires =
["Confidentiality", "DetectMisordering",

212
 Security Configuration Items

Example 10: Sample Security Configuration for CICS Server Adapter

(Sheet 2 of 4)

"DetectReplay", "Integrity"];
policies:target_secure_invocation_policy:supports =
["Confidentiality", "EstablishTrustInTarget",
"EstablishTrustInClient", "DetectMisordering",
"DetectReplay", "Integrity"];
policies:client_secure_invocation_policy:requires =
["Confidentiality", "EstablishTrustInTarget",
"DetectMisordering", "DetectReplay", "Integrity"];
policies:client_secure_invocation_policy:supports =
["Confidentiality", "EstablishTrustInClient",
"EstablishTrustInTarget", "DetectMisordering",
"DetectReplay", "Integrity"];

# For semi-secure services, the following policies would be used:

#
#policies:target_secure_invocation_policy:requires =
# ["NoProtection"];
#policies:target_secure_invocation_policy:supports =
# ["NoProtection", "Confidentiality",
# "EstablishTrustInTarget", "EstablishTrustInClient",
# "DetectMisordering", "DetectReplay", "Integrity"];
#policies:client_secure_invocation_policy:requires =
# ["NoProtection"];
#policies:client_secure_invocation_policy:supports =
# ["NoProtection", "Confidentiality",
# "EstablishTrustInTarget", "EstablishTrustInClient",
# "DetectMisordering", "DetectReplay", "Integrity"];
#
# If you are going to use a semi-secure approach, please
# search this file for "orb_plugins" and add "iiop" into
# the list.

orb_plugins = ["local_log_stream", "iiop_profile", "giop",

"iiop_tls"];

IT_LocatorReplicas = ["iona_services.locator=corbaloc:iiops:1.2@%{LOCAL\
_HOSTNAME}:%{LOCAL_TLS_LOCATOR_PORT},it_iiops:1.2@%{LOCAL_HOSTNAME}:%{L\
OCAL_TLS_LOCATOR_PORT},iiop:1.2@%{LOCAL_HOSTNAME}:%{LOCAL_LOCATOR_PORT}\
/IT_LocatorReplica"];

iona_services
{
orb_plugins = ["local_log_stream", "iiop_profile", "giop",
"iiop_tls", "ots"];

213
CHAPTER 17 | Securing the CICS Server Adapter

Example 10: Sample Security Configuration for CICS Server Adapter

(Sheet 3 of 4)

generic_server:wto_announce:enabled = "true";
…
cicsa
{
#
# Settings for well-known addressing:
# (mandatory if direct_persistence is enabled)
#
# plugins:cicsa:iiop_tls:port = "5107";
# plugins:cicsa:iiop_tls:host = "%{LOCAL_HOSTNAME}";

isf
{
# enable ISF authentication
#

orb_plugins = ["iiop_profile", "giop",

"iiop_tls", "local_log_stream",
"ots", "gsp", "portable_interceptor"];

event_log:filters = ["IT_CSI=*", "IT_GSP=*",

"IT_IIOP_TLS=*",
"IT_MFA=INFO_HI+WARN+ERROR+FATAL"];

binding:server_binding_list
= ["CSI+GSP+OTS", "CSI+GSP", "CSI+OTS", "CSI"];

# standalone ISF-enabled adapter

#
plugins:cicsa:direct_persistence = "yes";
plugins:cicsa:iiop_tls:port = "5106";
plugins:cicsa:iiop:port = "5006";

# search for an access ID in the received credentials,

# and if available, use that ID to perform SAF checks
# when starting CICS transactions
#
plugins:cicsa:use_client_principal = "yes";
plugins:cicsa:check_security_credentials = "yes";

# IOR for the off-host Security Service -

# not required if the adapter is only intended to
# perform identity assertion on the propagated CSI::IdentityToken

214
 Security Configuration Items

Example 10: Sample Security Configuration for CICS Server Adapter

(Sheet 4 of 4)

#
initial_references:IT_SecurityService:reference = "";

policies:csi:auth_over_transport:target_supports =
["EstablishTrustInClient"];

# allow non-CSIv2 based requests to proceed for

# demonstrational purposes. Insert this config item
# to enforce CSIv2 authentication:
#
# policies:csi:auth_over_transport:target_requires =
# ["EstablishTrustInClient"];

policies:csi:auth_over_transport:server_domain_name =
"IONA";

policies:csi:attribute_service:target_supports =
["IdentityAssertion"];

#
# ISF Authorization:
#
# - this variable can be used to disable authorization:
plugins:gsp:enable_authorization = "false";
#
# If the above setting is omitted, or set to true, please
# review the following primary settings for ISF authorization:
#
# - use local store for ACL (default: local):
# plugins:gsp:authorization_policy_store_type = "local";
#
# - and, specify file URL (UTF-8 encoded data in USS):
# plugins:gsp:action_role_mapping_file =
# "file:///my/action/role/mapping.xml";
#
# - or, use centralized support:
# plugins:gsp:authorization_policy_store_type = "centralized";
#
};
};
…

};

215
CHAPTER 17 | Securing the CICS Server Adapter

Summary of global scope The following is a summary of the security-related configuration items
configuration items associated with the global scope:
plugins:security:share_ Enables own security credentials to be
credentials_across_orbs shared across ORBs. Normally, when
you specify an own SSL/TLS
credential (using the principal sponsor
or the principal authenticator), the
credential is available only to the ORB
that created it. By setting this
configuration item to true, however,
the own SSL/TLS credentials created
by one ORB are automatically made
available to any other ORBs that are
configured to share credentials.
policies:mechanism_policy: Specifies the protocol version used by
protocol_version a security capsule (ORB instance). It
can be set to SSL_V3 or TLS_V1.
policies:mechanism_policy: Specifies a list of cipher suites for the
ciphersuites default mechanism policy.
plugins:systemssl_toolkit: Specifies the RACF keyring to be used
saf_keyring as the source of X.509 certificates.
principal_sponsor:use_principal_ This must be set to true to indicate
sponsor that the certificate information is to be
specified in the configuration file.
principal_sponsor:auth_method_id This must be set to security_label
to indicate that the certificate lookup
should be performed using the label
mechanism.
principal_sponsor:auth_method_ If you are using TLS security, this
data specifies the label that should be used
to look up the SSL/TLS certificate in
the SAF key store. The specified label
name must match the label name
under which the server certificate was
imported into, or created in, the key
store (for example, in RACF).

216
 Security Configuration Items

policies:target_secure_ Specifies the invocation policy

invocation_policy:requires required by the server for accepting
secure SSL/TLS connection attempts.
policies:target_secure_ Specifies the invocation policies
invocation_policy:supports supported by the server for accepting
secure SSL/TLS connection attempts.
policies:client_secure_ Specifies the invocation policy
invocation_policy:requires required by the client for opening
secure SSL/TLS connections.
policies:client_secure_ Specifies the invocation policies
invocation_policy:supports supported by the client for opening
secure SSL/TLS connections.
orb_plugins The iiop_tls plug-in must be added
to this list, to enable TLS support.
Note: Remove the iiop plug-in if you
explicitly wish to disable all insecure
communications.

Note: See the Mainframe Security Guide for more details of these
configuration items.

Summary of iSF configuration The following is a summary of the configuration items associated with the
items iona_services:cicsa:isf sample configuration scope:

orb_plugins List of standard ORB plug-ins the

CICS server adapter should load
when running in secure mode.
event_log:filters Specifies the types of events that the
CICS server adapter logs in secure
mode.
binding:server_binding_list Specifies a list of potential
server-side bindings.
plugins:cicsa:direct_persistence Specifies the persistence mode
adopted by the CICS server adapter
service in secure mode. This is an
optional item. iiop_tls:port is
required if this is specified as yes.

217
CHAPTER 17 | Securing the CICS Server Adapter

plugins:cicsa:iiop_tls:port Specifies the TCP/IP port number

that the CICS server adapter uses to
listen for incoming secure requests.
Valid values are in the range 1025–
65535. This is an optional item.
Default is 5106.
plugins:cicsa:iiop:port Specifies the TCP/IP port number
that the CICS server adapter uses to
listen for incoming insecure
requests. Valid values are in the
range 1025–65535. This is an
optional item. Default is 5006.
plugins:cicsa:use_client_ Indicates whether the CICS server
principal adapter should verify the client
principal user ID with SAF before
trying to start the target CICS
program under that ID. The default
is no.
plugins:cicsa:check_security_ Indicates whether the CICS server
credentials adapter should query the CSI
received credentials for a user ID
before defaulting to the GIOP
Principal value, on receiving a client
request.
initial_references: Specifies the IOR for the off-host
IT_SecurityService:reference Security service.
policies:csi:auth_over_transport:t Specifies that the target server
arget_supports supports receiving
username/password authentication
data from the client.
policies:csi:auth_over_transport:t Specifies that the target server
arget_requires requires the client to send
username/password authentication
data.
policies:csi:auth_over_transport:s Specifies the server’s CSIv2
erver_domain_name authentication domain name.
policies:csi:attribute_service: Specifies that the target server
target_supports supports receiving propagated user
identities from the client.

218
 Security Configuration Items

plugins:gsp:enable_authorization Specifies if an iSF authorization

check should be made based upon
the received CSI credentials.
plugins:gsp: Indicates which ACL store to use for
authorization_policy_store_typeobtaining authorization policy
information. A value of local
specifies that the local file system is
to be used. A value of centralized
indicates that the information is to
be obtained using the remote iSF
Security Service. The default is
local.
plugins:gsp: If a local policy store is being used,
action_role_mapping_file this variable must be set to indicate
the location of the authorization
mapping file. A file:// URL must be
specified, and the file itself must
reside in the Unix System Services
file system. In addition, the XML
data in this file must be encoded in
UTF-8.

219
CHAPTER 17 | Securing the CICS Server Adapter

Common Security Considerations

Overview This subsection provides details of common security considerations involved
in using the CICS server adapter. These security considerations are relevant
regardless of which protocol the server adapter is using to communicate
with CICS.
This subsection discusses the following topics:
• Orbix SSL/TLS
• iSF integration
• Client authorization
• SAF plug-in
• Mapping client principal values to z/OS user IDs
• RACF program control

Orbix SSL/TLS Orbix provides transport layer security (TLS) that enables secure connectivity
over IIOP. TLS includes authentication, encryption, and message integrity.
As with all Orbix servers, you can configure the CICS server adapter to use
TLS. See the Mainframe Security Guide for details on securing CORBA
applications with SSL/TLS.

iSF integration The IONA security framework (iSF) provides a common security framework
for all Orbix components in your system. This framework is involved at both
the transport layer (using TLS) and the application layer (using the CORBA
CSIv2 protocol and the Orbix generic security plug-in (GSP)). At the
application level, one of the following authentication credentials can be
passed, using the CSIv2 protocol:
• username/password/domain name
• propagated username
• Single sign-on (SSO) token
You can configure the CICS server adapter to use CSI/GSP support. See the
Mainframe Security Guide for details on iSF and integration with an off-host
Security service.

220
 Common Security Considerations

Client authorization Authorization checks can be performed in the following ways:

• Using the GSP realm/role authorization functionality.
• Using the SAF plug-in, which provides Principal-based access control.
Refer to “SAF plug-in” for more details.
• As part of the Orbix security mechanisms (for example, checking that
the client has invoke rights to the server). Refer to the Mainframe
Security Guide for more details.
• As part of the CICS security mechanisms (for example, checking that
the user is allowed to run the specified program). Refer to “CICS
Security Mechanisms when Using EXCI” on page 223 and “CICS
Security Mechanisms when Using APPC” on page 230 for more
details.
The client’s Principal value is a string that is passed as part of an Orbix
request that identifies the user on the client side. If Orbix SSL/TLS has not
been configured, this value cannot be authenticated in any way.
Sophisticated client-side users could fabricate this value, and therefore gain
access to server-side resources that those users would not otherwise be
allowed to use.

SAF plug-in This Orbix plug-in provides optional Principal-based access control, similar
to that found in IONA’s Orbix 2.3-based mainframe solutions. A server
might accept or reject incoming requests, based upon a CORBA::Principal
value in the request header. The value is treated as a z/OS user ID and
access is checked against an operation-specific SAF profile name. Access
can therefore be controlled on a per-operation basis, or (using generic
profiles) on a per-server basis. More details can be found in the
orbixhlq.DOC PDS which is created as part of the software installation.

Mapping client principal values For the purposes of checking access to CICS resources, the only translation
to z/OS user IDs that the server adapter performs between the client Principal value and the
z/OS user ID is to convert lowercase letters to uppercase. This means that
users must have the same name on the client platform and z/OS.

RACF program control If RACF program control is in use on your system, appropriate RACF
definitions must be defined for Orbix. See your RACF manuals for details.

221
CHAPTER 17 | Securing the CICS Server Adapter

EXCI-Based Security Considerations

Overview This section provides details of security considerations that are specific to
using the EXCI-based server adapter. It describes the various security modes
that the EXCI-based server adapter supports, with particular emphasis on
how each mode affects the existing CICS security mechanisms.

In this section The following topics are discussed in this section:

CICS Security Mechanisms when Using EXCI page 223

Orbix CICS Server Adapter Security Modes for EXCI page 226

222
 EXCI-Based Security Considerations

CICS Security Mechanisms when Using EXCI

Background to CICS security CICS provides a number of mechanisms for securing access to CICS
mechanisms for EXCI resources. The EXCI-based server adapter uses EXCI to transfer data into
and out of a CICS region. It is therefore bound by the security restrictions
that CICS places on it, such as link security, user security, and surrogate
checks.
This subsection discusses the following topics:
• Overview of CICS security mechanisms for EXCI
• MRO logon security
• MRO connect security
• Link security
• User security
• Further reading

Overview of CICS security Figure 7 provides a graphical overview of the security mechanisms that are
mechanisms for EXCI relevant to the operation of the EXCI-based server adapter.

CICS
Orbix CICS Adapter
MRO Connect
Mirror Transaction CICS Program

MRO Logon
Client Transaction
IIOP EXCI
Resource

ID - Principal
Command

ID - Adapter

Figure 7: CICS Security Mechanisms for EXCI-Based Server Adapter

223
CHAPTER 17 | Securing the CICS Server Adapter

MRO logon security CICS EXCI is designed to allow non-CICS programs (such as the server
adapter) to call a program running in a CICS region, without that program
needing to be aware that it has been invoked from outside CICS. The
program runs as if it were being linked to by another CICS program. EXCI
accomplishes this by allowing each EXCI client program to act as a CICS
pseudo-region. EXCI uses MRO logon security to ensure that a particular
user has the authority to start this particular “pseudo-region”. The
pseudo-region is named via the NETNAME attribute of the EXCI connection
that is to be used.
You can use the plugins:cics_exci:pipe_name configuration item to
specify the NETNAME of a particular EXCI SPECIFIC connection, which the
server adapter uses for communicating with CICS. When this connection is
first used, MRO logon security checks that the user ID under which the
server adapter is running is allowed to use that connection. It does this by
checking that the user ID has UPDATE access to the RACF FACILITY class
profile named DFHAPPL.pipename. If the user ID does not have UPDATE
access to this RACF FACILITY class profile, the server adapter cannot send
data into the CICS region.

Note: This check is not made if the server adapter uses the EXCI
GENERIC connection, which is used by default if you do not specify the
plugins:cics_exci:pipe_name configuration item when starting the
server adapter.

MRO connect security MRO connect security is normally used to check the authorization of one
CICS region to access resources in another region. Because CICS EXCI
clients are treated as regions in their own right, this check applies to them
also.
You can use the plugins:cics_exci:pipe_name configuration item to
specify the CICS region to which to connect. Access rights to the CICS
region that is specified with the plugins:cics_exci:pipe_name
configuration item must therefore be checked. This is done by checking for
READ access to a profile named DFHAPPL.applid in the RACF FACILITY
class.

224
 EXCI-Based Security Considerations

Link security Link security checks are made to ensure that a user has access to all the
CICS resources that it wants to use. In the case of the server adapter, the
following checks can occur:
• If CICS transaction-attach security is enabled (that is, XTRAN=YES in the
CICS system initialization parameters), access to the EXCI mirror
transaction (which is specified via the plugins:cics_exci:default_
tran_id configuration item) is checked via the RACF GCICSTRN and
TCICSTRN resource classes.
• If CICS resource security is enabled (that is, RESSEC=ALWAYS in the CICS
system initialization parameters or RESSEC(YES) in the mirror
transaction definition), a whole range of checks can be made for
access to resources used by the EXCI mirror transaction. This can
include checking for access to the program to be run, if XPPT=YES is
specified in the CICS system initialization parameters. It can also
include checking for resources that program might use, such as files (if
XFCT=YES), journals (if XJCT=YES), and other started transactions (if
XPCT=YES).
Refer to the CICS-RACF Security Guide for more details about which
CICS parameters need to be specified to protect the various kinds of
resources.
• If CICS command-security checking is enabled, checks are made if the
program issues system programming-type (SP-type) CICS commands.
Refer to the CICS-RACF Security Guide for more details about these
commands.

User security User security performs the same checks as link security. User security
checks are only made if the EXCI connection that the server adapter uses
(whether GENERIC or SPECIFIC) is defined with the ATTACHSEC(IDENTIFY)
attribute. Otherwise, user security is disabled.

Further reading Refer to the following IBM manuals for full details about securing CICS in
general, and EXCI clients in particular:
• SC33-1185 CICS/ESA CICS-RACF Security Guide
• SC33-1390 CICS/ESA External CICS Interface

225
CHAPTER 17 | Securing the CICS Server Adapter

Orbix CICS Server Adapter Security Modes for EXCI

Overview The Orbix CICS server adapter supports two modes of operation with regard
to security. The two modes are distinguished by which user identity is made
available to CICS for MRO connect and link security checks.
This section discusses the following topics:
• “Determining the user ID” on page 226.
• “Default mode” on page 227.
• “use_client_principal mode” on page 227.
• “Choosing between the two security modes for EXCI” on page 227.
• “check_security_credentials iSF option” on page 228.

Determining the user ID For every incoming client request, the CICS server adapter has two user IDs
at its disposal:
• Its own user ID (that is, the ID under which the server adapter
executable is running). This is always used for MRO logon security
checks.
• The client user ID (that is, the Principal value converted to uppercase,
and potentially truncated, to match the requirements of z/OS). This is
always used for CICS user security checks (if they are enabled).
By default, the client user ID is the string value that is passed in the GIOP
Principal field. For GIOP 1.2 or later versions, the CORBA::Principal field
has been deprecated; however, as an alternative, Orbix can be configured to
pass the Principal user ID in a special service context that is marshaled by
the GIOP plug-in.
For installations that have been configured to use the Security service, the
client user ID can be obtained from the CSI received credentials. If a user ID
is not available in the security credentials, the GIOP Principal value is used
instead. See “check_security_credentials iSF option” on page 228 for more
details.
The Orbix CICS security mode that is chosen when starting the server
adapter determines the mode used for CICS MRO connect and link security.

226
 EXCI-Based Security Considerations

Default mode In the default mode, it is the user ID of the server adapter itself that CICS
uses to verify access to the region, the EXCI mirror transaction, and the
other items already described. If CICS resource security is enabled (that is,
RESSEC=YES on the mirror transaction definition, or RESSEC=ALWAYS in the
CICS system initialization parameters), this can include a check for access
to the program being invoked and the resources it uses. This means that the
server adapter’s user ID must be given access to every CICS resource that
any potential client can access. Otherwise, the incoming request fails, even
though the client itself does have access to every CICS resource it needs.
Running in default mode means that the only security checks made against
the client principal are user security checks for EXCI, and then only if user
security is enabled.

use_client_principal mode If you set the plugins:cicsa:use_client_principal configuration item to

yes, the client Principal is used for the two types of checks. In this mode,
the server adapter is more transparent, and security checking is similar to
that of a user working from a 3270 terminal. Although the user now
requires access to the CICS region (the connect check) and the mirror
transaction (one of the link checks), the remaining resources that user needs
access to should be the same as if that user had signed in from a terminal.
If the use_client_principal configuration item is specified, user security
checks (which duplicate the link security checks) become redundant and
should be disabled by setting ATTACHSEC(LOCAL) on the connection.

Choosing between the two The following table summarizes which user ID is used for the CICS security
security modes for EXCI checks in the two modes:

Table 8: Summary of user IDs used for the CICS Security Checks

Mode MRO Logon MRO Connect Link User

Default Server Adapter Server Server Principal

Adapter Adapter

plugins:cicsa_:use_client_principal Server Adapter Principal Principal Principal

227
CHAPTER 17 | Securing the CICS Server Adapter

Note: In default mode, if the client request does not contain a user
principal, the server adapter's user ID is used for user security. This is
because the server adapter's user ID is the only one available in this case.
This does not apply to use_client_principal mode, where such requests
are rejected by the server adapter.

check_security_credentials iSF If you set the plugins:cicsa:check_security_credentials configuration

option item to yes, the CICS server adapter queries the CSI received credentials for
a user ID before defaulting to the GIOP Principal value, on receiving a client
request. Assuming that the CICS server adapter is running in
use_client_principal mode, it then attempts to verify that this user ID is
authorized to run the specified transaction.
When using the check_security_credentials iSF option, the client access
ID that is used is one of the following (in order of priority):
1. The propagated user ID that is passed using the identity assertion
mechanism.
2. The GSSUP token username
3. The GIOP Principal.
If a user ID is not available from any of these sources, the client request is
rejected.

Note: The check_security_credentials iSF option only takes effect if

the Orbix domain has been configured to use iSF. See the Mainframe
Security Guide for more details.

228
 APPC-Based Security Considerations

APPC-Based Security Considerations

Overview This section provides details of security considerations that are specific to
using the APPC-based server adapter. It describes the various security
modes that the APPC-based server adapter supports, with particular
emphasis on how each mode affects the existing CICS security mechanisms.

In this section The following topics are discussed in this section:

CICS Security Mechanisms when Using APPC page 230

Orbix CICS Server Adapter Security Modes for APPC page 236

229
CHAPTER 17 | Securing the CICS Server Adapter

CICS Security Mechanisms when Using APPC

Overview of APPC (LU 6.2 APPC is an implementation of the SNA LU 6.2 protocol for
Protocol) program-to-program communication across networks. An LU allocates a
conversation to another LU and exchanges data with it. LU 6.2 defines a
number of characteristics that can be established for a conversation. These
include throughput, transactional behavior, and levels of security. APPC
provides a set of programming interfaces that are used to construct
programs that can send or receive LU 6.2 conversations.
This subsection discusses the following topics:
• Overview of CICS security mechanisms for APPC
• Characteristics of the APPC-based server adapter
• LU 6.2 conversation security levels
• Preventing unauthorized access
• Security for users already logged on
• Session-level verification
• APPCLU class profiles
• Restricting authorized use of LU names
• Setting bind security on CONNECTION resource

230
 APPC-Based Security Considerations

Overview of CICS security Figure 8 provides a graphical overview of the security mechanisms that are
mechanisms for APPC relevant to the operation of the APPC-based server adapter.

CICS
Orbix CICS Adapter
APPC Verify
CICS Program

Client Transaction
IIOP APPC
Resource

ID - Principal
Command

ID - Adapter

Figure 8: CICS Security Mechanisms for APPC-Based Server Adapter

Characteristics of the APPC-based The APPC-based server adapter has been constructed as an outbound LU.
server adapter This means that it accepts data from CORBA clients on a TCP/IP network,
sends that data on to the CICS LU via an LU 6.2 conversation, and then
returns the data it receives from CICS back to the TCP/IP network.

LU 6.2 conversation security The LU 6.2 protocol, of which APPC/MVS is an implementation, defines
levels three levels of conversation security:
security_none No user identification is passed during the conversation.
Access to resources on the receiving (inbound) side is
limited to those that are universally available. In RACF
terms, this means that the only resources used are those
protected by profiles with a UACC other than NONE.

231
CHAPTER 17 | Securing the CICS Server Adapter

security_same The identity of the initiating (outbound) user is passed

when starting the conversation. On the receiving side,
access is granted to all resources for which that user has
appropriate permissions. Essentially, the program
running on the receiving side is expected to have the
same access privileges as if the user had logged in
directly. No authentication of the user is performed,
because the inbound side of the conversation is expected
to pass an already verified flag, to indicate that the
user’s identity has already been checked.
The CICS server adapter attempts to use security_same
when allocating its conversations with the APPC/CICS
inbound transaction program. This allows the CICS
transaction that is being scheduled to be associated with
a particular user, so that existing CICS mechanisms can
be used for resource-access checking and auditing.
However, security_none might be used if VTAM refuses
already verified connections to the LU. Refer to
“Session-level verification” on page 234 for further
details.
security_pgm The initiating side sends a user identity value to be used
on the receiving side. This is not necessarily the identity
of the user initiating the conversation. The program on
the receiving side is expected to run with the privileges of
the specified user. For authentication purposes, the
inbound side must also send an associated password
value for the user, which is checked via RACF services.
A conversation using security_pgm is not possible with
the CICS server adapter, because it has no access to
passwords for its clients.

Note: Although the LU 6.2 protocol can be used for network

communication, the CICS server adapter is only intended to be run on the
same machine as the CICS region with which it is communicating.

232
 APPC-Based Security Considerations

Preventing unauthorized access Generally, in a network environment, it is a ridiculous idea that a client
should be authenticated by a server merely on the basis that it claims to
have been already-verified. After all, it is possible for a sophisticated user
on a workstation to forge any desired identity merely by fabricating the
appropriate LU 6.2 protocol exchanges with the z/OS host. Therefore, to
prevent such unauthorized access, z/OS provides a way to specify what
information must be passed, to connect to a particular LU. This is done by
specifying the SECACPT=CONV key in the APPL definition for the VTAM ACB
associated with the LU.
When allocating a conversation with an LU defined in this way, the initiating
LU must provide a user ID and password: the already-verified indicator is
not accepted. If the required data is not passed, VTAM permits the
connection, but the level of conversation security is reduced to
security_none, and only universally available resources are accessible on
the receiving side. Therefore, to get access to resources on the inbound side,
the outbound user must provide a password.

Security for users already logged Consider the special case of a user already logged onto the host, who is
on using APPC/MVS to communicate with an LU on the same z/OS host. This
is known as an LU=LOCAL conversation. In this case, the security information
that is passed between the two sides for a security_same conversation is
contained entirely within APPC/MVS itself: the outbound LU extracts the
user’s identity automatically for presentation to the inbound LU. There is no
opportunity for the user to insert a fabricated identity. In such cases, there
should be no need for APPC/MVS to enforce the password requirement: the
user has already provided a password to gain access to the host in the first
place.
When running on z/OS, the CICS server adapter is in a similar situation to a
logged-on user. If it initiates conversations to the CICS LU under its own
identity (the default mode), that identity has either been verified when the
user that started the server adapter logged on (if the server adapter is
submitted as a job or started interactively), or it has been assigned by the
security product when the work is started by an operator (if the server
adapter is run as a started task).

233
CHAPTER 17 | Securing the CICS Server Adapter

Even if the server adapter is initiating conversations under the identity of its
clients, with the plugins:cicsa:use_client_principal configuration item
set to yes, it can only do that if it is running under a user ID that has been
given authority to do that. Additionally, it must have gone through at least
one of the checks already mentioned, to run under that user ID.

Session-level verification A secure but efficient APPC environment is, therefore, one that permits only
security_pgm conversations from remote machines, but which allows
security_same for LU=LOCAL conversations. In fact, prior to OS/390 V1R3,
this is what APPC/MVS provided for LUs defined with SECACPT=CONV,
because VTAM did not enforce the SECACPT=CONV specification for LU=LOCAL
conversations. Since OS/390 V1R3, however, this is enforced1, so an
alternate means of allowing security_same for LU=LOCAL conversations must
be used. This is accomplished on z/OS, using session-level verification.
Session-level verification introduces the concept of a session key that can be
used instead of a password for conversations between two specific LU
names only. If VERIFY=OPTIONAL is coded on the APPL definition of the VTAM
ACB for an LU, VTAM allows a security_same conversation to be
established, provided the other LU can correctly respond to a demand for
the session key that has been defined for these two LU names. On z/OS,
these session keys are maintained by RACF in APPCLU class profiles.

APPCLU class profiles APPCLU class profiles have names that take the following form:

‘networkid.local-lu-name.partner-lu-name’

They contain information to be used by APPC/MVS on one side of a

conversation. Even if both LUs are on the same z/OS host, each LU
examines a different profile, because each side of the conversation considers
itself to be the local LU.

1. Refer to the IBM publication GC28-1747 OS/390 V1R3.0 MVS

Conversion Notebook for more details.

234
 APPC-Based Security Considerations

For example, if an LU named OUTLU initiates a conversation with an LU

named INLU that has SECACPT=CONV and VERIFY=OPTIONAL coded on its
ACB, APPC/MVS on the inbound side determines the correct session key by
consulting the networkid.INLU.OUTLU APPCLU profile. On the outbound
side, when challenged for a session key, the initiating APPC/MVS consults
the networkid.OUTLU.INLU profile, for the key value to return. VTAM, on
the inbound side, permits the conversation to proceed as security_same,
only if the key values in the two profiles match and CONVSEC(ALREADYV) is
also coded in the inbound APPCLU profile.

Restricting authorized use of LU Additionally, because session-level verification is performed on the basis of
names LU name rather than on the basis of user name, it is necessary to restrict
the users that are authorized to use those particular LU names. This is done
via the RACF APPCPORT class. By defining a profile in this class with the
name of an LU, you can use its access list to control who can initiate or
accept APPC conversations with that LU on this system.

Setting bind security on The aim of the APPC-based server adapter is to integrate with CICS in such
CONNECTION resource a way that all the existing mechanisms continue to work. For CICS and
APPC, this is regulated by the setting of the bind security on the CONNECTION
resource, as described in “Bind Time Security with APPC” on page 106.

235
CHAPTER 17 | Securing the CICS Server Adapter

Orbix CICS Server Adapter Security Modes for APPC

Overview The APPC-based CICS server adapter supports two modes of operation with
regard to security. These are discussed as follows:
• Default mode
• use_client_principal mode

Default mode In the default mode, CICS and APPC use the server adapter’s user ID to
verify access to the LU names, to the CICS region, to the CICS transaction,
to databases, and so on. This means that the server adapter’s user ID must
be given access to not just the APPC resources, but also to every CICS
resource that any potential client can access. Otherwise, an incoming
request might fail, even though the client itself has access to every CICS
resource it needs.

use_client_principal mode If you set the plugins:cicsa:use_client_principal configuration item to

yes, the server adapter assumes the identity of the client before initiating
the APPC conversation. This means that the client Principal is used for the
APPC and CICS checks. In this mode, the server adapter is somewhat more
transparent, and security checking is similar to that of a user working from a
3270 terminal. Although users now require access to the server adapter LU
and the CICS LU, the remaining resources to which users need access
should be the same as if they had signed in from a terminal.
The plugins:cicsa:use_client_principal mode works by having the
server adapter use the services of z/OS to establish a thread-level security
environment with the identity of the client for portions of its processing. This
causes APPC and CICS to use that user ID for their checks. This does incur
some extra overhead on each client request compared to the default mode.

236
 CHAPTER 18

Mapping IDL
Interfaces to CICS
This chapter provides information on how a CICS server
adapter exposes CICS transactions as CORBA servers. It details
the role that the mapping file plays in mapping CORBA
operations and attributes for a given interface to a target
transaction. It also details the role of the type information
source (IFR or type_info store) in marshalling data from a client
request.

In this chapter This chapter discusses the following topics:

The Mapping File page 238

Using the IFR as a Source of Type Information page 244

Using type_info store as a Source of Type Information page 254

237
CHAPTER 18 | Mapping IDL Interfaces to CICS

The Mapping File

Overview This section describes how the mapping file is used by the CICS server
adapter. It also describes the contents of the file and how it can be
generated using the Orbix IDL compiler.

In this section This section discusses the following topics:

Characteristics of the Mapping File page 239

Generating a Mapping File page 241

238
 The Mapping File

Characteristics of the Mapping File

Overview This subsection describes the mapping file, its format, how it supports IDL
attributes, and its relationship with type information sources. It discusses
the following topics:
• Description
• Mapping file format
• Support for IDL attributes

Description The mapping file is a simple text file that determines what interfaces and
operations the CICS server adapter supports, and the transaction names to
which it should map each operation. The file is read when the CICS server
adapter starts, and can be written or re-read during the server adapter
operation by using the MappingGateway interface or the itadmin mfa
commands. Refer to “Making runtime modifications to mappings” on
page 243 for more details.

Mapping file format Each mapping entry in the file is specified as a tuple that specifies the
following:

(interface name, operation name, CICS program/transaction name)

Tuples can span lines. All white space (including blanks embedded in
names) is ignored.
In the tuples, if an IDL interface is scoped within a module or modules, the
module name or names must then be included in the interface name. The
module names are separated from each other and from the interface name
with / characters. The interface name therefore has the following layout if it
is scoped within two modules:
module_name/module_name/interface_name
For the EXCI plug-in, the third element in the tuple is an eight character
program name. This is the program name of the Orbix server running inside
CICS for this interface and operation. For the APPC plug-in, the third
element in the tuple is a four character transaction name. This is the
transaction name that is used by APPC to run the Orbix server inside CICS
for this interface and operation.

239
CHAPTER 18 | Mapping IDL Interfaces to CICS

Additionally, for the EXCI plug-in, you can also choose to specify the EXCI
mirror transaction for each individual entry in the mapping file. In this case,
each mapping in the file is specified as follows:

(interface_name, operation_name, program_name:mirror_tran_name)

For example, the following entry maps the set operation on the simple
interface (see the Simple IDL below) to the SIMPLESV CICS program and
ORX2 EXCI mirror transaction:

(Simple/SimpleObject, call_me, SIMPLESV:ORX2)

Ensure that there are no spaces before or after the colon that separates the
CICS program name and mirror transaction name. If the mirror transaction
name is not specified, which is the default situation, the server adapter uses
the transaction name that you can specify with the
plugins:cics_exci:default_tran_id configuration item when starting the
server adapter.

Support for IDL attributes Attributes of IDL interfaces are supported by using _get_attribute and
_set_attribute to read and write a particular attribute. For example,
consider the Simple IDL:

module Simple {
interface SimpleObject
{
void
call_me();
};
};

The following file maps the operation call_me on the SimpleObject

interface to the CICS transaction named SIMPLESV:
(Simple/SimpleObject, call_me, SIMPLESV)
If the SimpleObject interface had a read-only attribute; for example,
something (which it does not have in the sample application supplied by
IONA), it needs an entry as follows in the mapping file:
(Simple/SimpleObject, _get_something, SIMPLESV)
Because the something attribute of the SimpleObject interface is specified
as read-only in the IDL file, no _set_something operation is necessary.

240
 The Mapping File

Generating a Mapping File

Overview An IDL compiler plug-in is available, called mfa, that is used to generate
CICS server adapter mapping files.
This subsection discusses the following topics:
• Adapter mapping file versus other mapping files
• Sample IDL
• Generating mapping files on z/OS UNIX System Services
• Generating mapping files on native z/OS
• Making runtime modifications to mappings

Adapter mapping file versus other The CICS server adapter mapping file is completely unrelated to the
mapping files mapping file used by the COBOL and PL/I IDL compilers. The CICS server
adapter mapping file is used by the server adapter to select which
transaction to run inside CICS, while the mapping file used by the COBOL
and PL/I IDL compilers changes the names of specific items of source code
generated by the IDL compiler.

Sample IDL The code samples for generating a CICS server adapter mapping file are
based on Simple IDL:

module Simple {
interface SimpleObject
{
void
call_me();
};
};

241
CHAPTER 18 | Mapping IDL Interfaces to CICS

Generating mapping files on z/OS To generate a mapping file on z/OS UNIX System Services, run the following
UNIX System Services command:

idl -mfa:-tSIMPLESV simple.idl

The -t parameter specifies the program or transaction that is run inside

CICS for each IDL operation. For EXCI, it is the eight-character program
name. For APPC, it is the four-character transaction name.
Refer to “Mapping file format” on page 239 for details of the format of the
mapping file generated.

Generating mapping files on The following is an example of JCL you can use to generate a mapping file
native z/OS on native z/OS:

//MAPFILE JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//*
//* Generate an operation mapping file CICS Server Adapter
//*
//IDLMAP EXEC ORXIDL,
// SOURCE=SIMPLE,
// IDL=&ORBIX..DEMO.IDL,
// IDLPARM='-mfa:-tSIMPLESV'
//IDLMFA DD DISP=SHR,DSN=&ORBIX..DEMO.CICS.MFAMAP

The -t parameter specifies the program or transaction that is run inside

CICS for each IDL operation. For EXCI, it is the eight-character program
name. For APPC, it is the four-character transaction name.

Note: If the -mfa option is specified to the Orbix IDL compiler, the IDLMFA
DD statement defines the PDS used to store the generated CICS server
adapter mapping file.

242
 The Mapping File

Refer to “Mapping file format” on page 239 for details of the format of the
mapping file generated.

Making runtime modifications to A CICS server adapter caches mapping files internally during execution. This
mappings cache can be modified allowing mappings to be added, changed, or deleted.
This functionality is exposed by the itadmin mfa command (refer to “Using
the MappingGateway Interface” on page 272 for a complete list of itadmin
mfa commands). The syntax is as follows:

mfa
add -interface <name> -operation <name> <mapped value>
change -interface <name> -operation <name> <mapped value>
delete -interface <name> -operation <name>

The contents of this internal cache can be re-written (using mfa save) to file,
to ensure that the mapping file is kept up-to-date. To refresh an internal
cache from file, you can use mfa reload or mfa switch. The syntax is as
follows:

mfa
reload
save [<mapping_file name>]
switch <mapping_file name>

243
CHAPTER 18 | Mapping IDL Interfaces to CICS

Using the IFR as a Source of Type Information

Overview This section describes how the IFR can be used as the source of type
information by the CICS server adapter.

In this section This section discusses the following topics:

Introduction to Using the IFR page 245

Registering IDL interfaces with the IFR page 247

Informing CICS Server Adapter of a New Interface in the IFR page 250

Using an IFR Signature Cache file page 252

244
 Using the IFR as a Source of Type Information

Introduction to Using the IFR

Overview This subsection introduces how the IFR can be used to supply type
information to the CICS server adapter. It details how interfaces can be
registered with the IFR, and the operation of the server adapter when using
the IFR. It also describes how an IFR cache can be employed to improve
performance.
This subsection discusses the following topics:
• Description of the IFR
• Configuration of the IFR
• Operation of IFR when no IFR signature cache file is specified
• Steps for using the IFR

Description of the IFR The IDL for the interfaces and operations specified in the mapping file must
be available to the IFR server that the CICS server adapter uses. This
information is required by the server adapter to marshal a request from a
client. Therefore, IDL for supported interfaces must be added to the IFR.
The steps for doing this are detailed below. To improve performance the IFR
can be used with an optional IFR signature cache file.

Configuration of the IFR If you want to use the IFR you must ensure that the appropriate
configuration variables are set. Additionally, if you want to use an IFR
signature cache file, the relevant configuration variable must also be set.
Refer to “IFR signature cache file” on page 85 for more information.

Operation of IFR when no IFR The server adapter contacts the IFR during start-up and attains operation
signature cache file is specified signatures for operations defined in the mapping file. If an operation
signature changes (for example, changing the return type from void to
float) and the server adapter is notified (for example, if itadmin mfa
refresh is called), it contacts the IFR to retrieve this modified signature.
If you want to use the IFR signature cache file refer to “Using an IFR
Signature Cache file” on page 252.

245
CHAPTER 18 | Mapping IDL Interfaces to CICS

Steps for using the IFR To use the IFR follow these steps:

Step Action

1 Register IDL interfaces with the IFR. Refer to “Registering

IDL interfaces with the IFR” on page 247 for further details.

2 Inform the CICS server adapter that the contents of the IFR
have been modified. Refer to “Informing CICS Server
Adapter of a New Interface in the IFR” on page 250 for
more details.

246
 Using the IFR as a Source of Type Information

Registering IDL interfaces with the IFR

Overview This subsection describes how to register IDL interfaces with the IFR. It
discusses the following topics:
• Sample IDL
• Registering IDL on native z/OS
• Registering IDL on z/OS UNIX System Services
• Specifying a -ORB argument

Sample IDL The code samples for registering IDL with the IFR are based on the following
Simple::SimpleObject interface in the simple.idl file:

module Simple {
interface SimpleObject
{
void
call_me();
};
};

247
CHAPTER 18 | Mapping IDL Interfaces to CICS

Registering IDL on native z/OS To add IDL (for example, the SIMPLE IDL member) to the IFR on native z/OS,
use the following JCL:

//ADDIFR JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//* Make the following changes before running this JCL:
//*
//* 1. Change 'SET DOMAIN='DEFAULT@' to your configuration
//* domain name.
//*
// SET DOMAIN='DEFAULT@'
//*
//* Add an interface to the IFR
//*
//IDLMAP EXEC ORXIDL,
// SOURCE=SIMPLE,
// IDL=&ORBIX..DEMO.IDL,
// IDLPARM='-R'
//ITDOMAIN DD DSN=&ORBIXCFG(&DOMAIN),DISP=SHR

Registering IDL on z/OS UNIX To add IDL (for example, the simple.idl file) to the IFR on z/OS UNIX
System Services System Services, use the following command:

$ idl -R simple.idl

248
 Using the IFR as a Source of Type Information

Specifying a -ORB argument When registering IDL with the IFR, the idl -R command invokes an IDL
back end that acts as a CORBA client to the IFR server. The client sends the
IDL definitions by invoking CORBA calls on the IFR. Therefore, you might
want to specify an ORB argument that can be used in the client’s
ORB_init() call before it communicates with the IFR. For example, to
specify a different Orbix domain name on z/OS UNIX System Services, enter
the following command:

idl -R:-ORBdomain_name=domain2

249
CHAPTER 18 | Mapping IDL Interfaces to CICS

Informing CICS Server Adapter of a New Interface in the IFR

Overview After you add an interface to the IFR, the CICS server adapter must be
notified for the updates to take effect. If adding support for a new interface
or operation, the itadmin mfa add command can be used. In addition to
creating a new binding between operation and CICS transaction in the
mapping file, it also causes the CICS server adapter to contact the IFR to
retrieve the operation signature for the new operation.
This subsection discusses the following:
• Informing the server adapter of a new IDL interface on native z/OS
• Informing the server adapter of a new IDL interface on z/OS UNIX
System Services
• Notifying the server adapter of modifications to the IFR

Informing the server adapter of a To inform the CICS server adapter that the SimpleObject interface (see
new IDL interface on native z/OS “Sample IDL” on page 241 for an example) has been added to the IFR on
native z/OS, use the following JCL:

//ADDMFA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//* Make the following changes before running this JCL:
//*
//* 1. Change 'SET DOMAIN='DEFAULT@' to your configuration
//* domain name.
//*
// SET DOMAIN='DEFAULT@'
//*

250
 Using the IFR as a Source of Type Information

//* Add an interface mapping to the CICS Adapter

//*
//CICSADD EXEC ORXADMIN,
// PPARM='-ORBname iona_services.cicsa'
//SYSIN DD *
mfa add \
–interface Simple/SimpleObject \
–operation call_me \
SIMPLESV
/*
//ITDOMAIN DD DSN=SHR,DSN=&ORBIXCFG(&DOMAIN),DISP=SHR

Informing the server adapter of a To inform the CICS server adapter that the SimpleObject interface (see
new IDL interface on z/OS UNIX “Sample IDL” on page 241 for an example) has been added to the IFR on
System Services z/OS UNIX System Services, use the following command:

$ itadmin –ORBname iona_services.cicsa mfa add –interface

Simple/SimpleObject –operation call_me SIMPLESV

Notifying the server adapter of The itadmin mfa refresh command is used to notify the CICS server
modifications to the IFR adapter that an already supported operation signature has changed. It
causes the CICS server adapter to contact the IFR and retrieve the updated
operation signature and place this in its internal cache.
You can also use refreshInterface() or refreshOperation(). These
functions are available via the MappingGateway interface and can be used to
refresh the server adapter’s internal cache of operation signatures by
contacting the IFR. This requires that a corresponding entry exist for the
operation(s) in the mapping file.

251
CHAPTER 18 | Mapping IDL Interfaces to CICS

Using an IFR Signature Cache file

Overview This subsection describes how an IFR signature cache file can be used in
conjunction with the IFR to improve performance of the CICS server adapter.
It discusses the following topics:
• Prerequisites to using the IFR signature cache file
• First run of the server adapter after configuration
• Subsequent runs of the server adapter
• Runtime modifications to the IFR
• Updating an IFR signature cache file

Prerequisites to using the IFR Before you use a signature cache file you must specify the name of the
signature cache file signature cache file you want to use, in the plugins:cicsa:ifr:cache
configuration item in the iona_services:cicsa configuration scope. Refer to
“IFR signature cache file” on page 85 for more details.

First run of the server adapter after When the server adapter is started after this configuration item is set, a new
configuration signature cache file is generated with this name, and the contents of the IFR
are saved to it. If an operation signature is not available for an operation
defined to the CICS server adapter via the mapping file, a warning message
is output. For example, the warning message for an IDL interface called
Simple/SimpleObject with a single operation called call_me is similar to
the following:

Tue, 03 Dec 2002 12:35:30.0000000 [MYMACHINE:16777601]

(IT_MFA:100) W - synchronization problem occurred for mapping
(Simple/SimpleObject,call_me) - unable to obtain type
information for the operation

Subsequent runs of the server With subsequent runs of the server adapter the IFR is not contacted during
adapter start-up. Instead it reads the list of operation signatures directly from the
signature cache file. This should lead to an improvement in how long it
takes to start the server adapter, especially if you need to start multiple
server adapters simultaneously. This means the server adapters can be
ready and available more quickly for client requests.

252
 Using the IFR as a Source of Type Information

Runtime modifications to the IFR During runtime, the CICS server adapter can contact the IFR to load or
refresh an operation entry. Upon shutdown, the server adapter updates the
signature cache file with the operation signatures it has used.

Note: The IFR signature cache file is only ever accessed twice. First, it is
accessed in read mode during start-up. This boosts performance by
preventing the IFR being contacted initially. Second, it is accessed in write
mode during shutdown. This dumps the operation signatures used by the
server adapter to a signature cache file, so that this can be used when the
server adapter is restarted.

Updating an IFR signature cache If type information subsequently changes in the IFR, you can update the
file information in the signature cache file using refreshInterface() or
refreshOperation().
If you are using the IFR signature cache file, either or both of these can be
used on the MappingGateway interface, to consult the IFR and update the
cached IFR operation signatures in-memory in the CICS server adapter with
a specified interface or operation (or both).

253
CHAPTER 18 | Mapping IDL Interfaces to CICS

Using type_info store as a Source of Type

Information
Overview This section describes how a type_info store can be used as the source of
type information by the CICS server adapter.

In this section This section discusses the following topics:

Introduction to Using a type_info Store page 255

Generating type_info Files using the IDL Compiler page 257

Informing CICS Server Adapter of a new type_info Store File page 259

254
 Using type_info store as a Source of Type Information

Introduction to Using a type_info Store

Overview This section describes the type_info store in terms of how the Orbix IDL
compiler can be used to generate these files, the operation of the server
adapter when using a type_info store, and how the store can be updated.
This section discusses the following topics:
• Description
• Configuration
• Operation of CICS server adapter using type_info stores
• Steps for using a type_info store

Description The type_info store is one method of supplying IDL interface information to
the CICS server adapter. It is an alternative approach to the IFR, and uses a
file-based approach to represent operation signatures. The CICS server
adapter can access these files at start-up and runtime, to obtain operation
signatures, which it requires to marshal data from the CORBA client.

Note: If you are using a type_info store, the CICS server adapter does not
require the IFR. This means that a CICS server adapter that is using a
type_info store can be run in standalone mode, by configuring it to run in
direct persistent mode.

Configuration If you want to use a type_info source you must ensure that the appropriate
configuration items are set. Refer to “type_info store” on page 86 for more
information.

Operation of CICS server adapter The Orbix IDL compiler generates type_info files. When the CICS server
using type_info stores adapter is started it accesses the type_info store and, for all operations for
which an operation-to-transaction mapping entry exists, it loads the
operation signatures into an internal cache. These operation signatures are
required by the CICS server adapter to unmarshal operation arguments from
a client request, and to marshal the response back.

255
CHAPTER 18 | Mapping IDL Interfaces to CICS

During runtime, the type_info store can be updated dynamically (for

example, to add support for a new interface, or to reflect a change in one or
more operation signatures). This simply requires generating a new type_info
file and then requesting the CICS server adapter to refresh its internal
operation signature cache with the latest version in the type_info store.

Steps for using a type_info store To use a type_info store do the following:

Step Action

1 Use the IDL compiler to generate (or regenerate for subsequent

additions or other modifications) a type_info file for IDL. Refer
to “Generating type_info Files using the IDL Compiler” on
page 257 for further details.

2 Inform the CICS server adapter of a new or modified interface.

Refer to “Informing CICS Server Adapter of a new type_info
Store File” on page 259 for further details.

256
 Using type_info store as a Source of Type Information

Generating type_info Files using the IDL Compiler

Overview This subsection describes the process of generating type_info store files. It
discusses the following topics:
• Sample IDL
• On z/OS UNIX System Services
• On native z/OS

Sample IDL The code samples for generating a type_info file are based on Simple IDL

module Simple {
interface SimpleObject
{
void
call_me();
};
};

On z/OS UNIX System Services To generate a type_info file on z/OS UNIX System Services for the Simple
IDL, run the IDL compiler as follows:

idl –mfa:-inf simple.idl

This generates a type_info file named simpleB.inf.

Note: By default, the mfa backend generates type_info files with a suffix
of B. This can be modified by editing the MFAMappings scope in
orbixhlq.CONFIG(IDL).

257
CHAPTER 18 | Mapping IDL Interfaces to CICS

On native z/OS To generate a type_info file on native z/OS for the Simple IDL, submit the
following JCL to run the IDL compiler:

//ADDMFA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//*
//* Add an interface mapping to the CICS Server Adapter
//*
//IDLCBL EXEC ORXIDL,
// SOURCE=SIMPLE,
// IDL=&ORBIX..DEMO.IDL,
// COPYLIB=&ORBIX..DEMO.CICS.CBL.COPYLIB,
// IMPL=&ORBIX..DEMO.CICS.CBL.SRC,
// IDLPARM='-mfa:-inf'
//IDLTYPEI DD DISP=SHR,DSN=&ORBIX..DEMO.TYPEINFO

This generates a type_info file named orbixhlq.DEMO.TYPEINFO(SIMPLEB).

Note: By default, the mfa backend generates type_info files with a suffix
of B. This can be modified by editing the MFAMappings scope in
orbixhlq.CONFIG(IDL).

Note: If the -mfa:-inf option is specified to the Orbix IDL compiler, the
IDLTYPEI DD statement defines the PDS used to store the generated
type_info file.

258
 Using type_info store as a Source of Type Information

Informing CICS Server Adapter of a new type_info Store File

Overview After you add a file to the type_info store, the CICS server adapter must be
notified for the updates to take effect. If adding support for a new interface
or operation, the itadmin mfa add command can be used. In addition to
creating a new binding between operation and CICS transaction in the
mapping file, it also causes the CICS server adapter to access the type_info
store to retrieve the operation signature for the new operation.
This subsection discusses the following:
• Informing the server adapter of a new IDL interface on native z/OS
• Informing the server adapter of a new IDL interface on z/OS UNIX
System Services
• Notifying the server adapter of modifications to the type_info store

Informing the server adapter of a To inform the CICS server adapter that the SimpleObject interface (see
new IDL interface on native z/OS “Sample IDL” on page 257 for an example) has been added to the type_info
store on native z/OS, use the following JCL:

//ADDMFA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//* Make the following changes before running this JCL:
//*
//* 1. Change 'SET DOMAIN='DEFAULT@' to your configuration
//* domain name.
//*
// SET DOMAIN='DEFAULT@'
//*
//* Add an interface mapping to the CICS Adapter
//*

259
CHAPTER 18 | Mapping IDL Interfaces to CICS

//CICSADD EXEC ORXADMIN,

// PPARM='-ORBname iona_services.cicsa'
//SYSIN DD *
mfa add \
–interface Simple/SimpleObject \
–operation call_me \
SIMPLESV
/*
//ITDOMAIN DD DSN=&ORBIXCFG(&DOMAIN),DISP=SHR

Informing the server adapter of a To inform the CICS server adapter that the SimpleObject interface (see
new IDL interface on z/OS UNIX “Sample IDL” on page 257 for an example) has been added to the type_info
System Services store on z/OS UNIX System Services, use the following command:

$ itadmin –ORBname iona_services.cicsa mfa add –interface

Simple/SimpleObject –operation call_me SIMPLESV

Notifying the server adapter of The itadmin mfa refresh command is used to notify the CICS server
modifications to the type_info adapter that an already supported operation signature has changed. (Refer
store to “Using the MappingGateway Interface” on page 272 for a complete list of
itadmin mfa commands.) It causes the CICS server adapter to access the
type_info store and retrieve the updated operation signature and place this
in its internal cache.
You can also use refreshInterface() or refreshOperation(). These
functions are available via the MappingGateway interface and can be used to
refresh the server adapter’s internal cache of operation signatures by
accessing the type_info store. This requires that a corresponding entry exists
for the operation(s) in the mapping file.

260
 CHAPTER 19

Using the CICS

Server Adapter
This chapter provides information on running and using the
CICS server adapter. It provides details on how to start and
stop the server adapter. It provides details on how to use the
server adapter to act as a dynamic bridge to pass IDL-based
requests into CICS. It describes how to use the
MappingGateway interface of the server adapter. It also
explains how to add a portable interceptor to the server adapter
and gather accounting information in the server adapter.

In this chapter This chapter discusses the following topics:

Preparing the Server Adapter page 263

Starting the Server Adapter page 267

Stopping the CICS Server Adapter page 269

Running Multiple Server Adapters Simultaneously page 270

Using the MappingGateway Interface page 272

Locating CICS Server Adapter Objects Using itmfaloc page 275

Adding a Portable Interceptor to the CICS Server Adapter page 278

261
CHAPTER 19 | Using the CICS Server Adapter

Enabling the GIOP Request Logger Interceptor page 289

Gathering Accounting Information in the Server Adapter page 291

Exporting Object References at Runtime page 298

262
 Preparing the Server Adapter

Preparing the Server Adapter

Overview This section describes what needs to be done to run the server adapter in
prepare mode. It discusses the following topics:
• Prerequisites to running the server adapter in prepare mode
• Running the CICS server adapter in prepare mode
• Sample JCL to run the CICS server adapter in prepare mode
• Location of CICS server adapter IORs
• The IT_MFA IOR
• The IT_MFA_CICSRAW IOR
• Sample configuration file
• Running the CICS server adapter on z/OS UNIX System Services

Prerequisites to running the server If you are using a type_info store as the type information source (as is the
adapter in prepare mode default), you can run the CICS server adapter in standalone mode, if you
wish. This requires setting the CICS server adapter to run in direct persistent
mode. In direct persistent mode, the CICS server adapter does not require
the other Orbix Mainframe services.
If you are using the IFR as the type information source, you must first run
the locator, node daemon, and IFR in prepare mode. Ensure that these are
prepared as described in the Mainframe Installation Guide and that they
are running.
Additionally, if you are running the server adapter in prepare mode by using
the batch prepare JOB, ensure that the initial_references:IT_cicsraw:
plugin configuration item is set to cics_exci. This avoids non-zero return
codes being issued by the prepare JOB.

Running the CICS server adapter Run the server adapter in prepare mode. This generates IORs and writes
in prepare mode them to a file, which you can then include in your configuration file. A job to
run the CICS server adapter in prepare mode is provided in
orbixhlq.JCLLIB(PREPCICA).

263
CHAPTER 19 | Using the CICS Server Adapter

Sample JCL to run the CICS server This JCL contains the default high-level qualifier, so change it to reflect the
adapter in prepare mode proper value for your installation:

//PREPCICA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
// SET CICSHLQ=CICSTS13
//*
//* Prepare the Orbix CICS Adapter
//*
//* Make the following changes before running this JCL:
//*
//* 1. If you ran DEPLOY1 (or DEPLOYT) to configure in a domain
//* other than the default, please ensure that dataset
//* &ORBIXCFG(ORBARGS) has the domain name used by DEPLOY1
//* (or DEPLOYT).
//*
//PREPARE EXEC PROC=ORXG,
// PROGRAM=ORXCICSA,
// LOADLIB=&CICSHLQ..SDFHEXCI,
// PPARM='prepare -publish_to_file=DD:ITCONFIG(IORCICSA)'
//TYPEINFO DD DUMMY
//MFAMAPS DD DUMMY
//ORBARGS DD DSN=&ORBIXCFG(ORBARGS),DISP=SHR
//*
//* Update configuration domain with CICS Adapter’s IOR
//*
//ITCFG1 EXEC ORXADMIN
//SYSIN DD *
variable modify \
-type string \
-value --from_file:3 //DD:ITCONFIG(IORCICSA) \
LOCAL_MFA_CICS_REFERENCE
/*
//ORBARGS DD DSN=&ORBIXCFG(ORBARGS),DISP=SHR
//*
//* Update configuration domain with CICSRAW IOR
//*

264
 Preparing the Server Adapter

//ITCFG2 EXEC ORXADMIN

//SYSIN DD *
variable modify \
-type string \
-value --from_file:6 //DD:ITCONFIG(IORCICSA) \
initial_references:IT_MFA_CICSRAW:reference
/*
//ORBARGS DD DSN=&ORBIXCFG(ORBARGS),DISP=SHR

Location of CICS server adapter When complete, the IORs for the server adapter should be in
IORs orbixhlq.CONFIG(IORCICSA). The file contains two IORs.

The IT_MFA IOR One IOR is for IT_MFA. This is the IOR for the server adapter
MappingGateway interface. The orbixhlq.JCLLIB(PREPCICA) JCL copies this
IOR into the LOCAL_MFA_CICS_REFERENCE configuration item, which is found
in the orbixhlq.CONFIG PDS, in the member that corresponds to your
configuration domain name. (The default configuration domain name is
DEFAULT@.) This IOR is used by itadmin to contact the correct server
adapter. Refer to “Using the MappingGateway Interface” on page 272 for
more details.

The IT_MFA_CICSRAW IOR The other IOR is for IT_MFA_CICSRAW. This IOR is only produced if the EXCI
plug-in is used. It is not produced if the APPC plug-in is used. This is the
IOR for the CICS server adapter cicsraw interface. This IOR should be made
available to client programs of the server adapter that want to use the
cicsraw interface. Refer to the “The CICS Server Adapter cicsraw Interface”
on page 44 for more details.

Sample configuration file The following is an extract from a working configuration file for you to
compare your file with.

Note: The position of the first quote is moved to the next line, directly
preceding the start of the IOR. (Ellipses denote text omitted for the sake of
brevity.)

265
CHAPTER 19 | Using the CICS Server Adapter

…
LOCAL_MFA_CICS_REFERENCE =
"IOR:000000000000002549444c3a696f6e612e636f6d2f49545f/
4c6f636174696f6e2f4c6f6361746f723a312e300000000000000001000000/
0000007e00010200000000056a756e6f00003a99000000253a3e0233311752/
5706c69636174656453696e676c65746f6e504f410007d3968381a39699000/
0000000003000000010000001c000000001002041700000001000100010001/
10000000001000101090000001a00000004010000000000000600000006000/
0000001c";
…

Running the CICS server adapter You can also run the CICS server adapter in prepare mode from the UNIX
on z/OS UNIX System Services System Services prompt. The command is as follows:

$ itcicsa -ORBname iona_services.cicsa prepare

The two IORs for IT_MFA and IT_MFA_CICSRAW are then displayed on the
console. You can copy them to the appropriate places as described above.
However, in general, it might be easier to obtain the IT_MFA IOR, using the
orbixhlq.JCLLIB(PREPCICA) JCL. This is because it automatically copies
the IOR into the PDS-based configuration file.

266
 Starting the Server Adapter

Starting the Server Adapter

Overview This section describes how to start the CICS server adapter. It discusses the
following topics:
• Starting the server adapter on native z/OS
• Starting the server adapter on z/OS UNIX System Services
• Adapter logging information

Starting the server adapter on In a native z/OS environment, you can start the CICS server adapter in any of
native z/OS the following ways:
• As a batch job.
• Using a TSO command.
• As a started task (by converting the batch job into a started task).
The default CICS server adapter is the server adapter whose configuration is
defined directly in the iona_services.cicsa scope, and not in some
sub-scope of this. The following is sample JCL to run the default CICS server
adapter:

//CICSA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
// SET CICSHLQ=CICSTS13
//*
//* Run the Orbix CICS Adapter
//*
//* Make the following changes before running this JCL:
//*

267
CHAPTER 19 | Using the CICS Server Adapter

//* 1. Change 'SET DOMAIN='DEFAULT@' to your configuration

//* domain name.
//*
// SET DOMAIN='DEFAULT@'
//*
//GO EXEC PROC=ORXG,
// PROGRAM=ORXCICSA,
// LOADLIB=&CICSHLQ..SDFHEXCI,
// PPARM='run'
//MFAMAPS DD DUMMY
//TYPEINFO DD DUMMY
//ITDOMAIN DD DSN=&ORBIXCFG(&DOMAIN),DISP=SHR

Starting the server adapter on On z/OS UNIX System Services, you can start the CICS server adapter from
z/OS UNIX System Services the shell. The command to run the default CICS server adapter is similar to
the following if you have an initial_references:IT_MFA:reference entry
in the root scope (that is, not inside any {} brackets) of your configuration
file:

$ itcicsa

The command to run extra server adapters is similar to the following:

$ itcicsa -ORBname iona_services.cicsa.gateway2

Refer to “Running Multiple Server Adapters Simultaneously” on page 270

for more details on running multiple server adapters.

Adapter logging information When the adapter is started, if a sufficient logging level is enabled, some
basic information is displayed on how the particular adapter is configured,
including which region it is going to connect with. If client principal support
is not enabled, the logged information includes the user ID under which the
server adapter is running. This is normally the TSO/E user ID running the
adapter. However, if a USERIDALLIASTABLE is in use in z/OS UNIX System
Services, the user ID that is displayed instead is the alias associated with
the user ID. Regardless of which user ID (that is, TSO/E or alias) is
displayed, for z/OS it is the same user ID, so it does not affect the
functionality of the server adapter.

268
 Stopping the CICS Server Adapter

Stopping the CICS Server Adapter

Overview This section describes how to stop the CICS server adapter. It discusses the
following topics:
• Stopping the adapter via the admin interface
• Stopping the adapter on native z/OS
• Stopping the adapter on z/OS UNIX System Services

Stopping the adapter via the The Orbix administrative interface is used to configure and manage Orbix
admin interface installations. This interface can be invoked via the ORXADMIN JCL on z/OS or
the itadmin shell command on z/OS UNIX System Services. As with the
other Orbix services, you can stop the CICS server adapter by issuing an
admin stop command that uses the appropriate admin plug-in (in this case,
the mfa plug-in). For example, the format of the command is as follows on
z/OS UNIX System Services:

% itadmin mfa stop

This instructs the adapter to shut down.

Stopping the adapter on native To stop a CICS server adapter job on native z/OS, issue the STOP (P)
z/OS operator command from the console.

Stopping the adapter on z/OS To stop a CICS server adapter process on z/OS UNIX System Services, use
UNIX System Services the kill command or, if the adapter is running in an active rlogin shell,
press Ctrl-C.

269
CHAPTER 19 | Using the CICS Server Adapter

Running Multiple Server Adapters

Simultaneously
Overview This section describes how to run multiple server adapters simultaneously.
It discusses the following topics:
• Running multiple server adapters simultaneously
• Using itadmin on z/OS UNIX System Services

Running multiple server adapters To run multiple CICS server adapters perform the following steps:
simultaneously

Step Action

1 Set up a configuration scope for each server adapter (for

example, the gateway2 scope) in the partial configuration file.
(Refer to the example in “A CICS Server Adapter Sample
Configuration” on page 60.)

2 Set up a corresponding configuration scope for usage with the

admin utility. For example, add a gateway2 sub-scope to the
iona_utilities.cicsa scope in the configuration file, and add
the following configuration setting under it:
initial_references:IT_MFA:reference=%{LOCAL_MFA_CICS_
REFERENCE2}

3 Specify a unique cicsa:poa_prefix variable for each server

adapter if you are using the locator (indirect persistent).
This is a good idea anyway, even for direct persistent server
adapters, because the IORs are easier to distinguish when
examined with the iordump utility.

4 Set the unique port number.

270
 Running Multiple Server Adapters Simultaneously

Step Action

5 Get the initial reference for each adapter.

On native z/OS, change the CICS server adapter prepare JCL to
use the new ORBname, and replace the LOCAL variable with the
new LOCAL_MFA_CICS_REFERENCE2 variable.
On z/OS UNIX System Services, enter the following command
to obtain the IOR:
$ itcicsa -ORBname iona_services.cicsa.gateway2 prepare
Enter the following command on z/OS UNIX System Services,
to add the new reference to the configuration file:
$ itadmin variable create -value IOR:00000…0
LOCAL_MFA_CICS_REFERENCE2

6 Ensure that each server adapter has:

• A unique mapping file.
• A unique IFR signature cache file, if one is being used.
• A unique type_info store, if one is being used.
• A unique pipe member name, if EXCI is being used.
• A unique resource manager name, if RRS is being used.

Using itadmin on z/OS UNIX It might be useful to run in shell mode, so that you do not have to type the
System Services long ORBname in the JCL’s itadmin parameter. To run itadmin on z/OS UNIX
System Services:

$ itadmin -ORBname iona_utilities.cicsa.gateway2

% mfa list
% mfa resolve .....

Note: When using JCL to issue itadmin commands on native z/OS,

include the full ORBname in the JCL’s itadmin parameter.

271
CHAPTER 19 | Using the CICS Server Adapter

Using the MappingGateway Interface

Overview The MappingGateway interface is used to control a running CICS server
adapter. It discusses the following topics:
• Uses of the MappingGateway interface
• Access to the MappingGateway interface
• Selecting a specific server adapter

Uses of the MappingGateway You can use the MappingGateway interface to list the transaction mappings
interface that the server supports, to add or delete individual interfaces and
operations, or to alter the transaction to which an operation is mapped. You
can use it to read a new mapping file, or write existing mappings to a new
file.
Additionally, the MappingGateway interface provides the means by which
IIOP clients can invoke on the exported interfaces. Using the resolve
operation, an IOR can be retrieved for any exported interface. This IOR can
then be used directly by IIOP clients, or registered with an OrbixNames
server as a way of publishing the availability of the interface.

Access to the MappingGateway The MappingGateway interface is provided both via the itadmin interface and
interface as an IDL interface. The IDL for the MappingGateway interface is provided
with the other IDL in the installation and can be used by client applications
to invoke operations on the MappingGateway interface.
Access to the MappingGateway interface, using itadmin, is provided as a
plug-in. This plug-in is selected with the mfa keyword. This itadmin mfa
plug-in is an IONA-supplied client of the MappingGateway interface and is
provided to make it easier to access the MappingGateway interface. For
example, to obtain a list of all the operations provided by the itadmin mfa
plug-in, issue the following command (from the UNIX System Services shell
or via JCL on native z/OS):

$ itadmin mfa –help

272
 Using the MappingGateway Interface

The output looks as follows:

mfa list
add -interface <name> -operation <name> <mapped value>
change -interface <name> -operation <name> <mapped value>
delete -interface <name> -operation <name>
resolve <interface name>
refresh [-operation <name>] <interface name>
reload
save [<mapping_file name>]
switch <mapping_file name>
stats
resetcon
stop

Items shown in angle brackets (<…>) must be supplied and items shown in
square brackets ([…]) are optional. Module names form part of the interface
name and are separated from the interface name with a / character.
The parameter after mfa specifies the operation to be invoked. The options
are:
list This prints a list of the (interface, operation, and name)
mappings that the CICS server adapter currently
supports.
add This allows you to add a new mapping.
change This allows you to change the transaction to which an
existing operation is mapped.
delete This allows you to get the CICS server adapter to stop
exporting a particular operation.
resolve This prints a stringified IOR for the object in the server
adapter that supports the specified interface. This IOR
string can then be given to clients of that interface, or
stored in an OrbixNames server. The IOR produced
contains the TCP/IP port number for the locator if the
CICS server adapter is running with direct persistence set
to no; otherwise, it contains the CICS server adapter’s
port number.
refresh This causes the CICS server adapter to obtain up-to-date
type information for the specified operation. If you omit
the operation argument, all operations being mapped in
the specified interface are refreshed.

273
CHAPTER 19 | Using the CICS Server Adapter

reload This causes the CICS server adapter to reload the list of
mappings from its mapping file.
save This causes the CICS server adapter to save its current
mappings to either its current mapping file or to a
filename you provide.
switch This causes the CICS server adapter to switch over to a
new mapping file, and to export only the mappings
contained within it.
stats Displays some statistical information on the running
server adapter. Information includes the current time
according to the server adapter, the pending request
queue length, the total number of worker threads, worker
threads currently active, total number of requests
processed by the server adapter since start-up, and the
server adapter start-up time.
resetcon This command has no effect for the CICS server adapter.
stop Instructs the CICS server adapter to shut down.

Note: The add, change, and delete operations only update the CICS
server adapter internal information, unless a save operation is issued, in
which case the new details are written to the server adapter mapping file.

Selecting a specific server adapter To select a specific server adapter, provide the ORBname for the server
adapter on a request. For example, to obtain the IOR for the SimpleObject
interface, use the following command:

itadmin -ORBname iona_utilities.cicsa mfa resolve

Simple/SimpleObject

274
 Locating CICS Server Adapter Objects Using itmfaloc

Locating CICS Server Adapter Objects Using

itmfaloc
Overview The CICS server adapter maintains object references that identify CORBA
server programs running in CICS. A client must obtain an appropriate object
reference to access the target server. The itmfaloc URL resolver plug-in
supplied with your Orbix Mainframe installation facilitates and simplifies
this task.1
This section discusses the following topics:
• Locating CICS servers using IORs
• Locating objects using itmfaloc
• Format of an itmfaloc URL
• What happens when itmfaloc is used
• Example of using itmfaloc

Locating CICS servers using IORs One way of obtaining an object reference for a target server, managed by the
CICS server adapter, is to retrieve the IOR via the itadmin utility. This calls
the resolve() method on the server adapter's MappingGateway interface and
returns a stringified IOR. For example, to retrieve an IOR for the
SimpleObject IDL interface, issue the following command:

itadmin mfa resolve Simple/SimpleObject

After it has been retrieved, the IOR can be distributed to the client and used
to invoke on the target server running inside CICS.

Locating objects using itmfaloc In some cases, the use of itadmin and the need to persist stringified IORs is
not very manageable, and thus a more dynamic approach is desirable. The
itmfaloc resolver is designed to provide an alternative approach. It follows
a similar scheme to that of the corbaloc URL technique. (Refer to the
CORBA Programmer’s Guide, C++ for more information.)

1. This plug-in is not yet available on other Orbix platforms.

275
CHAPTER 19 | Using the CICS Server Adapter

In this way, the Orbix CORBA client can specify a very simple URL format
which identifies the target service required. This text string can therefore be
used programmatically in place of the rather cumbersome stringified IOR
representation.

Format of an itmfaloc URL An itmfaloc URL is a string of the format:

itmfaloc:<InterfaceName>

In the preceding example, <InterfaceName> represents the fully scoped

name of the IDL interface implemented by the target CICS server, as
specified in the server adapter mapping file.

What happens when itmfaloc is When an itmfaloc URL is used in place of an IOR, the Orbix client
used application contacts the server adapter to obtain an object reference for the
desired CICS server. The itmfaloc URL string only encodes the interface
name, not the server adapter’s location. To establish the initial connection
to the server adapter, the IT_MFA:initial_references configuration item is
used.
If multiple server adapters are deployed, it is imperative that the client
application specifies the correct IT_MFA:initial_references setting, to talk
to the correct CICS server adapter. This can be achieved by specifying the
appropriate ORBname which represents the particular configuration scope;
for example, -ORBname iona_utilities.cicsa.
If the client application successfully connects to the server adapter, it then
calls the resolve() operation on the MappingGateway object reference, thus
retrieving an object reference for the target server managed by the CICS
server adapter.

276
 Locating CICS Server Adapter Objects Using itmfaloc

Example of using itmfaloc The simple demonstration client code that is shipped with Orbix uses a
file-based mechanism to access the target server's stringified IOR. If the
target server resides in CICS, an alternative approach is to specify an
itmfaloc URL string in the string-to-object call:

itmfaloc:Simple/SimpleObject

The relevant Orbix APIs are:

• str2obj (PL/I)
• STRTOOBJ (COBOL)
• string_to_object() (C++)

277
CHAPTER 19 | Using the CICS Server Adapter

Adding a Portable Interceptor to the CICS

Server Adapter
Overview This section describes how to add a portable interceptor (or multiple
interceptors) to the server adapter. This can be used to perform the usual
functions available in portable interceptors. Refer to the CORBA
Programmer’s Reference, C++ and CORBA Programmer’s Guide, C++ for
more details on portable interceptors. Additionally, a portable interceptor
can be used to manipulate the client principal that the CICS server adapter
receives from the client. It can also be used to inspect the operation
arguments sent in the request.

In this section This section discusses the following topics:

Developing the Portable Interceptor page 279

Compiling the Portable Interceptor page 284

Loading the Portable Interceptor into the CICS Server Adapter page 286

278
 Adding a Portable Interceptor to the CICS Server Adapter

Developing the Portable Interceptor

Overview A portable interceptor should be developed as described in the CORBA
Programmer’s Guide, C++. For the server adapter, only server-side
interceptors are of interest, because the CICS server adapter is a CORBA
server.
This subsection discusses the following topics:
• Server adapter portable interceptor sample locations
• Contents of the ORB plug-in implementation
• Contents of the ORB initializer implementation
• Contents of the server interceptor implementation
• Server interceptor sample code
• Server interceptor sample code explanation

Server adapter portable An example of a portable interceptor framework for use in the server adapter
interceptor sample locations is provided in orbixhlq.DEMO.CPP.SRC and orbixhlq.DEMO.CPP.H. The
header file members are ORBINITI and SRVINTRC. The source file members
are PLUGIN, ORBINITI, and SRVINTRC.
For a z/OS UNIX System Services installation, the demonstration is located
in $IT_PRODUCT_DIR/asp/Version/demos/corba/pdk/security_pi. The
header files are located in orb_initializer_impl.h and
server_interceptor_impl.h. The implementation files are located in
plugin.cxx, orb_initializer_impl.cxx and
server_interceptor_impl.cxx.
The portable interceptor is packaged as a standard ORB plug-in, to enable it
to be loaded by an existing Orbix server (in this case, the CICS server
adapter).

Contents of the ORB plug-in The ORB plug-in implementation contains code to register this DLL as an
implementation ORB plug-in. The ORB plug-in implementation also contains code in its
ORB_init() method to register the portable interceptor’s ORB initializer
object with the ORB. The ORB plug-in mechanism is used here to enable
the server adapter to load this DLL when the adapter is started. (See

279
CHAPTER 19 | Using the CICS Server Adapter

“Loading the Portable Interceptor into the CICS Server Adapter” on

page 286.) Sample source is provided in the PLUGIN member on z/OS and in
the plugin.cxx file on z/OS UNIX System Services.

Contents of the ORB initializer The ORB initializer implementation contains code to register the server
implementation request interceptor with the ORB. Refer to the CORBA Programmer’s Guide,
C++ for details on how to implement an ORB initializer. The initializer is
registered in the IT_Security_PlugIn class (that is, the ORB plug-in
implementation). Sample source is provided in the ORBINITI members on
z/OS, and in the orb_initializer.h and orb_initializer.cxx files on
z/OS UNIX System Services.

Contents of the server interceptor The server request interceptor implementation illustrates how you can
implementation intercept the incoming CORBA request and check the following:
• Principal—You can inspect the GIOP principal value, and potentially
modify this principal value before it is subsequently used by the server
adapter. (See “Activating Client Principal Support” on page 125 for
more details.) This is done by invoking on the GIOP Current API.
• Arguments—You can inspect the operation arguments that have been
sent in the request. This is done by invoking on the server adapter’s
IT_MFA Current API.

To achieve this functionality, the interceptor only implements the

receive_request() interception point. This is the point at which both the
principal and operation arguments has been read in from the GIOP request
message. Sample source is available in the SRVINTRC dataset members on
z/OS, and in the server_interceptor_impl.h and
server_interceptor_impl.cxx files on z/OS UNIX System Services.

280
 Adding a Portable Interceptor to the CICS Server Adapter

The IT_MFA Current API The Current API is specific to the server adapter and enables PDK
application-level code to access the operation arguments in the form of a
sequence of octets. The IDL is located in your Orbix Mainframe installation
at [email protected](MFA@CUR) on z/OS or at
install-dir/asp/6.x/idl/orbix_pdk/mfa_current.idl on z/OS UNIX
System Services.
The Current API can only be used to inspect arguments for a mapped
operation. This means that requests targeting the cicsraw interface or the
MappingGateway interface cause a CORBA::BAD_INV_ORDER system exception
to be thrown. A CORBA::BAD_INV_ORDER exception is also thrown if the
Current API is invoked from within an unsuitable interception point. The
request_message_body() operation must be called in the
receive_request() interception point. The reply_body_length()
operation, which returns the length of the reply returned from CICS, must be
called from the send_reply() interception point.

Server interceptor sample code The receive_request() method makes calls to inspect the GIOP principal
and the operation arguments (if appropriate). The following code example
focuses on the GIOP principal checking:

Example 11: Sample Server Interceptor code (Sheet 1 of 2)

void
Demo_ServerInterceptorImpl::inspect_giop_principal(
PortableInterceptor::ServerRequestInfo_ptr ri
) IT_THROW_DECL((
CORBA::SystemException,
PortableInterceptor::ForwardRequest
))
{
1 CORBA::OctetSeq_var received_val_binary =
m_current->received_principal();
2 if (received_val_binary->length() != 0)
{

281
CHAPTER 19 | Using the CICS Server Adapter

Example 11: Sample Server Interceptor code (Sheet 2 of 2)

3 if (received_val_binary[received_val_binary->length()-1]
== '\0')
{
cout << "Received a string principal in PI" << endl;
}
else
{
cout << "Received a binary principal in PI" << endl;
return;
}
}
else
{
cout << "Did not received any principal!" << endl;
return;
}
4 // Show the principal value
CORBA::String_var received_val =
m_current->received_principal_as_string();

if (strlen(received_val.in()) != 0)
{
cout << "Received principal string in PI "
<< received_val.in() << endl;
5 // This is very contrived, but shows how to change a principal
cout << "If principal is JOHN, change to PETER" << endl;
if (strcmp(received_val.in(),"JOHN") == 0)
{
char* new_user = "PETER";
6 m_current->change_received_principal_as_string(new_user);
}
}
else
{
cout << "Did not received any principal!" << endl;
}
}

282
 Adding a Portable Interceptor to the CICS Server Adapter

Server interceptor sample code The sample server interceptor code can be explained as follows:
explanation 1. Obtain the principal in binary format. In binary format, the principal
value does not undergo ASCII-to-EBCDIC conversion.
2. Check if a principal has been received.
3. Check if the principal value ends in a null terminator, which indicates
that it is probably a string. (This depends on the conventions agreed
with the client application.)
4. Because the interceptor returns if the principal value is not a string, it
now re-obtains the principal value as a string with ASCII-to-EBCDIC
conversion taking place.
5. In this example, it checks if the principal is JOHN. If the principal is
JOHN, it is changed to PETER. This is just an example to show how to
change a principal. Production applications probably have more
complex rules for modifying principals.
6. Other interceptor points can also be implemented. For example, the
send_exception() interceptor point can be implemented if tracking or
logging of exceptions is desired. The
receive_request_service_contexts() interceptor can be
implemented if access to additional service contexts is required.
Additionally, send_reply() can be used to check the length of the
reply message, using the reply_body_length() method from the
IT_MFA Current API.

283
CHAPTER 19 | Using the CICS Server Adapter

Compiling the Portable Interceptor

Overview This subsection outlines the build information used to compile the portable
interceptor demonstration. It also provides information about the naming of
the compiled DLL, and the location of the readme files that provide
additional information about compiling the portable interceptor.
This section discusses the following topics:
• Compiling on native z/OS
• Compiling on z/OS UNIX System Services
• Specifying the correct DLL name when loading the portable interceptor
• Location of additional information for compiling the portable
interceptor

Compiling on native z/OS Sample JCL to compile the portable interceptor can be found in
orbixhlq.DEMO.CPP.BLD.JCLLIB(ADTPICL). This compiles the two sample
source files and links them into a DLL called SECPI1.

Compiling on z/OS UNIX System The $IT_PRODUCT_DIR/asp/Version/demos/corba/pdk/security_pi

Services directory contains a makefile that is used to build the SECPI1 DLL on z/OS
UNIX System Services.

Specifying the correct DLL name The DLL name, SECPI1, has been chosen for this example, because it is a
when loading the portable valid name in both a native z/OS and z/OS UNIX System Services
interceptor environment. Any valid DLL name can be used for your target deployment
environment. The correct DLL name must then be specified when selecting
the portable interceptor that is to be loaded into the server adapter. Refer to
“Loading the Portable Interceptor into the CICS Server Adapter” on
page 286 for more details.

284
 Adding a Portable Interceptor to the CICS Server Adapter

Location of additional information On native z/OS, the ADTPI member in orbixhlq.DEMO.CPP.README also
for compiling the portable provides a description of how to compile the portable interceptor. You can
interceptor refer to this for additional information.
On z/OS UNIX System Services, similar information tailored to compiling the
portable interceptor is provided in $IT_PRODUCT_DIR/asp/Version/demos/
corba/pdk/security_pi/README_CXX.txt.

285
CHAPTER 19 | Using the CICS Server Adapter

Loading the Portable Interceptor into the CICS Server Adapter

Overview This subsection describes how the portable interceptor is loaded into the
CICS server adapter. It discusses the following topics:
• Loading the portable interceptor on native z/OS
• Loading the portable interceptor on z/OS UNIX System Services
• Setting related configuration items
• Sample CICS server adapter configuration scope

Loading the portable interceptor Add the PDS containing the portable interceptor DLL to the STEPLIB for the
on native z/OS CICS server adapter. On native z/OS, this can be done by updating the JCL
used to run the server adapter. For example, add a LOADLIB value as
follows:

//GO EXEC PROC=ORXG,

// PROGRAM=ORXCICSA,
// LOADLIB=&ORBIX..DEMO.CPP.LOADLIB,
// PPARM='run'

Note: If the LOADLIB symbolic is already in use, you might wish to update
the ORXG procedure and add the PDS that contains the portable interceptor
into the STEPLIB concatenation.

Loading the portable interceptor If the server adapter is run from z/OS UNIX System Services, and the
on z/OS UNIX System Services portable interceptor was built using JCL on native z/OS (that is, the SECPI1
DLL resides in a PDS), add the PDS to the STEPLIB environment variable.
The following is an example of how to do this, where IT_PRODUCT_HLQ is set
to the relevant Orbix HLQ install area:

export STEPLIB=$IT_PRODUCT_HLQ.DEMO.CPP.LOADLIB:$STEPLIB

286
 Adding a Portable Interceptor to the CICS Server Adapter

If the server adapter is run from z/OS UNIX System Services, and the
portable interceptor was built using a makefile on z/OS UNIX System
Services, so the SECPI1 DLL resides in a UNIX System Services directory,
add the directory that contains the SECPI1 DLL to the LIBPATH environment
variable. The following is an example of how to do this, where
IT_PRODUCT_DIR is set to the relevant Orbix install area for z/OS UNIX
System Services:

export LIBPATH=$IT_PRODUCT_DIR/asp/Version/demos/corba/pdk/
security_pi:$LIBPATH

Setting related configuration The following configuration items must be set to load the plug-in:
items
orb_plugins The list must include the demo_sec ORB
plug-in, which is the name that was
used in the ORB plug-in demonstration
code. This plug-in must appear before
the portable_interceptor plug-in in the
orb_plugins list.
The list must also include the
portable_interceptor plug-in, to allow
for portable interceptor support to be
activated.
binding:server_binding_list The name of the server request
interceptor must be added to this list, to
allow it to gain control when a server
request is being processed. For the
purposes of this example, add the
DemoPI interceptor.
plugins:demo_sec:shlib_name Specifies the name of the ORB plug-in
library, without the version suffix.

287
CHAPTER 19 | Using the CICS Server Adapter

plugins:demo_sec:shlib_version Specifies the version number of the ORB

plug-in library.
Note: On z/OS, unlike on other
platforms, a particular ORB plug-in DLL
name is resolved from the Orbix
configuration simply by appending the
shlib_version to the shlib_name.

Sample CICS server adapter For example, the following can be added to the CICS server adapter’s
configuration scope configuration scope:

orb_plugins = ["iiop_profile", "giop", "iiop",

"local_log_stream", "ots", "demo_sec",
"portable_interceptor"];
binding:server_binding_list = ["DemoPI"];
plugins:demo_sec:shlib_name = "SECPI";
plugins:demo_sec:shlib_version = "1";

When the CICS server adapter is then started, the portable interceptor
should be loaded and included in the server-side communication bindings.

288
 Enabling the GIOP Request Logger Interceptor

Enabling the GIOP Request Logger Interceptor

Overview The request logger plug-in uses the interceptor approach to log accounting
information for each request and reply message. The request logger uses the
ORB's event log to perform the logging.

Format of log messages The log messages take the following format:

Request message: [REQUEST], peer IP address, peer port number,

principal, operation, program name
Reply message: [REPLY], peer IP address, peer port number,
principal, operation, program name, reply status

The components of the preceding log messages can be explained as follows:

principal This is the user ID as specified in the incoming GIOP
request. NO_PRINCIPAL is displayed if the principal was
not sent by the client.
program name This field is specific to the cicsraw interface that is
exposed by the server adapter (see “The CICS Server
Adapter cicsraw Interface” on page 44). It refers to the
program name as passed in the first argument of the
run_program operations. For all other
interfaces/operations, this field does not appear.
reply status This indicates the success status of the invocation.
Values can be:
• NO_EXCEPTION—success: reply data is being sent
back to the client.
• SYSTEM_EXCEPTION—failure: a CORBA system
exception is being thrown.
• USER_EXCEPTION—failure: a CORBA user exception
is being thrown.

289
CHAPTER 19 | Using the CICS Server Adapter

Sample log output The following is an example of some log output:

Mon, 01 May 2006 14:38:52.0000000 [thehost:CICSA,A=0040]

(IT_REQUEST_LOGGER:202) I - [REQUEST] 10.2.100.8, 1408,
johndoe, run_transaction(), PART
Mon, 01 May 2006 14:38:53.0000000 [thehost:CICSA,A=0040]
(IT_REQUEST_LOGGER:202) I - [REPLY] 10.2.100.8, 1408,
johndoe, run_transaction(), PART, NO_EXCEPTION

Configuration To enable the request logger, the following configuration items must be
modified:
orb_plugins The request_logger plug-in must be added to the
orb_plugins list. Also, ensure that this list includes a
log stream plug-in (for example, the local_log_stream).
binding:server_ The name of the server request interceptor must appear
binding_list in the list of allowable server bindings. The interceptor is
also called request_logger.
event_log:filters The request logger event subsystem can be enabled by
adding IT_REQUEST_LOGGER=* to the list of filters. This
indicates that all event log messages from this plug-in
are to be enabled.

Sample configuration scope For example, the following can be added to the CICS server adapter's
configuration scope:

orb_plugins = ["local_log_stream", "iiop_profile",

"giop", "iiop", "request_logger"];
binding:server_binding_list = ["request_logger"];
event_log:filters = ["IT_REQUEST_LOGGER=*",
"IT_MFA=INFO_HI+WARN+ERROR+FATAL"];

Also ensure that the following global variables are specified in the ORXINTRL
configuration file:
• plugins:request_logger:shlib_name = "ORXRLOG";
• plugins:request_logger:shlib_version = "5";

290
 Gathering Accounting Information in the Server Adapter

Gathering Accounting Information in the

Server Adapter
Overview This section describes how to activate a DLL in the CICS server adapter that
can gather and log accounting type information. A sample accounting DLL is
provided in your Orbix installation in the orbixhlq.LOADLIB load library. You
can customize the behavior of this DLL to suit your needs.

In this section This section discusses the following topics:

Customizing the Accounting DLL page 292

Compiling the Customized Accounting DLL page 296

Activating the Accounting DLL in the Server Adapter page 297

Note: For testing purposes, you can choose to use the sample DLL
directly as shipped. In this case, there is no need to perform any of the
DLL customization tasks as outlined in this section.

291
CHAPTER 19 | Using the CICS Server Adapter

Customizing the Accounting DLL

Overview The accounting DLL consists of a call to the function
IT_MFA_display_account_information() for mapped requests, and a call
to the function IT_MFA_display_raw_interface_account_information()
for cicsraw requests, after each CICS server adapter request has been
completed. You can implement your own version of these functions and
replace the DLL called ORXACCT2, to gather the customized accounting
information.
This section discusses the following topics:
• IT_MFA_display_account_ information() parameters
• Sample use of IT_MFA_display_account_information()
• Location of sample source code

IT_MFA_display_account_ The parameters for the function contain the following information:
information() parameters

Parameter Description
interface This is the interface name of the request.
operation This is the operation name of the request.
mapped_name This is the transaction or program name that is invoked in
CICS.
request_length This is the total length of inbound data received from
TCP/IP, excluding the 12-byte fixed GIOP header.
reply_length This is the total length of outbound data sent back via
TCP/IP, excluding the 12-byte fixed GIOP header.
principal The Client principal, if available; otherwise, an empty
string.
local_arglist This is an NVList of all the arguments for the request. This
NVList is in the state after the reply has been transmitted
back to the client application, so only limited data is
available in it.

292
 Gathering Accounting Information in the Server Adapter

Parameter Description
dynany_set Indicates if the first argument has been saved in a dynamic
any when the request was received from the client. This
dynamic any is the next parameter. Saving the argument
has to be activated via configuration.
da First argument, if saved. Refer to the chapter on Any’s and
Dynamic Any’s in the CORBA Programmer’s Guide, C++
for details on how to access the data contained in this
parameter.
orb Pointer to the CICS server adapter ORB, if needed, for
example, to call resolve_initial_references() to obtain
a current object.

293
CHAPTER 19 | Using the CICS Server Adapter

Sample use of Here is an example of what can be done in the function.

IT_MFA_display_account_inform
ation()

Example 12: Sample use of IT_MFA_display_account_information() (Sheet

1 of 2)

#include <it_cal/iostream.h>
#include <it_cal/fstream.h>
#include <string.h>
#include <it_mfa/account.h>

IT_USING_NAMESPACE_STD
void
IT_MFA_display_account_information(
const char* interface,
const char* operation,
const char* mapped_name,
CORBA::Long request_length,
CORBA::Long reply_length,
const char* principal,
CORBA::NVList_ptr local_arglist,
CORBA::Boolean dynany_set,
DynamicAny::DynAny_ptr da,
CORBA::ORB_ptr orb
)
{
cout << "Accounting information: " << endl;
cout << " Interface: " << interface << endl;
cout << " Operation: " << operation << endl;
cout << " Tran: " << mapped_name << endl;
cout << " Request len: " << request_length << endl;
cout << " Reply len: " << reply_length << endl;
cout << " Principal: " << principal << endl;

294
 Gathering Accounting Information in the Server Adapter

Example 12: Sample use of IT_MFA_display_account_information() (Sheet

2 of 2)

// Gather type information from the NVList

cout << " Number of Arguments: " << local_arglist->count() <<
endl;

// Display information from the first parameter

if (dynany_set == IT_TRUE)
{
CORBA::TypeCode_ptr type = da->type();

cout << " Kind: " << type->kind() << endl;

cout << " Id: " << type->id() << endl;
if ((type->kind() == CORBA::tk_struct))
{
cout << " Member count: " << type->member_count() <<
endl;
for (int ii=0; ii < type->member_count(); ii++)
{
CORBA::TypeCode_ptr type1 = type->member_type(ii);
cout << " Kind of member: " << type1->kind() <<
endl;
}
}
}
cout << endl;
}

Location of sample source code The source code for this sample function is contained in
orbixhlq.DEMO.CPP.SRC(ACCOUNT). This example can be used as a basis for
a function which logs the request accounting information in the desired
format.

295
CHAPTER 19 | Using the CICS Server Adapter

Compiling the Customized Accounting DLL

Overview The IT_MFA_display_account_information() and
IT_MFA_display_raw_interface_account_information() functions must
be compiled into a C++ DLL, called ORXACCT2. This is the name of the
library that the CICS server adapter uses when it is configured to call out to
these functions.
This section discusses the following topics:
• Location of sample JCL to compile IT_MFA_display_account_
information()
• Location of additional information for compiling
IT_MFA_display_account_ information()

Location of sample JCL to compile Sample JCL to compile the DLL can be found in
IT_MFA_display_account_ orbixhlq.DEMO.CPP.BUILD.JCLLIB(ACCTCL). By default, this job generates
information() the customized ORXACCT2 DLL in the orbixhlq.DEMO.CPP.LOADLIB PDS.

Location of additional information The orbixhlq.DEMO.CPP.README(ACCOUNT) file also provides a description of

for compiling how to compile the DLL, which can be referred to for additional information.
IT_MFA_display_account_
information()

296
 Gathering Accounting Information in the Server Adapter

Activating the Accounting DLL in the Server Adapter

Overview This subsection describes how the customized accounting DLL can be
loaded into the server adapter at runtime. It also describes how to activate
this functionality. It discusses the following topics:
• Loading the accounting DLL on native z/OS
• Loading the accounting DLL on z/OS UNIX System Services
• Setting required configuration items

Loading the accounting DLL on To load the customized accounting DLL on native z/OS, add the PDS
native z/OS containing your customized version of the accounting DLL to the STEPLIB
concatenation for the server adapter. This can be done by updating the CICS
server adapter JCL. For example, add a LOADLIB value as follows:

//GO EXEC PROC=ORXG,

// PROGRAM=ORXCICSA,
// LOADLIB=&ORBIX..DEMO.CPP.LOADLIB,
// PPARM='run'

Loading the accounting DLL on To load the customized accounting DLL on z/OS UNIX System Services, add
z/OS UNIX System Services the PDS to the STEPLIB environment variable, for example using:

export STEPLIB=orbixhlq.DEMO.CPP.LOADLIB:$STEPLIB

In the preceding example, orbixhlq represents the relevant high-level

qualifier for the PDS.

Setting required configuration If the plugins:cicsa:call_accounting_dll configuration item is set to yes,

items the server adapter invokes on the appropriate accounting function after it
has processed each request and sent the reply from CICS back to the client.
If the plugins:cicsa:capture_first_argument_in_dynany configuration
item is set to yes, the first argument of the request, if it is an input
argument, is also preserved and passed to the function.

297
CHAPTER 19 | Using the CICS Server Adapter

Exporting Object References at Runtime

Overview When you start the server adapter it can export object references for the
interfaces it supports. These object references relate to the MappingGateway
interface, the cicsraw interface, and (optionally) any other mapped
interfaces that have been defined to the server adapter via its mapping file
at start-up. The server adapter can export these object references to a file, to
the Naming Service, or both.

In this section This section discusses the following topics:

Configuration Items for Exporting Object References page 299

Exporting Object References to a File page 305

Exporting Object References to Naming Service Context page 306

Exporting Object References to Naming Service Object Group page 308

298
 Exporting Object References at Runtime

Configuration Items for Exporting Object References

Overview This subsection describes the configuration items that are used to control
the export of object references from the server adapter.

Configuration items summary The following table summarizes the configuration items that are used to
control the export of object references from the server adapter:

Note: None of these configuration items are included by default in the

adapter configuration file. If you want to configure the server adapter to
export object references, you must add these configuration items, as
appropriate.

plugins:cicsa:object_publishers This specifies where the adapter can

publish its object references. Valid
options are naming_service to publish
object references to the Naming
Service, and filesystem to publish
object references to file. The default
value is "".
plugins:cicsa:write_iors_to_fileThis item has now been deprecated
and is superseded by the
plugins:cicsa:object_publisher:
filesystem:filename configuration
item described next.
plugins:cicsa:object_publisher: This supersedes the plugins:cicsa:
filesystem:filename write_iors_to_file configuration
item. It specifies the file that is to be
used if you want the adapter to export
object references to a file. You can
specify the full path to an HFS
filename, a PDS member name, or a
PDS name as the value for this item. If
this configuration item is not included
in the adapter’s configuration, no
object references are exported to file.
See “Configuration example” on
page 305 for more details.

299
CHAPTER 19 | Using the CICS Server Adapter

plugins:cicsa:write_iors_to_ns This item has now been deprecated

_context and is superseded by the
plugins:cicsa:object_publisher:
naming_service:context configuration
item described next.
plugins:cicsa:object_publisher: This supersedes the plugins:cicsa:
naming_service:context write_iors_to_ns_context
configuration item. It specifies the
Naming Service context that is to be
used if you want the adapter to export
object references to a Naming Service
context. If this configuration item is not
included in the adapter’s configuration,
no object references are exported to a
Naming Service context. If you specify
a value of "", the object references are
written to the root context of the
Naming Service.
plugins:cicsa:object_publisher: This specifies whether the Naming
naming_service:context: Service context specified by
auto_create plugins:cicsa:object_publisher:nam
ing_service:context should be
created if it does not exist. Valid
options are true and false. The
default value is true.
plugins:cicsa:object_publisher: This specifies whether
naming_service:update_mode adapter-deployed objects are to be
published during start-up only or
whether updates are also to be
published. Valid options are startup
and current. The default value is
startup.
plugins:cicsa:place_iors_in_ This item has now been deprecated
nested_ns_scopes and is superseded by the
plugins:cicsa:object_publisher:
naming_service:nested_scopes
configuration item described next.

300
 Exporting Object References at Runtime

plugins:cicsa:write_iors_to_ns This item has now been deprecated

_context and is superseded by the
plugins:cicsa:object_publisher:
naming_service:context configuration
item described next.
plugins:cicsa:object_publisher: This supersedes the plugins:cicsa:
naming_service:context write_iors_to_ns_context
configuration item. It specifies the
Naming Service context that is to be
used if you want the adapter to export
object references to a Naming Service
context. If this configuration item is not
included in the adapter’s configuration,
no object references are exported to a
Naming Service context. If you specify
a value of "", the object references are
written to the root context of the
Naming Service.
plugins:cicsa:object_publisher: This specifies whether the Naming
naming_service:context: Service context specified by
auto_create plugins:cicsa:object_publisher:nam
ing_service:context should be
created if it does not exist. Valid
options are true and false. The
default value is true.
plugins:cicsa:object_publisher: This specifies whether
naming_service:update_mode adapter-deployed objects are to be
published during start-up only or
whether updates are also to be
published. Valid options are startup
and current. The default value is
startup.
plugins:cicsa:place_iors_in_ This item has now been deprecated
nested_ns_scopes and is superseded by the
plugins:cicsa:object_publisher:
naming_service:nested_scopes
configuration item described next.

301
CHAPTER 19 | Using the CICS Server Adapter

plugins:cicsa:object_publisher: This supersedes plugins:cicsa:

naming_service:nested_scopes place_iors_in_nested_ns_scopes. If
this is set to false, the IOR is stored in
the specified scope in the Naming
Service. If this is set to true, the
module name(s) of the interface for the
IOR is used to navigate subscopes from
the configured scope, with the same
names as the module names. The IOR
is then placed in the relevant subscope.
The default is false.
When using Naming Service contexts
and
plugins:cicsa:object_publisher:
naming_service:context:auto_create
is set to true, contexts are created for
IDL module scopes. For example,
Simple/SimpleObject with
plugins:cicsa:object_publisher:
naming_service:context set to base
creates a context tree of /base/Simple
for SimpleObject.
The default for
plugins:cicsa:object_publisher:
naming_service:nested_scopes is
false.
plugins:cicsa:publish_all_iors If this is set to yes, the object
references for the MappingGateway
interface, the cicsraw interface, and all
interfaces specified in the adapter
mapping file are exported. If this is set
to no, only the object references for the
MappingGateway and cicsraw
interfaces are exported. The default is
no.
Note: This configuration item is only
used by the deprecated object
publishing configuration items. When
using the new object publishing
configuration items, all IORs are
published.

302
 Exporting Object References at Runtime

plugins:cicsa:remove_ns_iors If this is set to yes, the server adapter

_on_shutdown attempts to unbind the object
references from the Naming Service
when it shuts down normally (for
example, via an operator stop
command). The default is no.
Note: This configuration item is only
used by the deprecated object
publishing configuration items. When
using the new object publishing
configuration items, the setting of
plugins:cicsa:object_publisher:
naming_service:update_mode
determines if the server adapter
attempts to unbind object references
from the Naming Service when it shuts
down normally. A setting of current
causes the server adapter to attempt to
unbind references at shutdown.
plugins:cicsa:write_iors_to_ns This item has now been deprecated
_group_with_prefix and is superseded by the
plugins:cicsa:object_publisher:
naming_service:group:prefix
configuration item described next.
plugins:cicsa:object_publisher: This supersedes the plugins:cicsa:
naming_service:group:prefix write_iors_to_ns_group_with_
prefix configuration item. It specifies
the prefix that is to be added to each
generated name indicating an interface.
The specified prefix is attached to the
generated name, to specify the object
group that is to be used. If a prefix of “”
is specified, no prefix is added. If this
configuration setting is not present, no
object references are exported to any
object groups.
plugins:cicsa:write_iors_to_ns This item has now been deprecated
_group_member_name and is superseded by the
plugins:cicsa:object_publisher:
naming_service:group:member_name
configuration item described next.

303
CHAPTER 19 | Using the CICS Server Adapter

plugins:cicsa:object_publisher: This supersedes the plugins:cicsa:

naming_service:group: write_iors_to_ns_group_member_
member_name name configuration item. It specifies the
member name that the server adapter
is to use in the object group. A unique
member name must be specified for
each adapter; otherwise, one adapter
might end up replacing the object
group members of another adapter.

304
 Exporting Object References at Runtime

Exporting Object References to a File

Overview When it comes to the server adapter exporting object references, the
simplest option is to have the adapter export them to a file. This subsection
provides an example of the configuration settings that are required to enable
the export of object references to a file, and the subsequent output
produced.

Configuration example The following configuration settings indicate that the server adapter should
export object references for all the interfaces it supports to the home
directory of user1:

plugins:cicsa:object_publishers = ["file_system"];
plugins:cicsa:object_publisher:fileystem:filename = "/home/user1/test.txt";

The following configuration settings indicate that the server adapter should
export object references for all the interfaces it supports to a data set called
MFAIORS:

plugins:cicsa:object_publishers = ["file_system"];
plugins:cicsa:object_publisher:fileystem:filename = "DD:MFAIORS";

Example output The following is an example of the output produced in the file for the first of
the preceding configuration examples, assuming the simple demonstration
has been added to the adapter mapping file:

IT_MFA = IOR:0000000000000027494…
Simple:SimpleObject = IOR:000000000000001c4944…
IT_MFA_CICS:cicsraw = IOR:00000000000000254944…

305
CHAPTER 19 | Using the CICS Server Adapter

Exporting Object References to Naming Service Context

Overview When it comes to exporting object references to the Naming Service, the
server adapter can be configured to export to either a Naming Service
context or a Naming Service object group. This subsection provides details
about exporting to a Naming Service context.

Note: The simultaneous exporting of object references to both a Naming

Service context and a Naming Service object group is not supported.

Prerequisites If the server adapter is configured to export its object references to a Naming
Service context, the following prerequisites apply:
• The Naming Service used must support the
CosNaming::NamingContextExt interface.
• The initial reference for this Naming Service must be supplied to the
adapter either in the adapter’s configuration file or via the command
line at start-up.

Configuration The plugins:cicsa:object_publisher:naming_service:context

configuration item specifies the Naming Service context to which the
adapter should export its object references. If a value of "" (that is, an
empty context) is specified for this item, the object references are written to
the root context. To indicate a nested context, the specified value must take
a format of context/context/context.

Note: The context must exist when the adapter is started. See the Orbix
Administrator’s Guide for details of how to create contexts with itadmin, in
particular how to create and specify nested Naming Service contexts.
However, if
plugins:cicsa:object_publisher:naming_service:context:auto_create
is set to true, the context is created automatically if it does not already
exist.

If plugins:cicsa:object_publisher:naming_service:update_mode is set
to current, the adapter calls unbind() on the object references in the
Naming Service as part of a normal shut-down operation.

306
 Exporting Object References at Runtime

Object ID The ID for the object bound into the Naming Service is derived from the
module and interface name. First, all the module names are used and then
the interface name, each separated by a colon. For example, the ID for the
interface for the simple demonstration is Simple:SimpleObject. The kind
parameter is always left empty. The MappingGateway interface uses IT_MFA
as the ID.

rebind() function The adapter uses rebind() to add the object references to the Naming
Service, so any existing object reference with the same name in the same
context is replaced.

Example The following itadmin command creates a context called test in the
Naming Service:

itadmin ns newnc test

Note: You can also create a context using an equivalent piece of JCL.

Note: If plugins:cicsa:object_publisher:naming_service:context:
auto_create is set to true, the Naming Service context is created
automatically, and the preceding itadmin command is not necessary.

The following configuration settings indicate that when the adapter starts, it
should write all of its object references to the Naming Service context called
test, which will be created if it does not already exist. It should
subsequently remove the object references again on shutting down (during a
normal shut-down):

plugins:cicsa:object_publishers = ["naming_service"];
plugins:cicsa:object_publisher:naming_service:context = "test";
plugins:cicsa:object_publisher:naming_service:context:auto_create = "true";
plugins:cicsa:object_publisher:naming_service:update_mode = "current";
plugins:cicsa:object_publisher:naming_service:nested_scopes = "false";

307
CHAPTER 19 | Using the CICS Server Adapter

Exporting Object References to Naming Service Object Group

Overview When it comes to exporting object references to the Naming Service, the
server adapter can be configured to export to either a Naming Service
context or a Naming Service object group. This subsection provides details
about exporting to a Naming Service object group.

Note: The simultaneous exporting of object references to both a Naming

Service context and a Naming Service object group is not supported. See
the Orbix Administrator’s Guide for more details on Naming Service object
groups.

Prerequisites If the server adapter is configured to export its object references to a set of
Naming Service object groups, the following prerequisites apply:
• The Naming Service used must support the Orbix load balancing
extensions to the Naming Service.
• The initial reference for the Naming Service must be available to the
adapter either in the adapter’s configuration file or via the command
line at start-up.
• The object group must be predefined, so that the load balancing
algorithm defined for each object group can be used—the load
balancing algorithm might be round-robin, random, or some other
custom load balancing algorithm.

Summary of rules The following rules apply when mapping object references to a Naming
service object group:
• An object group must be created for each object before the adapter is
started; otherwise, the objects will not be exported. If you are unsure
about the names of the object groups, start the adapter without any
object groups created and check the error messages to see which
object groups are needed.
• The object groups must then be bound to “objects”, so that clients can
locate them. The fact that object groups are used is transparent to the
clients.

308
 Exporting Object References at Runtime

• Each adapter must have a unique member name to ensure that it does
not overwrite object group members created by other adapters.
• Members are only removed if the adapter shuts down normally; for
example, by using an operator Stop command, by using itadmin mfa
stop, or by calling the stop operation on the adapter’s MappingGateway
interface.

Configuration Both the plugins:cicsa:object_publisher:naming_service:group:

prefix and plugins:cicsa:object_publisher:naming_service:group:
member_name configuration items indicate that the adapter should write its
object references to a Naming Service object group.
If a value of "" (that is, an empty prefix) is specified for
plugins:cicsa:object_publisher:naming_service:group:prefix, the
object references are written to object groups derived from the interface
name only; otherwise, the prefix is attached to the derived names for each
object group.

Note: The object groups must exist when the adapter is started. See the
Orbix Administrator’s Guide for details on how to create and specify
nested Naming Service contexts.

The object reference for each interface is placed in the relevant object group,
with the member name obtained from the plugins:cicsa:object_
publisher:naming_service:group:member_name configuration variable. A
unique member name must be specified for each adapter that is to use the
set of object groups.

Object group name The object group name used for each object bound into the Naming Service
is derived from the module and interface name. First, all the module names
are used and then the interface name, each separated by a colon. For
example, the object group name for the interface for the simple
demonstration is Simple:SimpleObject. If the prefix is not blank, it is
attached to the start of each derived object group name before the object
group is located in the naming service. The MappingGateway interface uses
IT_MFA as the object group name.

309
CHAPTER 19 | Using the CICS Server Adapter

rebind() function The adapter uses rebind() to add the object references to the Naming
Service, so any existing member in the object group is replaced.

Example For example, consider the following configuration settings:

plugins:cicsa:object_publishers = ["naming_service"];
plugins:cicsa:object_publisher:naming_service:group:prefix = "group1_";
plugins:cicsa:object_publisher:naming_service:group:member_name = "adapter1";
plugins:cicsa:object_publisher:naming_service:update_mode = "current";
plugins:cicsa:object_publisher:naming_service:nested_scopes = "false";

Assuming the interface for the simple demonstration is the only one
exported by the adapter, the following itadmin commands create object
groups called group1_IT_MFA, group1_IT_MFA_CICS:cicsraw, and
group1_Simple:SimpleObject:

itadmin nsog create -type rr group1_IT_MFA

itadmin nsog create -type rr group1_IT_MFA_CICS:cicsraw
itadmin nsog create -type rr group1_Simple:SimpleObject

Note: You can also create object groups via an equivalent piece of JCL.

Now, with the three round-robin object groups created, each needs to be
bound to a context in the Naming Service, so that clients can locate the
object references. For example, the following command creates a context
called testog:

itadmin ns newnc testog

Each object group should be subsequently created in this context, using the
following commands, so that clients can locate the objects:

itadmin nsog bind -og_name group1_IT_MFA testog/IT_MFA

itadmin nsog bind -og_name group1_IT_MFA_CICS:cicsraw testog/cicsraw
itadmin nsog bind -og_name group1_ Simple:SimpleObject testog/simple

310
 Exporting Object References at Runtime

Based on the preceding command, the content of the testog context should
now be listed as follows (when you specify an itadmin ns list testog
command):

IT_MFA Object
cicsraw Object
simple Object

If a client now resolves one of the object references before any adapter is
started, a nil object will be returned. For example, consider the following
command:

itadmin ns resolve testog/cicsraw

If the preceding itadmin command is entered before an adapter is started,

the following output is returned:

IOR:00000000000000010000000000000000

If the preceding itadmin command is entered after an adapter is started, the

following output is returned:

IOR:00000000000000254944…

Running simultaneous adapters If more than one adapter is started, each time resolve() is used it gives a
different object reference, based on the load balancing algorithm specified
when the object group was created.
If all the adapters are stopped normally and the following configuration has
been specified, resolve again returns a nil object reference:

plugins:cicsa:object_publisher:naming_service:update_mode = "current"

311
CHAPTER 19 | Using the CICS Server Adapter

312
 Part 5
Securing and Using the
Client Adapter
In this part This part contains the following chapters:

Securing the Client Adapter page 315

Using the Client Adapter page 329

 CHAPTER 20

Securing the Client

Adapter
This chapter provides details of security considerations
involved in using the client adapter. It provides a review of
general Orbix security implications and the relevant CICS
security mechanisms. It describes the various security modes
that the APPC-based client adapter supports, with particular
emphasis on how each mode affects the existing CICS security
mechanisms.

In this chapter This chapter discusses the following topics:

Security Configuration Items page 316

Common Security Considerations page 321

APPC Security Considerations page 323

315
CHAPTER 20 | Securing the Client Adapter

Security Configuration Items

Overview This section provides an example and details of how to configure the client
adapter to run with Transport Layer Security (TLS) enabled. The sample
configuration includes a csiv2 sub-scope that highlights the configuration
items required to propagate CSIv2 user/password credentials to
CSIv2-enabled targets.

Sample configuration Example 13 provides an overview of the configuration items used to enable
security with the client adapter.

Example 13: Sample Security Configuration for Client Adapter (Sheet 1 of

3)

plugins:security:share_credentials_across_orbs = "true";

# By default, use TLS V1. Downgrade to SSL V3 if the remote

# peer is unable to support TLS V1.
policies:mechanism_policy:protocol_version = ["TLS_V1", "SSL_V3"];

# Please change the following if you have only export strength

# encryption available on the machine.
policies:mechanism_policy:ciphersuites = ["RSA_WITH_RC4_128_SHA",
"RSA_WITH_RC4_128_MD5"];

plugins:systemssl_toolkit:saf_keyring
= "%{LOCAL_SSL_USER_SAF_KEYRING}";

principal_sponsor:use_principal_sponsor = "true";
principal_sponsor:auth_method_id = "security_label";

# By default, use the 'iona_services' certificate from the keyring

principal_sponsor:auth_method_data = ["label=iona_services"];

# By default the following policies are used to deploy a

# fully secure domain where client authentication is not required:
#
policies:target_secure_invocation_policy:requires =
["Confidentiality", "DetectMisordering",
"DetectReplay", "Integrity"];
policies:target_secure_invocation_policy:supports =

316
 Security Configuration Items

Example 13: Sample Security Configuration for Client Adapter (Sheet 2 of

3)

["Confidentiality", "EstablishTrustInTarget",
"EstablishTrustInClient", "DetectMisordering",
"DetectReplay", "Integrity"];
policies:client_secure_invocation_policy:requires =
["Confidentiality", "EstablishTrustInTarget",
"DetectMisordering", "DetectReplay", "Integrity"];
policies:client_secure_invocation_policy:supports =
["Confidentiality", "EstablishTrustInClient",
"EstablishTrustInTarget", "DetectMisordering",
"DetectReplay", "Integrity"];

iona_services
{
…
cics_client
{
plugins:cicsa:iiop_tls:host = "%{LOCAL_HOSTNAME}";
plugins:cicsa:iiop_tls:port = "5172";

orb_plugins = ["local_log_stream", "iiop_profile", "giop",

"iiop_tls", "ots", "amtp_appc"];

ots
{
orb_plugins = ["local_log_stream", "iiop_profile",
"giop", "iiop_tls"};
};

csiv2
{
# enable csiv2 authentication
#

orb_plugins = ["iiop_profile", "giop", "iiop",

"iiop_tls", "local_log_stream",
"ots", "gsp", "amtp_appc"];

event_log:filters = ["IT_CSI=*", "IT_GSP=*",

"IT_IIOP_TLS=*",
"IT_MFA=INFO_HI+WARN+ERROR+FATAL"];

binding:client_binding_list
= ["OTS+TLS_Coloc+POA_Coloc",
"TLS_Coloc+POA_Coloc",

317
CHAPTER 20 | Securing the Client Adapter

Example 13: Sample Security Configuration for Client Adapter (Sheet 3 of

3)

"OTS+POA_Coloc", "POA_Coloc",
"CSI+OTS+GIOP+IIOP_TLS", "OTS+GIOP+IIOP_TLS",
"CSI+GIOP+IIOP_TLS", "GIOP+IIOP_TLS",
"CSI+OTS+GIOP+IIOP", "OTS+GIOP+IIOP",
"CSI+GIOP+IIOP", "GIOP+IIOP"];

principal_sponsor:csi:use_principal_sponsor = "true";
principal_sponsor:csi:auth_method_id = "GSSUPMech";

# Provide the correct username, password, and domain

# for the user you would like to authenticate.
principal_sponsor:csi:auth_method_data = ["username=IONAAdmin",
"password=admin",
"domain=IONA"];

policies:csi:auth_over_transport:client_supports = ["EstablishTrustInClient"];

};
};

Summary of global scope The following is a summary of the security-related configuration items
configuration items associated with the global scope:
plugins:security:share_ Enables own security credentials to be
credentials_across_orbs shared across ORBs. Normally, when
you specify an own SSL/TLS
credential (using the principal sponsor
or the principal authenticator), the
credential is available only to the ORB
that created it. By setting this
configuration item to true, however,
the own SSL/TLS credentials created
by one ORB are automatically made
available to any other ORBs that are
configured to share credentials.
policies:mechanism_policy: Specifies the protocol version used by
protocol_version a security capsule (ORB instance). It
can be set to SSL_V3 or TLS_V1.
policies:mechanism_policy: Specifies a list of cipher suites for the
ciphersuites default mechanism policy.

318
 Security Configuration Items

plugins:systemssl_toolkit: Specifies the RACF keyring to be used

saf_keyring as the source of X.509 certificates.
This must match the keyring you
specified in the GENCERT JCL.
principal_sponsor:use_principal_ This must be set to true to indicate
sponsor that the certificate information is to be
specified in the configuration file.
principal_sponsor:auth_method_id This must be set to security_label
to indicate that the certificate lookup
should be performed using the label
mechanism.
principal_sponsor:auth_method_ If you are using TLS security, this
data specifies the label that should be used
to look up the SSL/TLS certificate in
the SAF key store. The specified label
name must match the label name
under which the server certificate was
imported into, or created in, the key
store (for example, in RACF).
policies:target_secure_ Specifies the invocation policy
invocation_policy:requires required by the server for accepting
secure SSL/TLS connection attempts.
policies:target_secure_ Specifies the invocation policies
invocation_policy:supports supported by the server for accepting
secure SSL/TLS connection attempts.
policies:client_secure_ Specifies the invocation policy
invocation_policy:requires required by the client for opening
secure SSL/TLS connections.
policies:client_secure_ Specifies the invocation policies
invocation_policy:supports supported by the client for opening
secure SSL/TLS connections.
orb_plugins The iiop_tls plug-in must be added
to this list, to enable TLS support.
Note: Remove the iiop plug-in if you
explicitly wish to disable all insecure
communications.

Note: See the Mainframe Security Guide for more details of these
configuration items.

319
CHAPTER 20 | Securing the Client Adapter

Summary of CSIV2 configuration The following is a summary of the configuration items associated with the
items iona_services:cics_client:csiv2 security plug-in:

orb_plugins The csi plug-in must be added to

this list for CSIv2 credentials
propagation.
Note: The iiop_tls plug-in is a
prerequisite for CSIv2 and must also
be included if the csi plug-in is used.
event_log:filters All CSIv2-specific messages
(informational and otherwise) can be
enabled by adding IT_CSI=* to this
list.
binding:client_binding_list Specifies a list of potential client-side
binding chains. The CSI binding must
be added to the relevant chains to
effect CSIv2 credential propagation
at invocation time.
principal_sponsor:csi: This must be set to true to indicate
use_principal_sponsor that the CSIv2 credential information
is to be specified in the configuration
file.
principal_sponsor:csi: This must be set to GSSUPMech.
auth_method_id
principal_sponsor:csi: This list is used to specify the
auth_method_data credentials information.
policies:csi:auth_over_transport: This must be set to
client_supports EstablishTrustInClient to indicate
that the client is capable of
propagating credentials.

320
 Common Security Considerations

Common Security Considerations

Overview This section provides details of common security considerations involved in
using the CICS client adapter. It discusses the following topics:
• Orbix SSL/TLS
• iSF integration
• Principal propagation

Orbix SSL/TLS Orbix provides Transport Layer Security (TLS) that enables secure
connectivity over IIOP. TLS includes authentication, encryption, and
message integrity. As with all Orbix applications, you can configure the CICS
client adapter to use TLS. See the Mainframe Security Guide for details on
securing CORBA applications with SSL/TLS.

iSF integration The IONA security framework (iSF) provides a common security framework
for all Orbix components in your system. This framework is involved at both
the transport layer (using TLS) and the application layer (using the CORBA
CSIv2 protocol and the Orbix generic security plug-in (GSP)). At the
application level, in terms of the CICS client adapter, one of the following
authentication credentials can be passed:
• username/password/domain name
• Single sign-on (SSO) token
You can configure the client adapter to use CSI/GSP support. See the
Mainframe Security Guide for details on iSF and integration with an off-host
Security service.

Principal propagation By default, when an Orbix CICS client invokes a request via the client
adapter, it passes the user ID of the running CICS transaction to the client
adapter as part of the requesting message. The client adapter will then
interact with the GIOP Current interface to set the outgoing principal
identifier to this CICS user ID. If the GIOP plug-in has been configured
appropriately, this ID is then sent as part of the CORBA request to the target
server.

321
CHAPTER 20 | Securing the Client Adapter

The following table highlights the pertinent GIOP configuration settings:

policies:giop:interop_policy: This instructs GIOP to propagate a
send_principal = "true"; principal value if one has been
specified for the outgoing client
request. For example, the
local_principal_as_string()
attribute in the GIOP Current
interface can be used to set a
text-based user ID.
policies:giop:interop_policy: For GIOP 1.2, if this item is set to
enable_principal_service_contexttrue, it instructs the client adapter
to insert the outgoing principal
string in a service context. This is
required because the
CORBA::Principal field is not
available in the request header for
GIOP 1.2 messages. The default
value is false.
policies:giop:interop_policy: This item specifies the service
principal_service_context_id context ID into which the CICS
client adapter attempts to insert
the principal string, if
policies:giop:interop_policy:
enable_principal_service_
context has been set to true. If
this configuration setting is not
specified, a default ID of
0x49545F44 is used to create the
service context.
Note: You cannot configure the
default processing behavior of the
client adapter. For example, setting
the use_client_principal
configuration item has no effect in
this case. To customize the
processing behavior of the client
adapter (for example, to map the
CICS user ID to a network ID), you
can use the Orbix PDK to develop a
client-side interceptor.

322
 APPC Security Considerations

APPC Security Considerations

Overview This section provides details on how to secure the client adapter in an APPC
environment. It discusses the following topics:
• Overview of APPC security
• APPC LU security
• Define the CICS connection with BINDSECURITY
• Define APPCLU RACF profiles
• APPC conversation security
• Controlling access to the client adapter LU
• Controlling access to the CICS local LU

Overview of APPC security APPC/MVS provides the following levels of security:

• LU security
• Conversation security

APPC LU security The client adapter processes client transactions from CICS. Therefore, CICS
should be allowed to establish sessions with the client adapter. Other APPC
applications on the network, however, are not intended to process requests
via the client adapter. In some environments it might be considered a
security breach if any application other than CICS establishes an APPC
connection with the client adapter.
To prevent applications other than CICS from establishing sessions with the
client adapter, APPC LU security can be used. Enable APPC LU security by
doing the following:
• Define the VTAM APPLs for the system base LU and the client adapter
with the appropriate keywords
• Define the CICS CONNECTION with BINDSECURITY
• Define APPCLU RACF profiles
• Define VTAM APPLs with Security Keywords

323
CHAPTER 20 | Securing the Client Adapter

For the system base LU, make sure the following keywords are defined on
the VTAM APPL definition:

Table 9: APPC LU Security System Base LU Keyword Definitions

Keyword Description

SECACPT=CONV This keyword allows CICS to provide security

information on a request to allocate a conversation.
The security information includes the user ID
making the request to allocate the conversation, the
user’s group ID, and an “already verified” indicator.

VERIFY=OPTIONAL This setting makes the definition compatible with

the client adapter.

For the client adapter LU, make sure the following keywords are defined on
the VTAM APPL definition:

Table 10: APPC LU Security Client Adapter LU Keyword Definitions

Keyword Description

SECACPT=CONV Allows security information on the allocate request

as described above.

VERIFY=REQUIRED This keyword requires that a RACF APPCLU profile is

defined for this LU and for any LU that attempts to
establish a session with it. If RACF APPCLU profiles
do not exist, the session cannot be established. If
profiles do exist, the session keys in each profile
must match; otherwise, the session cannot be
established.

Define the CICS connection with Setting BINDSECURITY on the CICS CONNECTION causes CICS to perform bind
BINDSECURITY time security when attempting to establish sessions with the client adapter.
Set BINDSECURITY(YES) on the CONNECTION definition. Refer to “Bind Time
Security with APPC” on page 106 for more information on bind time
security and the prerequisites for its use.

324
 APPC Security Considerations

Define APPCLU RACF profiles The CICS local LU and the client adapter LU require RACF APPCLU profiles.
The names have the following pattern:

NETID.LU01.LU02

NETID represents your network ID. LU01 and LU02 are the LU names to be
secured. Each LU requires its own profile. The profile name in the preceding
example would be for LU01. The profile name for LU02 would be as follows:

NETID.LU02.LU01

Even though CICS makes use of the system base LU to establish sessions
with the client adapter, it is not the LU that must be secured. The LU
defined in the CICS SIT APPLID parameter is the LU that must be secured.
The following is an example of defining the profiles for the CICS local LU
and the client adapter LU:

RDEFINE APPCLU P390.CICSTS1.ORXLUCA1

UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))

RDEFINE APPCLU P390.ORXLUCA1.CICSTS1

UACC(NONE) SESSION(SESSKEY(137811C0) CONVSEC(ALREADYV))

To activate the profiles in RACF, use the following command:

SETROPTS CLASSACT(APPCLU)

To refresh the profile in VTAM, use the following VTAM command:

F VTAM,PROFILES,ID=CICSTS1
F VTAM,PROFILES,ID=ORXLUCA1

In the preceding example, VTAM is the name of the procedure used to start
VTAM.

Note: Although APPC can be used for networked communication, the

client adapter is only intended to be run on the same machine as the CICS
region with which it is communicating.

325
CHAPTER 20 | Securing the Client Adapter

APPC conversation security There are three levels of conversation security:

• security_none
• security_same
• security_pgm

The Orbix runtime inside CICS uses security_same when allocating its
conversations with the client adapter.
A conversation using security_pgm is not possible with the client adapter,
because the Orbix runtime inside CICS has no access to client passwords.
APPC conversation security allows for:
• Controlling which users are permitted access to the client adapter LU
• Controlling which users are permitted to access the CICS local LU
Refer to “LU 6.2 conversation security levels” on page 231 for more details
on each conversation security level.

Controlling access to the client Some environments might want very strict controls regarding which users
adapter LU are permitted access to the client adapter. A RACF APPL class can be
defined for the client adapter LU specifying a universal access of NONE.
Individual users can then be permitted access to the client adapter LU.
An example of defining the RACF APPL class is as follows:

RDEFINE APPL ORXLUCA1 UACC(NONE)

Individual users can then be permitted access to the client adapter LU:

PERMIT ORXLUCA1 CLASS(APPL) ID(USER1) ACCESS(READ)

PERMIT ORXLUCA1 CLASS(APPL) ID(USER2) ACCESS(READ)
…

Activate the APPL class as follows:

SETROPTS CLASSACT(APPL) RACLIST(APPL)

Refresh the RACLIST as follows:

SETROPTS RACLIST(APPL) REFRESH

326
 APPC Security Considerations

Controlling access to the CICS Access to the client adapter LU can be controlled by controlling access to
local LU the CICS local LU that wants to establish communications with the client
adapter LU. The CICS local LU is considered an APPC port of entry and can
be secured with the RACF APPCPORT class.
Define the APPCPORT profile for the CICS local LU as follows:

RDEFINE APPCPORT CICSTS1 UACC(NONE)

This profile defines a universal access of NONE to the system base LU. To
permit access to users, use the RACF PERMIT command:

PERMIT MVSLU01 CLASS(APPCPORT) ID(USER1) ACCESS(READ)

PERMIT MVSLU01 CLASS(APPCPORT) ID(USER2) ACCESS(READ)
…

Activate the APPCPORT class as follows:

SETROPTS CLASSACT(APPCPORT) RACLIST(APPCPORT)

When changes are made to an APPCPORT profile, refresh the profile for the
change to take effect:

SETROPTS RACLIST(APPCPORT) REFRESH

327
CHAPTER 20 | Securing the Client Adapter

328
 CHAPTER 21

Using the Client

Adapter
This chapter provides information on running and using the
client adapter. It provides details on how to start and stop the
client adapter, and also provides details on how to run multiple
client adapters.

In this chapter This chapter discusses the following topics:

Starting the Client Adapter page 330

Stopping the Client Adapter page 332

Running Multiple Client Adapters Simultaneously page 333

329
CHAPTER 21 | Using the Client Adapter

Starting the Client Adapter

Overview This section describes how to start the client adapter. It discusses the
following topics:
• Starting the client adapter on native z/OS
• Starting the client adapter on z/OS UNIX System Services
• Running with a different configuration scope

Starting the client adapter on In a native z/OS environment, you can start the client adapter in any of the
native z/OS following ways:
• As a batch job.
• Using a TSO command.
• As a started task (by converting the batch job into a started task).
The default client adapter is the client adapter for which configuration is
defined directly in the iona_services.cics_client scope, and not in some
sub-scope of this. The following is sample JCL to run the default client
adapter:

//CICSCA JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//* Run the Orbix CICS Client Adapter
//*
//* Make the following changes before running this JCL:
//*
//* 1. Change 'SET DOMAIN='DEFAULT@' to your configuration
//* domain name.
//*
// SET DOMAIN='DEFAULT@'

330
 Starting the Client Adapter

//*
//GO EXEC PROC=ORXG,
// PROGRAM=ORXCICSA,
// PPARM='run -ORBname iona_services.cics_client'
//TYPEINFO DD DUMMY
//ITDOMAIN DD DSN=&ORBIXCFG(DOMAIN),DISP=SHR

Starting the client adapter on z/OS On z/OS UNIX System Services, you can start the client adapter from the
UNIX System Services shell. The following command is used to run the default client adapter:

$ itcicsca

Running with a different To run the client adapter with a different configuration scope:
configuration scope • On native z/OS set the value of PPARM to the new scope, for example:

PPARM=’-ORBname iona_services.cics_client’

• On z/OS UNIX System Services run a command similar to the

following:

$ itcicsa -ORBname iona_services.cics_client

Refer to “Running Multiple Client Adapters Simultaneously” on page 333 for

more details on running multiple client adapters.

331
CHAPTER 21 | Using the Client Adapter

Stopping the Client Adapter

Overview This section describes how to stop the client adapter. It discusses the
following topics:
• Stopping the client adapter on native z/OS
• Stopping the client adapter on z/OS UNIX System Services

Stopping the client adapter on To stop a client adapter job on native z/OS, issue the STOP (P) operator
native z/OS command from the console.

Stopping the client adapter on To stop a client adapter process on z/OS UNIX System Services, use the
z/OS UNIX System Services kill command or press Ctrl-C if it is running in an active rlogin shell.

332
 Running Multiple Client Adapters Simultaneously

Running Multiple Client Adapters

Simultaneously
Overview This section describes how to run multiple client adapters simultaneously.

In this section This section discusses the following topics:

Load Balancing with Multiple Client Adapters page 334

Running Two Client Adapters on the Same z/OS Host page 336

333
CHAPTER 21 | Using the Client Adapter

Load Balancing with Multiple Client Adapters

Overview The client adapter is a multi-threaded application that can concurrently
service multiple requests. However, an installation can choose to run
multiple client adapters to spread the workload over address spaces when
using APPC. When using cross memory, this scenario does not apply.
This subsection discusses the following topics:
• Load balancing scenario
• Graphical overview
• Load balancing scenario explanation

Load balancing scenario Suppose there are three CICS regions that might run client transactions to
be processed via the client adapter. An installation might choose to run two
client adapters to process the load. If one of the client adapters is stopped,
the other can still service client requests from CICS.

Graphical overview Figure 9 illustrates the load balancing scenario.

CICS Target
Region 1 Object
Client
Adapter 1
Configuration
CICS
APPC/MVS
Region 2

Client
Adapter 2
CICS Target
Region 3 Object

Figure 9: Graphical Overview of a Load Balancing Scenario

334
 Running Multiple Client Adapters Simultaneously

Load balancing scenario Each CICS region contains an Orbix runtime. Each Orbix runtime has a
explanation configuration that specifies the same symbolic destination. The symbolic
destination determines the client adapter that CICS client transaction
requests are being directed to. From the CICS perspective, it appears as if
there is only one client adapter running.
APPC/MVS processes the CICS client transaction requests. It queues the
requests in an allocation queue. The allocation queue is determined by the
symbolic destination. Because all CICS regions are using the same symbolic
destination, CICS client transaction requests are directed to a single
allocation queue.
Both client adapters are using the same configuration file and same
configuration scope. Therefore, they are using the same symbolic
destination, and share the same allocation queue that APPC/MVS uses for
CICS client transaction requests. Each client adapter has one or more
threads that are waiting for allocation requests from APPC/MVS, all from the
same allocation queue.
APPC/MVS hands off an allocation request to a thread in one of the client
adapters. Determining which thread to give an allocation request to is an
internal function of APPC/MVS. Therefore, it is APPC/MVS that spreads the
load over the two client adapters. If one of the client adapters is stopped,
APPC/MVS hands off all allocation requests to the client adapter that is still
running.

335
CHAPTER 21 | Using the Client Adapter

Running Two Client Adapters on the Same z/OS Host

Overview An installation might choose to run a test and production client adapter on
the same z/OS host. In this scenario, when using APPC, it is not desirable
for the client adapters to share the APPC/MVS allocate queues.
This subsection discusses the following topics:
• Running a test and production client adapter on the same host
• Graphical overview
• Setting up a test and production client adapter on the same host

Running a test and production Each CICS region contains an Orbix runtime. Each Orbix runtime has a
client adapter on the same host configuration that specifies different symbolic destinations. The production
CICS region is configured to communicate with the production client
adapter. The test CICS region is configured to communicate with the test
client adapter.

Using APPC
When using APPC, APPC/MVS processes the CICS client transaction
requests. It queues the requests to separate allocation queues—one for the
production client adapter using the production symbolic destination, and
one for the test client adapter using the test symbolic destination.
Both client adapters are using the same configuration file but different
configuration scopes. The configuration scopes can define different symbolic
destinations. Therefore, the client adapters each have their own allocation
queues.

Using cross memory

When using cross memory, the data from the CICS client transaction is sent
directly to the client adapter address space. The data from the production
CICS is sent directly to the production client adapter, and the data from the
test CICS is sent directly to the test client adapter.
Both client adapters are using the same configuration file but different
configuration scopes. The configuration scopes can define different symbolic
destinations. Therefore, the client adapters each have their own name/token
pairs.

336
 Running Multiple Client Adapters Simultaneously

Graphical overview Figure 10 illustrates how two client adapters can run on the same z/OS host
when using APPC.

Target
Production
Object
Client
CICS Adapter
Production
Region Configuration
Production Scope
APPC/MVS & Test Scope
CICS Test
Region Test Client
Adapter
Target
Object

Figure 10: Running Two Client Adapters on the Same z/OS Host

Setting up a test and production The steps to set up a test and production client adapter on the same z/OS
client adapter on the same host host are as follows:

Step Action

1 When using APPC, define separate symbolic destinations in

APPC/MVS for the test and production client adapters to use.
Refer to “Defining an APPC Destination Name for the Client
Adapter” on page 166 for more information on defining
symbolic destinations.

2 Configure the Orbix runtime inside CICS for the test and
production regions. The test region is configured with the test
symbolic destination. The production region is configured with
the production symbolic destination. Refer to “Customizing
Orbix Symbolic Destination” on page 206 for more information
on configuring the symbolic destination.

337
CHAPTER 21 | Using the Client Adapter

Step Action

3 Define a test configuration scope in the client adapter

configuration file such as iona_services.cics_test_client.
The existing iona_services.cics_client configuration scope
can be used for production. Set the test symbolic destination in
the test configuration scope, and set the production symbolic
destination in the production configuration scope.
When using APPC, refer to “APPC destination” on page 180 for
more information on configuring the symbolic destination.
When using cross memory, refer to “Cross memory
communication destination” on page 191 for more information
on configuring the symbolic destination.

4 Start the production client adapter, specifying a configuration

scope of iona_services.cics_client. Start the test client
adapter specifying the test configuration scope defined in step
3 (that is,. iona_services.cics_test_client). Refer to
“Starting the Client Adapter” on page 330 for more information
on running the client adapter with a different configuration
scope.

338
 Part 6
Appendices
In this part This part contains the following chapters:

Troubleshooting page 341

Glossary of Acronyms page 345

 APPENDIX A

Troubleshooting
This chapter provides an overview of the MCLOOKUP utility
that can be used for troubleshooting.

In this chapter This chapter discusses the following topics:

Overview page 342

Starting the MCLOOKUP utility on native z/OS page 342

Starting the MCLOOKUP utility on z/OS UNIX System Services

page 343

341
CHAPTER A | Troubleshooting

Overview The MCLOOKUP utility is supplied with your Orbix Mainframe installation and
can be used to perform lookups on system exception minor codes. It serves
as a troubleshooting tool in cases where an errant CORBA application
reports a minor code but does not display a useful message.

Starting the MCLOOKUP utility on In a native z/OS environment, you can start the MCLOOKUP utility using the
native z/OS following sample JCL:

Note: In the following example, a minor code value of Ox49540102 is

passed across to MCLOOKUP for investigation.

//MCLOOKUP JOB (),

// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(1,1),
// NOTIFY=&SYSUID,
// REGION=0M,
// TIME=1440
//*
// JCLLIB ORDER=(HLQ.ORBIX63.PROCLIB)
// INCLUDE MEMBER=(ORXVARS)
//*
//* Run the Minor Code Lookup utility
//*
//* Please customise the search criteria via the PPARM variable
//* before running this utility
//*
//* Usage:
//* MCLOOKUP .query options.
//*
//* Query options (include a subset of the following):
//* -mcv/-minor_code_value .val. Specify minor code value
//* as search criteria
//* -exn/-exception_name .val. Specify exception name
//* as search criteria
//* -sbn/-subsystem_name .val. Specify subsystem name
//* as search criteria
//* -mcn/-minor_code_name .val. Specify minor code name
//* as search criteria
//*
//* Examples:
//* MCLOOKUP -mcv 0x49540102
//* MCLOOKUP -mcv 1230242050 -exn TRANSIENT

342
 //*
//*
//GO EXEC PROC=ORXG,
// PROGRAM=ORXMCLUP,
// PPARM='-mcv 0x49540102'

Starting the MCLOOKUP utility on On z/OS UNIX System Services, use the following command to run the
z/OS UNIX System Services MCLOOKUP utility:

mclookup -mcv minor_code

For example:

mclookup -mcv 0x49540102

343
CHAPTER A | Troubleshooting

344
 APPENDIX B

Glossary of
Acronyms
This glossary provides an expansion for each of the acronyms
used in this guide.
For more details of each of these terms, refer to the following, as
appropriate:
• The IBM documentation series at http://www.ibm.com.
• The OMG CORBA specification at http://www.omg.org.
• The Sun Microsystems J2EE specification at http://www.sun.com.

Table 11: Glossary of Acronym Extensions

Acronym Extension

ACB Access Control Block

ACEE Accessor Environment Entry

APAR Application Program Authorized Report

APPC Advanced Program to Program Communication

ASCII American National Standard Code for Information

Interchange

CICS Customer Information Control System

CORBA Common Object Request Broker Architecture

345
CHAPTER B | Glossary of Acronyms

Table 11: Glossary of Acronym Extensions

Acronym Extension

CSD CICS System Definition Data Set

DASD Direct Access Storage Device

DLL Dynamic Link Library

EBCDIC Extended Binary-Coded Decimal Interchange Code

EJB Enterprise Java Beans

GIOP General Inter-ORB Protocol

HFS Hierarchal File System

IDL Interface Definition Language

IFR Interface Repository

IIOP Internet Inter-ORB Protocol

IOR Interoperable Object Reference

IPL Initial Program Load

IRC Inter Region Communication

JCL Job Control Language

LE Language Environment

LU Logical Unit

MVS Multiple Virtual Systems

OMG Object Management Group

OMVS Open Multiple Virtual Systems

ORB Object Request Broker

OTS Object Transaction Service

PADS Program Access to Data Sets

PCB Program Control Block

346
Table 11: Glossary of Acronym Extensions

Acronym Extension

PDS Partitioned Data Set

PSB Program Specification Block

RACF Resource Access Control Facility

RRS Resource Recovery Services

SAF System Authorization Facility

SNA System Network Architecture

SPA Save Program Area

TCP/IP Transmission Control Protocol over Internet Protocol

TP Transaction Program

TPN Transaction Program Name

TSL Transport Security Layer

TSO Time Sharing Option

UACC Universal Access Authority

USS UNIX System Services

VTAM Virtual Telecommunications Access Method

XCF Cross Coupling Facility

WFI Wait For Input

WTO Write-To-Operator

347
CHAPTER B | Glossary of Acronyms

348
Index
A BPX.SERVER 129
ACBNAME= parameter 103, 171 and Adapter user ID 132
address space, non swappable 187 BPX.SRV.* resource 132
address space ID 189 BPX.SRV.userid resource 132
amtp_appc 151 ByteSegments attribute 49
amtp_appc plug-in configuration items 152
AMTP function timeout 180 C
AMTP_XMEM 183 C++ demonstration for cicsraw 51
amtp_xmem 151 C++ standard classes support 136
APF authorization 122 CEDA transaction 92
APF-authorized 185 CharSegments attribute 48
APPC 148 CICS
APPC/MVS side information dataset, specifying 164 configuring inside 200
APPC data segment length 111 customizing 136
APPC destination 180 defining APPC resources to 104
APPC destination name 100, 110, 166 cicsa plug-in configuration items 66, 125
multiple 168 cics_appc plug-in configuration items 73
APPCLU class profiles 103 CICS APPLID 94
format 234 CICS commit processing 65
APPCLU profile name 107 CICS connection name 94
and LU name 99 CICS Connection Type 94
APPCLU profiles 177 CICS connection type 94
APPCLU profiles, user IDs 107 cics_exci plug-in configuration items 72
APPCLU RACF definitions 106 CICS local LU 163
APPCLU RACF profiles, defining 325 access to 179, 327
APPC maximum communication threads 181 CICS mirror transaction ID, default 95
APPC minimum communication threads 180 CICS pseudo-region 224
APPCPORT profile cicsraw IDL interface 44, 45
CICS local LU 327 ByteSegments attribute 49
APPC resources to CICS 175 C++ demo client 51
APPC-side information data set example 100 CharSegments attribute 48
APPL class, Client Adapter LU 326 CICS mirror transaction ID 95
APPLID 94 din parameter 48
ASCII-to-EBCDIC translation 48 modifications to 44
ASID 189 run_program_binary operation 48
ATBSDFMU utility program 100 run_program_binary_with_tran operation 49
ATTACHSEC(IDENTIFY) 93 run_program operation 48
ATTACHSEC operand, specifying 109 run_program_with_tran operation 49
tran_name parameter 48
B CICS resource definitions
BINDSECURITY 324 installing 137
bind time security 106 CICS resources, access permissions 93
CONNECTION resource 235 cics_rrs plug-in configuration items 73

349
INDEX

CICS security mechanisms cross memory communication 148, 183

for APPC 231 CSD group DFH$EXCI 91
for EXCI 223 CSECT 138, 202
CICS system initialization parameters 225
CICS transaction-attach security 225 D
Client Adapter DASD-only log streams 116
APPC security 323 data types defined in cicsraw 47
change configuration scope 331 default security mode for APPC 236
characteristics 53 default security mode for EXCI 227
configuration scope 149 DESTNAME 101, 167
functions 54 DFH$EXCI 91
graphical overview 54 DFHCSD DD cards 104
load balancing 334 DFHCSDUP, running 92, 137
LU-LU security 177 din parameter 48
multiple on same host 336 do_trans() operation 44
plug-ins 151
starting 330
stopping 332 E
client_adapter 185 EBCDIC, translating from ASCII 48
Client Adapter LU 164 EPERM errors 132
access to 179, 326 errors, EPERM 132
client_principal support configuration items 125 event_log
client Principal value 221 filters
z/OS user IDs 221 Client Adapter 158
clients 25, 27 event_log filters 81
authentication 221 event logging 81, 138, 202
invoking on CORBA objects 29 Client Adapter 158
client stub code 28 event logging settings 202
COMMAREA block size 95 exception information
COMMAREA length, maximum 49 for APPC 50
common_adapter 151 for EXCI 51
Configuration domains 36 exceptions
configuration file 265 address space 132
CONNECTION resource defined in cicsraw 48
ATTACHSEC operand 109 EXCI
bind security 235, 324 default security mode 227
BINDSECURTIY option 106 user security 225
conversation security 326 EXCI GENERIC connection
CONVSEC setting 107 type 94
CORBA 23 update access 224
application basics 28 EXCI limitation on request size 95
introduction to 22 EXCI mirror transaction
CORBA::Principal 125 Adapter default mode 93
SAF plug-in 221 ID 95
CORBA gateway to the CICS system 28 user security enables 93
CORBA objects 25
and IDL 26 G
client invocations on 29 GIOP, client_principal support 125
coupling facility log streams 116 global configuration scope 47

350
 INDEX

H IsDefault 143
host name 78 itadmin commands 271
itadmin mfa refresh command 251
itcicsa shell script 132
I IT_MFA_CICS module 44
IDL compiler 28 IT_MFA event logging subsystem 81
-mfa plug-in 142 itmfaloc 275
operation parameters 29 format 276
IDL interfaces 26 using 277
for CICS Adapter 44 IT_MFU event logging subsystem 158
location for Adapter 43 IXCL1DSU 116
IDL operations 29 IXCMIAPU utility 120
adapter processing of 43
COMMAREA block length 95
parameter-passing modes 29 L
IEFSSNxx member 121 Language Environment Support 136
IFR 36, 245 link security 109, 225
modifications to and Server Adapter 250, 259 Location domains 35
registering IDL interfaces 247 locator 36
running in prepare mode 263 running Adapter in prepare mode 263
IFR signature cache file 252 LOGR couple data set 118, 119
configuration 85, 194 log streams
runtime modifications 253 defining 120
updating 253 IBM recommended sizes 117
IIOP 23 running 117
cicsa plug-in configuration 66 types 116
client_principal configuration 127 LU=LOCAL conversations
mapping gateway interface 272 security settings for 103
TCP-IP port number 79 LU 6.2
timestamps 84 and Adapter usage 232
initial_references:IT_cicsraw:plugin 65, 80, 81 connection to a remote system 106
initial_references:IT_RRS:plugin 122 conversation security levels 231
Interface Definition Language See IDL LU-LU security verification 177
Interface Repository See IFR LU-LU session-level verification 103
iona_services.cicsa configuration scope example 60 LU names
iona_services.cics_client 148 APPC destination 110
iona_services.cics_client.cross_memory 148 outbound LU 110
iordump utility 270 restricting use of 235
IORs 36 specifying 99
and itmfaloc 276 user access 108
IT_MFA 265 LUs
IT_MFA_CICSRAW 265 access to 326
locating Server Adapter 275 CICS local 163
mapping gateway interface 272 Client Adapter 164
POA prefix 83 defined to VTAM 170
sample 266 outbound 231
transactional processing support 114 protecting 179
IRC, enabling 91 VTAM requirements for 102
IRC parameter 91 LU security 323

351
INDEX

M Orbix security mechanisms 221

mapping file 43 ORB-level plug-ins 82
errors 252 ORBname 60, 148
format 239 multiple adapters 271
generating 241 orb_plugins 82
IDL attribute support 240 Client Adapter 160
runtime modifications to 243 ORX1 session 92
Mapping Gateway interface 272 ORXLU02 profile 108
maxCommareaSize attribute 49 ORXMFACx DLL 139, 203
MCLOOKUP utility 341 segment size 204
MFACLINK JCL member 139 OTS plug-in 83
MFAMappingExtension 143 outbound LU 231
MFAMappings 142
MFAMappingSuffix 144 P
mfa plug-in parameter-passing mode qualifiers 29
options 273 PARTNER_LU 101, 167
using 272 partner LU 103
MODENAME 167 passwords
MODENAME parameter 101 and session keys 103
MRO connect security 224 partner LU 103
MRO logon security 224 processing requests without 129
persistence mode policy 78
N plugins:amtp_appc:function_wait 180
naming clash 47 plugins:amtp_appc:max_comm_threads 181
NETNAME of a CICS-specific EXCI connection 94 plugins:amtp_appc:maximum_syncl_level 181
networked environment, controlling access 233 plugins:amtp_appc:min_comm_threads 180
node daemon 35 plugins:amtp_appc:symbolic_destination 180
running Adapter in prepare mode 263 plugins:amtp_xmem:max_comm_threads 191
non-swappable address space 187 plugins:amtp_xmem:max_segment_size 192
numeric data corruption 48 plugins:amtp_xmem:min_comm_threads 191
plugins:amtp_xmem:symbolic_destination 191
plugins:cicsa:alternate_endpoint 79
O plugins:cicsa:direct_persistence 78
object ID 33 plugins:cicsa:display_timings 83
object key 83 plugins:cicsa:display_timings_in_logfile 83
object references 26, 32 plugins:cicsa:ifr:cache 85
and the POA 33 plugins:cicsa:iiop:host 78
map to servants 33 plugins:cicsa:iiop:port 79
ORB (Object Request Broker) plugins:cicsa:mapping_file 84
and the naming service 33 plugins:cicsa:poa_prefix 83
locating objects 36 plugins:cicsa:repository_id 85
ORB_init() 82 plugins:cicsa:type_info:source 86
Orbix 23 plugins:cicsa:use_client_password 127
Orbix application 32 plugins:cicsa:use_client_principal 126
Orbix CICS resource definitions, installing 92 security 227, 236
Orbix configuration inside CICS 200 plugins:cicsa:use_client_principal_user_security 12
Orbix event logging 81 6
Orbix runtime in CICS 138, 202 plugins:cics_appc:appc_outbound_lu_name 99,
parameter-passing modes 29 103, 110

352
 INDEX

plugins:cics_appc:cics_destination_name 101, 110 run_program_with_tran 49

plugins:cics_appc:segment_length 111
plugins:cics_appc:timeout 110 S
plugins:cics_exci:applid 94 S390 Assembler Program Variables 201
plugins:cics_exci:check_if_cics_available 95 SAF Plug-In 221
plugins:cics_exci:default_tran_id 95, 225 sample applications 28
plugins:cics_exci:max_comm_area_length 95 SEC= parameter 106
plugins:cics_exci:pipe_name 94, 224 SECACPT=CONV key 233
plugins:cics_exci:pipe_type 94 SECACPT= parameter 171
plugins:client_adapter:ifr:cache 194 SECPRFX=YES 93
plugins:client_adapter:repository_id 194 security
plugins:client_adapter:type_info:source 195 APPC-based considerations 229
plugins:rrs:rmname 122 common considerations 220
POA (Portable Object Adapter) 33 default mode 227
POA prefix used by adapter 83 default mode APPC 236
policies:giop:interop_policy EXCI-based considerations 222
enable_principal_service_context 127 link 109, 225
principal_service_context_id 128 MRO connect 224
policies:iiop:client_version_policy 127 MRO logon 224
policies:iiop:server_version_policy 127 use_client_principal mode 227
pragma prefix 47 user 109, 225
PREPCICA member 263 security modes
PresetOptions 143 default for APPC 236
principal values, mapping to z/OS user IDs 221 default for EXCI 227
PROCLIB. 190 security_none 231, 233
proxy objects 29 security_pgm 232
pthread_security_np() 131 security_same 232, 233, 234
segment size, customizing 204
R Server Adapter
RACF 231 access to 232
RACF APPCPORT profiles, creating 108 and logged on users 233
RACF FACILITY class profile APPC based 231
READ access 224 APPC security modes 236
update access 224 default mode EXCI requirements 93
RACF GCICSTRN resource class 225 first run 252
RACF SURROGAT class 132 functions 40
RACF TCICSTRN resource class 225 graphical overview 42
RACF user profile 129 locating 275
RECEIVECOUNT 92 obtaining type information 43
refreshInterface() 260 old versions of 44
refreshOperation() 260 ORBname 60
resource manager names 122 plug-ins 65
RESSEC= parameter 225, 227 programmed controlled 132
RRS running in default mode 93
setting up 115 running multiple 270
starting and stopping 121 security for users already logged on 233
run_program 48 security modes 226
run_program_binary 48 starting 267
run_program_binary_with_tran 49 stopping 269

353
INDEX

using type_info store 255 U

servers 25, 27 user ID
session key and access to BPX.SERVER 132
bind requests 106 and ATTACHSEC=LOCAL 109
session key, APPCLU profile name 107 BPX.SERVER 129
session keys 103 for APPCLU profiles 107
session-level verification 234, 235 UPDATE access 224
session security, specifying 106 user security 109, 225
SET PROG 186 enabled on EXCI 93
SETPROG 185
SETRRS CANCEL command 121
SETSSI ADD,SUBNAME=RRS command 121 V
SETXCF operator commands 119 VERIFY= parameter 103, 172
skeleton code 28 VSAM data set name, specifying 99
SNA network VTAM SECACPT= setting 107
access to 103
and LUs 102 W
SPECIFIC connection type 94 WTO announce plug-in 82, 160
S RRS command 121
STEPLIB 104, 185 X
updating CICS region 137 XAPPC= parameter 106
SURROGAT RACF class 129 XPPT= parameter 225
SYS1.MIGLIB 120
SYS1.PARMLIB 187
SYS1.SAMPLIB(ATBAPPL) definition 102, 170 Z
SYSEVENT TRANSWAP 187 z/OS user ID 221
System Logger and RRS 117

T
thread IDs 84
thread-level security environments 129
thread_pool
high_water_mark 74
and RECEIVECOUNT 92
initial_threads 74
thread_pool:high_water_mark 79
thread_pool:initial_threads 79
timestamps 83
TPNAME 101, 167
tran_name parameter 48
transaction processing times 83
troubleshooting 341
TypeinfoFileExtension 143
TypeinfoFileSuffix 144
type information mechanism 85
type_info store
configuration 86, 195
generating files 257
introduction 255

354