tibco activematrix businessworks plug-in for cics … · tibco activematrix businessworks plug-in...

TIBCO ActiveMatrix BusinessWorks™Plug-in for CICS

User’s GuideSoftware Release 1.2September 2012

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIBCO, The Power of Now, TIBCO Hawk, TIBCO Rendezvous, TIBCO Runtime Agent, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, and TIBCO Designer are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1999-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTIBCO ActiveMatrix BusinessWorks Plug-in for CICS Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiThird-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2 CICS Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

CICS Region Shared Resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Pooling Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Transport Layer Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8CICS Region Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

CICS Adapter Mode Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Input Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

CICS Interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Input Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CICS Container Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Input Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

TIBCO ActiveMatrix BusinessWorks Plug-in for CICS User’s Guide

iv | Contents

Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Pool Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Error Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 3 Sample ActiveMatrix BusinessWorks Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Downloading the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Using the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Chapter 4 Security Modes for z/OS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Security Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Unsecured Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Verify Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Identify Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Current Plug-in Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Running in POOL or NON-POOL Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Appendix A Transport Layer Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

RACF Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Personal Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46AT-TLS Configuration with Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

BWCP Project Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55


| v

Preface

TIBCO ActiveMatrix BusinessWorks™ Plug-in for CICS, referred to as the Plug-in in this manual, allows the user to run CICS programs on the host computer and acquire the results for processing in the TIBCO ActiveMatrix BusinessWorks application.

This Plug-in, together with TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion, provides to projects and users the flexibility to perform CICS Request-Reply functions for applications while performing all the orchestration, parsing and rendering locally in a central place.

The most common use case scenario for this feature is one in which the user needs to get or update some information on the host using an existing CICS program to accomplish the task. To accomplish this, the user only requires the name of the program and the copybooks used for its input and output.

Topics

• Changes from the Previous Release of this Guide, page vi

• Related Documentation, page vii

• Typographical Conventions, page ix

• Connecting with TIBCO Resources, page xii


vi | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

Enhancements

The following enhancements are documented in the sections shown:

• Variable Length Commareas A new option has been added to the main configuration page of the CICS Interaction object. The "Data Communication Type" drop down box now contains a third option called "Variable Length Commarea". Selecting this mode makes it possible to control both the size of the commarea provided to the program, as well as an offset into the returned commarea. This offset is used as a starting point when copying the commarea back to the TIBCO ActiveMatrix BusinessWorks activity.

For more information, see options for the Data Communication Type field.

• Improved Abend Detection and Reporting The CICS program abend detection and reporting has been improved. The abend code is now provided to the activty in its exception object.

• Improved Accuracy in Time Stamp The time stamps on messages in the CICS logs are now accurate to 1/1000 of a second, making it easier to dicern the order of events in the log.


Preface | vii

Related Documentation

This section lists documentation resources you may find useful.

TIBCO ActiveMatrix BusinessWorks Plug-in for CICS DocumentationThe following documents form the TIBCO ActiveMatrix BusinessWorks Plug-in for CICS documentation set:

• TIBCO ActiveMatrix BusinessWorks Plug-in for CICS User’s Guide Read this manual for instructions on using the product on Windows platforms.

• TIBCO ActiveMatrix BusinessWorks Plug-in for CICS Installation Read this manual for instructions on site preparation and installation.

• TIBCO ActiveMatrix BusinessWorks Plug-in for CICS Release Notes Read this document for the new features and known issues for this release.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO ActiveMatrix BusinessWorks™ Plug-in for Data Conversion software: This product is a prerequisite for working with TIBCO ActiveMatrix BusinessWorks Plug-in for CICS.

• TIBCO ActiveMatrix BusinessWorks™ software:

— Concepts Read this manual first. It describes the terminology and concepts of ActiveMatrix BusinessWorks. The other manuals in the documentation set assume familiarity with the information in this manual.

— Getting Started This manual steps you through a simple example of designing, deploying, and monitoring an ActiveMatrix BusinessWorks process.

— Process Design Guide This manual describes how to create, edit, and test business processes with ActiveMatrix BusinessWorks.

— Administration This manual describes how to deploy, manage, and monitor ActiveMatrix BusinessWorks processes with TIBCO Administrator™.

— Palette Reference This manual describes the palettes in ActiveMatrix BusinessWorks.


viii | Related Documentation

— Installation This manual shows you how to install one or more components of ActiveMatrix BusinessWorks and how to set up an ActiveMatrix BusinessWorks domain.

— Error Codes This manual describes the errors returned by ActiveMatrix BusinessWorks.

— Release Notes This document describes the new and changed features as well as the closed and known issues in this release.

• TIBCO Designer™ software: TIBCO Designer is an intuitive graphical user interface for design-time configuration of TIBCO applications. Online help is available for TIBCO Designer palettes.

• TIBCO Administrator software: TIBCO Administrator is the monitoring and managing interface for such new-generation TIBCO products as ActiveMatrix BusinessWorks.

Third-Party DocumentationActiveMatrix BusinessWorks is bundled with other products, whose documentation you might find helpful:

• COBOL concepts and syntax — Many resources are available, one of which is Enterprise COBOL for z/OS Language Reference, an IBM publication.

• PL/I concepts and syntax — See the IBM publications:

— Enterprise PL/I for z/OS

— PL/I for AIX

— PL/I for Windows

— Language Reference

• CICS Sockets concept and syntax — See the IBM publications IP CICS Sockets Guide.


Preface | ix

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

ENV_NAME

TIBCO_HOME

TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments.

An installation environment consists of the following properties:

• Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu.

• Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME.

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]


x | Typographical Conventions

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3


Preface | xi

{ } A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}

Table 2 Syntax Typographical Conventions

Convention Use


xii | Connecting with TIBCO Resources

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts, a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access All TIBCO DocumentationYou can access the documentation for many supported product versions here:

http://docs.tibco.com

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, contact TIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

http://docs.tibco.com

http://www.tibcommunity.com

| 1

Chapter 1 Introduction

This chapter provides an overview of the product TIBCO ActiveMatrix BusinessWorks Plug-in for CICS, later referred to as Plug-in in this manual. It discusses the product’s main features and describes how the various components are designed.

Topics

• Product Overview, page 2


2 | Chapter 1 Introduction

Product Overview

The Plug-in allows the user to run CICS programs on the host (mainframe) computer and acquire the results for processing in the ActiveMatrix BusinessWorks application. Both commarea and container-based programs are supported, as well as multi region routing, connection pooling, and copybook rendering and parsing.

The most common use case scenario for this Product is one in which the user needs to get or update some information on the host (mainframe) using an existing CICS program. To accomplish this, the user only requires the following:

• URL for the CICS Region

• Name of the program

• Input copybook for the program commarea (or container)

• Output copybook for the program commarea (or container)

• Security credentials, if required

The Plug-in along with TIBCO ActiveMatrix BusinessWorks Data Conversion Plug-in provides all the support to:

• Take ActiveMatrix BusinessWorks XML data and transform it to CICS program input data

• Deliver input to Mainframe

• Check CICS security

• Run the program with the supplied input

• Receive the output back from CICS

• Deliver the program output back to ActiveMatrix BusinessWorks process in XML form


| 3

Chapter 2 CICS Palette

This chapter describes the capabilities of the CICS palette.

Topics

• CICS Region Shared Resource, page 4

• CICS Adapter Mode Interaction, page 10

• CICS Interaction, page 13

• CICS Container Interaction, page 23

• Pool Manager, page 31


4 | Chapter 2 CICS Palette

CICS Region Shared Resource

The CICS Region Shared Resource represents all the information necessary to make a connection to a CICS region which is running the ActiveMatrix BusinessWorks Integration for CICS Plug-in socket listener.

Configuration TabTable 3 lists and describes the fields under the Configuration tab. .

Table 3 Fields Under Configuration Tab: CICS Region Resource

Field Global Variable Description

Name N The name of the Region Resource.

Default: Region

Description N Description of the resource

Host Y The TCP host name of the machine running the CICS region to which this region connects.

Default: localhost

Port Y The TCP port number on which CICS is listening.

Default: 9911Range: 0-65535


CICS Region Shared Resource | 5

Alternate Hosts

N A list of host:port URIs that together comprise a group of CICS regions that are used to service interactions. These regions must support all the programs used by activities sharing this Region Resource and must also have the same version of the Plug-in host software installed.

In the dialog provided, enter each URI on a separate line. Alternately, the URI's can be comma, semi-colon, or space delimited.

In the event that the current CICS region becomes unavailable, new connections are established using the next available region. The "active" region becomes the default for new connections until it too becomes unavailable, in which case the next region is tried. If no regions are available, the interaction fails.

For pooled Region Resources, the loss of a CICS region may result in the failure of currently executing interactions, after which the pool migrates to the next available CICS region.

Userid Y The userid which will be used to create the TCP connection. This userid becomes the default userid for all interactions executed using this resource. See CICS Region Security on page 8.

Password Y The password for this userid. See CICS Region Security.

Transaction Id

Y A custom transaction identifier that is used to account for application resources for each transaction. This identifier becomes the transaction on whose behalf the connection to CICS is made and under which all Plug-in interactions on this CICS region or regions are run.

To enable this transaction ID, copy the transaction SXNE CSD provided by TIBCO to the name of the custom transaction.

Cleartext Credentials

N Default: disabled

When this function is enabled, the interactions pass security credentials to the CICS region using clear text.

The userid and password are usually encrypted on the network. Use this feature if the installation has replaced the security exit provided by TIBCO with one which requires the security credentials to be in clear text.





Character Set Y The encoding in which the CICS system is running.

Default: IBM037

Socket Option Linger

Y The number of seconds that a slow ActiveMatrix BusinessWorks activity needs to collect its data from the network after the CICS interaction has completed.

Default: 60 (option is not set)Range: 0-255

Pool Connections

N Enables the Pooling tab and enables connection pooling for this resource. If a pooled region resource is used in any activity, the security credentials provided on the region override all others specified on either the activity or its input mapping.

If pooling is enabled for the connections to a region, activities using that pool will be blocked until there is an available connection. The blocking interval corresponds to the pool's Max Wait Time.

Because this blocks threads in BusinessWorks, such activities are made to run in their own threads. Therefore, the size of the pool not only controls the maximum number of simultaneous connections to a given region, but also the number of BusinessWorks threads dedicated to that task.

TLS Enabled N Enable this option in order to display the Transport Layer Security parameters panel. See Transport Layer Security on page 8.

After this field is enabled, you must enter the correct information in the Transport Layer Security parameters panel before you can make a connection to CICS using this resource.





Pooling TabTable 4 lists and describes the fields under the Pooling tab.

Test Connection Button

This button tests the host and port specifications to determine if the socket listener is up. If the port is open, a simple program is run to ensure that the basic infrastructure is working.

Table 4 Fields Under Pooling Tab: CICS Region Resource


Pool Size Y The number of concurrent connections that a given ActiveMatrix BusinessWorks instance will make to this CICS region.


Note that the NUMSOCK CICS socket definition parameter can also limit the number of concurrent connections to CICS. This parameter setting restricts the number of ActiveMatrix BusinessWorks instances connecting pools of Region Resouces to a particular CICS region.

The TIBCO Administrator can also restrict a deployed application’s thread pool size, effectively limiting the number of interactions that can be executed concurrently. The pool size should be less than or equal to the size of the administrator's deployed thread pool.

Connection Lifetime

Y The number of seconds that a pooled connection will remain connected before hanging up. Connections do not persist indefinitely so that CICS resources are not needlessly consumed.


Max Wait Time

Y The number of seconds that an activity will wait for a connection before terminating with an error.


This test button is not compatible for the region in TIBCO Adapter™ for CICS.



Transport Layer SecurityTable 5 lists and describes the fields under the Transport Layer Security parameters panel. This panel appears when the TLS Enabled field is enabled. All fields must be filled correctly before you can make a connection to CICS using this resource.

CICS Region SecurityFrom the security point of view, the configurations for accessing CICS are:

• Legacy Mode In this mode, the CICS socket listeners and other CICS resources will have been installed as part of a CICS Adapter installation, and the security will be as documented in TIBCO AdapterTM for CICS, User’s Guide. If the installation is current (if the current BW plugin for CICS z/OS installation has been performed on the target CICS region), then the credentials provided on the region resource will be used.

Table 5 Fields Under Transport Layer Security: CICS Region Resource


Client Identity File

N Provide the fully qualified name of a PKCS12 encoded certificate file containing the client certificate and private key. This file must be extracted from RACF using the procedure in Appendix A, Transport Layer Security, on page 45.

Identity Password N Provide the password used to encrypt the PKCS12 file when it was extracted from RACF. See the procedure in Appendix A.

Server Cert Chain N Provide all the Certificate Authority (CA) certificates used to sign this identity. The certificates must be in DER format. See the procedure described in Appendix A.

Load Certificates N This button reads the contents of the above files and verifies the passwords and their encoding. If the files appear to be correct, their contents are encrypted and stored in the Region Resource's metadata.

Use the Test Connection button to verify that a connection can be established using these credentials. Once you have verified the connection, it is best to delete the original files or place them in a secure location.



• BW Plugin for CICS Mode In this mode, the CICS administrator will have installed a new set of resources, one of which is a security exit. There are three possibilities for installing the SECEXIT:

a. No SECEXIT All interactions run under the security credentials of the user ID used to start the CICS socket listener. All specified user IDs and passwords are ignored. In this case credential fields can be left blank.

b. SECEXIT=SXNSECUR with verify (default) Interactions run with the provided credentials, which are validated with the operating system's security product.

c. SECEXIT=SXNSECID with Identify Interactions run with the credentials provided; however, the user ID provided must be a surrogate of the user ID used to start the CICS socket listener. The password is not checked in this case but may not be blank.



CICS Adapter Mode Interaction

The CICS Adapter Mode Interaction activity emulates the functionality of the legacy CICS Adapter: it performs essentially the same functions as did the CICS Adapter, but without the adapter messaging infrastructure being used. The CICS Adapter included its own copybook parsing and rendering capabilities, which are replaced with those of the ActiveMatrix BusinessWorks Data Conversion Plug-in. The following tables describe the fields available on the CICS Adapter Mode Interaction palette object.


Table 6 Fields Under Configuration Tab: CICS Adapter Mode Interaction


Name N The name of the Region resource.

Default: CICS Program Call

Description N Optional free-form description

Region Y A link to the region object to be used for this interaction.

Program Name Y The name of the CICS program to be invoked.

Return Commarea N A flag that enables the return of data via the output commarea of the program being invoked. If this flag is not enabled, no data will be returned.

Default: enabled

Program Call Timeout

Y The number of seconds that the activity will wait for the CICS system to return from the called program.



CICS Adapter Mode Interaction | 11

Trace Level Y This selection provides a list of trace message verbosity which starts at "OFF" for no trace information to "INFO", which represents the maximum verbosity. Messages enabled by this feature are also printed in the debug and tracing queues in CICS.

The trace level general descriptions:

• OFF No messages.

This is the default.

• ERROR Trace messages will be printed for conditions that cause an error. Generally, the error object produced will contain the same information as the trace message.

• WARN Error messages plus messages related to the management of the connection pool, and so on.

• INFO Prints all above messages plus detailed descriptions and hex dumps of data read and written to the network. This setting generates sufficient output to swamp a production ActiveMatrix BusinessWorks instance in logging activities and should be used with care.

Trace File Name Y The name of the file to which trace records will be written. If no file is provided, or the file fails to open for any reason, trace records will be written to the ActiveMatrix BusinessWorks instances stdout stream.

Note that on systems that enforce exclusive file locks (such as Windows), when the trace file is opened with an editor that requires exclusive access to the file, either the editor may not be able to open the file (if it is already open) or, once opened, the activity will not be able to write to it.

Table 6 Fields Under Configuration Tab: CICS Adapter Mode Interaction




Input TabIn general, the output of the Render Copybook Data activity is mapped onto the bytes field of the CICS Adapter Mode Interaction's input object. However, any mechanism which provides a binary representation of a commarea suitable for use by the CICS program is acceptable (though difficult to manage). Render Copybook Data activity is provided by TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion.

The input mapping also provides the USERID and PASSWORD fields so that the user used to run the interaction can be overridden at run time.

Output TabThe output schema provides only the bytes returned by the commarea based program. These bytes may be used as is, but they are usually mapped as input to the activity Parse Copybook Data.

If the Return Commarea option was not selected, there will be no output data at all.

Error Output TabErrors produced by this activity will throw an exception of the type CicsPiException.

Override will not occur if connection pooling is in effect and the userid acquired at run time does not match the Region resource's userid.


CICS Interaction | 13

CICS Interaction

The CICS Interaction activity represents a modern approach to running CICS programs: all the functionality available in the Adapter Mode Interaction is available here, in addition to the ability to use CICS Containers as input and output from the program, the ability to route the request between CICS regions for execution, and much more. The following tables describe the fields available on the CICS Interaction.


Table 7 Fields Under Configuration Tab: CICS Interaction Activity



Default: CICS Interaction

Description N Optional free-form description.

Region Y A link to the CICS Region shared resource to be used for this interaction.

Program Name Y The name of the CICS program to be invoked.



Userid Y Userid and password can be provided as follows:

• If userid is not provided, the program is run with the security credentials of the Region shared resource.

• If both the userid and password are provided, and the region resource does not indicate a pooled connection, CICS will check that the userid has access to the program and will then run the program under the provided userid's security credentials.

• In both cases, the normal overrides for credentials are in place:

— For Pooled connections, the credentials on the region resource are used.

— For unpooled connections the credentials are taken first from the activity's input, then from the activity's parameters and then from the region resource.

This field is only available for interactions using non-pooled connections.

Password Y Password for the above userid. This field is only available for interactions using non-pooled connections.

Transaction Id

Y This optional field can hold a custom transaction identifier for resource accounting purposes. When a custom SXNE is entered here, the activity runs the copy of the SXNE instead of the original.

To use a custom transaction ID you must arrange for the CICS administrator to create a copy of the default SXNE transaction provided with the product. For information about copying a transaction, see the IBM documentation provided for the CEDA transaction in CICS. Note that you may also override this transaction ID on the input schema.

This feature cannot be used with pooled connections.

Interaction Timeout

Y The number of seconds that the activity will wait for the CICS system to return from the called program. Zero disables the timeout, which means that interactions will wait forever for the CICS system to return. A blank value implements the 60 second default.






Dedicated Threads

Y The number of threads dedicated to the interactions with CICS.

Because interactions with CICS can involve a lot of latency, they can have a detrimental impact on the execution of other processes in the ActiveMatrix BusinessWorks thread pool. To prevent other threads from idling while CICS interactions are running, enter the number of long running threads which are to be dedicated to CICS interactions.

Note that the thread pool is named after the interaction where it is specified. Specifying a Dedicated Threads limit on several identically named interactions resultes in shared threads.

Default: 0 (blank or zero disables the feature)Range: 0-1024

Response Type

N The response type is as follows:

• Return data area Returns the output of the program.

This is default.

• Return nothing Calls the program and does not wait for a result code. This is completely asynchronous.

• Return code only Calls the program and return the program call return code. This ensures that the activity finds out about abnormal events in the call but does not return any data.





Data Communication Type

N Data communication type can be as follows:

• Commarea This is the default and means that the program is a commarea program and will use a commarea for input and output. The default commarea size is 32500 bytes.

• Variable Length Commarea This option provides the ability to run a CICS program using a commarea of a specific size, as well as to transfer an arbitrary subsection of the resultant commarea back to the activity. This option enables two additional fields:

a. Commarea Size N

Provide the size, in bytes, of the commarea to be used by the program. This size must be sufficient to hold the input data as well as any data that the program will write.

b. Commarea Offset N

Provide a zero-based offset into the commarea returned by the program. This value is used as the starting position when copying the commarea data back to the activity. The number of bytes specified in the Return Area Size field is copied from this offset. An error is returned to the activity is any overrun is detected.

• Container This means that the input and output to the program is provided by named containers. You must know what the program expects its containers to be named. If this option is selected it enables the fields Output Container and Input Container:

a. Channel Name Y

The optional name of the CICS Channel object which will contain the input containers for this program execution. This is only required to support programs which explicitly open a named channel rather than use the default.

b. Input Container Y

The Input Container name to be used for this transaction. It can be 1 to 16 chars long.

c. Output Container Y

The Output Container name to be used for this transaction. It can be 1 to 16 chars long.





Return Area Size

N Regardless of the input output type, this is the number of bytes returned from the programs output area.

If a program produces 20K of data but you are only interested in the first 100 bytes, you can elect to receive only the first 100 bytes to conserve network resources.

If this parameter is used to limit the size of the data area returned from an activity, it must be done in such a way that any subsequent DCP parse activity has enough data so satisfy the requirements of its schema. Therefore, if you truncate the data, be sure to adjust the schema's requirements to match.

Note that a size of zero effectively disables this parameter. Commarea interactions will use the maximum commarea size (32500), and container interactions will use actual sizes for containers.

Default: 32500Range: commarea 0-32500

container 0-4m





Trace Level N This selection provides a list of trace message verbosity, which starts at "OFF" for no trace information to "DEBUG" that represents the maximum verbosity. Messages enabled by this feature are also printed in the debug and tracing queues in CICS. The trace level general descriptions:

• OFF There are no messages.




• INFO Prints all above messages plus detailed descriptions and hex dumps of data read and written to the network.

• DEBUG Prints all above messages plus many engineering-specific messages related to the internal workings of the CICS resident interface programs. This option also enables the printing of messages to the CICS log.

Both the INFO and DEBUG setting generate sufficient output to swamp a production ActiveMatrix BusinessWorks instance in logging activities and should be used with care.

Trace File Name

Y The name of the file to which trace records will be written. If no file is provided, or the file fails to open for any reason, trace records will be written to the ActiveMatrix BusinessWorks instances stdout stream.

Note that on systems that enforce exclusive file locks (such as Windows), when the trace file is opened with an editor that requires exclusive access to the file, either the editor may not be able to open the file (if it is already open) or, once opened, the activity may not be able to write to it.





Advanced TabTable 8 lists and describes the fields under the Advanced tab.

Region Status button

N This button queries the configured CICS region for the status of the network interface program listening there. It produces a text box which identifies:

• The name, version and compile date of the interface program

• Configuration information for the CICS region

• Operating system level information.



Table 8 Fields Under Advanced Tab: CICS Interaction Resource


CICS Resource Commit Point

N Options are:

• Auto The CICS interaction interface program automatically commits CICS resources at the completion of the program call.

This is default.

• User It is expected that the called program will explicitly commit CICS resource changes if it is necessary to do so.

DB2 Transaction Id

Y Optionally, provide a transaction identifier to be used by programs accessing DB2 by way of plans that have a specific transaction ID bound into them.

Enable CICS Remote Routing

N Enables the CICS routing options.

If checked, the following three rows become available: Remote CICS System ID, Remote CICS Transaction, and Sync On Return.

Default: disabled



Input TabThe input tab contains an XML document node called InteractionInput. The present fields make it possible to programmatically override the activity's defaults by mapping values from a previous activity's output.

The Input tab contains the following fields:

Remote CICS System ID

Y A four character system identifier for the CICS region where the program will ultimately be run.

Uses alpha-numeric characters only.

Remote CICS Transaction

Y A four character transaction identifier responsible for running the program on the remote CICS system.


Sync On Return Y Automatically commit CICS resources on the remote CICS system when the program returns. If not selected, the remote CICS program cannot issue a CICS SYNC or a CICS ROLLBACK.

Default: disabled

Table 8 Fields Under Advanced Tab: CICS Interaction Resource


Table 9 Fields Under Input Tab: CICS Interaction Resource


InteractionInput

USERID Y Override the userid for this interaction. This field is only available for interactions using non-pooled connections.

PASSWORD Y Override the password for this interaction. This field is only available for interactions using non-pooled connections.



TRACE-LEVEL Y Override the trace level in cases where tracing is desired only for specific interactions. This enables the process designer to obtain detailed trace records without the overhead of tracing all interactions. The input value must be added in upper case characters.


TRANID Y This optional field can hold or override a custom transaction identifier that is used to account for application resources for each transaction. This identifier becomes the transaction on whose behalf the connection to CICS is made and under which all Plug-in interactions on this CICS region or regions are run.



TRACE-FILE Y The file to which trace records will be written. The ActiveMatrix BusinessWorks instance's stdout stream will be used if no file is provided or available.


MROTRAN Y Override the four character transaction identifier responsible for running the program on the remote CICS system.


MROSYNC Y Override the Boolean. Indicates whether the CICS LINK is done with or without SYNCONRETURN parameter. The valid input is the words TRUE or FALSE.

MROSYS Y Override the four character system identifier for the CICS region where the program will ultimately be run.






Output TabTable 10 lists and describes the fields under the Output tab, which provide the results of the CICS Interaction for a commarea or a container.

Error Output TabErrors encountered at any stage of the CICS Interaction will cause an exception of type CicsPiException to be thrown.

bytes N The input to the activity, normally mapped from a previous activity Render Copybook Activity provided by TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion.



Table 10 Fields Under Output Tab: CICS Interaction Resource

Field Description

InteractionOutput

bytes The body of the commarea or container is returned.

responsetimemillisec

Provides the number of milliseconds that the CICS interaction took for performance monitoring reasons.


CICS Container Interaction | 23

CICS Container Interaction

The CICS Container Interaction activity functions much like the CICS Interaction activity using containers with the exception that there may be any number of input and output containers. The containers are described and mapped on the input and output schema tabs rather than in fields on the activity's configuration panel. The output of the activity will contain a container segment for every container created by the program as well as those which were used as input (unless the input only indication was used).

Configuration TabTable 11 lists and describes the fields under the Configuration tab.

Table 11 Fields Under Configuration Tab: CICS Container Interaction Activity

Filed Global Variable Description


Default: CICS Container Interaction

Description N Optional free-form description.

Region Y A link to the CICS Region shared resource to be used for this interaction.

Program Name

Y The name of the CICS program to be invoked.



Userid Y Userid and password can be provided as follows:

• If userid is not provided, the program is run with the security credentials of the Region shared resource.

• If only userid is provided, CICS will check to ensure that this userid has access to the named program, and if it does, the program will be run under the security credentials of the region shared resource.

• If both the userid and password are provided, CICS will check that the userid has access to the program and will then run the program under the provided userid's security credentials.

• In all cases, the normal overrides for credentials are in place:

— For Pooled connections, the credentials on the region resource are used.

— For unpooled connections the credentials are taken first from the activity's input, then from the activity's parameters and then from the region resource.


Password Y Password for the above userid. This field is only available for interactions using non-pooled connections.

Transaction Id

Y If this field is enabled (and you are not using a pooled connection), you may enter an optional custom transaction identifier for resource accounting purposes.

To use a custom transaction ID you must arrange for the CICS administrator to create a copy of the default SXNE transaction provided with the product. For information about copying a transaction see the IBM documentation provided for the CEDA transaction in CICS. Note that you may also override this transaction ID on the input schema.






Interaction Timeout

Y The number of seconds that the activity will wait for the CICS system to return from the called program. Zero disables the timeout, which means that interactions will wait forever for the CICS system to return. A blank value implements the 60 second default.


Dedicated Threads

Y The number of threads dedicated to the interactions with CICS.

Because interactions with CICS can involve a lot of latency, they can have a detrimental impact on the execution of other processes in the ActiveMatrix BusinessWorks thread pool. To prevent other threads from idling while CICS interactions are running, enter the number of long running threads which are to be dedicated to CICS interactions.

Note that the thread pool is named after the interaction where it is specified. Specifying a Dedicated Threads limit on several identically named interactions resultes in shared threads.

Default: 0 (blank or zero disables the feature)Range: 0-1024

CICS Resource Commit Point

N The options are:

• Auto The CICS interaction interface program automatically commits CICS resources at the completion of the program call.


• User It is expected that the called program will explicitly commit CICS resource changes if it is necessary to do so.

DB2 Transaction Id

Y Optionally, provide a transaction identifier to be used by programs accessing DB2 by way of plans that have a specific transaction ID bound into them.

Enable CICS Remote Routing

N Enables the CICS routing options.

If checked, the following three rows become available: Remote CICS System ID, Remote CICS Transaction, and Sync On Return.

Default: disabled





Remote CICS System ID

Y A four character system identifier for the CICS region where the program will ultimately be run.


Remote CICS Transaction

Y A four character transaction identifier responsible for running the program on the remote CICS system.


Sync On Return

Y Automatically commit CICS resources on the remote CICS system when the program returns. If not selected, the remote CICS program cannot issue a CICS SYNC or a CICS ROLLBACK.

Default: disabled

Trace Level N This selection provides a list of trace message verbosity, which starts at "OFF" for no trace information to "DEBUG" that represents the maximum verbosity. Messages enabled by this feature are also printed in the debug and tracing queues in CICS. The trace level general descriptions:

• OFF There are no messages




• INFO Prints all above messages plus detailed descriptions and hex dumps of data read and written to the network.

• DEBUG Prints all above messages plus many engineering-specific messages related to the internal workings of the CICS resident interface programs. This option also enables the printing of messages to the CICS log.

Both the INFO and DEBUG setting generate sufficient output to swamp a production ActiveMatrix BusinessWorks instance in logging activities and should be used with care.





Input TabTable 12 lists and describes the fields under the Input tab.

Trace File Name

Y The name of the file to which trace records will be written. If no file is provided, or the file fails to open for any reason, trace records will be written to the ActiveMatrix BusinessWorks instances stdout stream. The output goes to the applications log file.

Note that on systems that enforce exclusive file locks (such as Windows), when the trace file is opened with an editor that requires exclusive access to the file, either the editor may not be able to open the file (if it is already open) or, once opened, the activity will not be able to write to it.

Region Status button

N This button queries the configured CICS region for the status of the network interface program listening there. It produces a text box which identifies:

• The name, version and compile date of the interface program

• Configuration information for the CICS region

• Operating system level information.



Table 12 Fields Under Input Tab: CICS Container Interaction Activity


InteractionInput

USERID Y Override the userid for this interaction. This field is only available for interactions using non-pooled connections.

PASSWORD Y Override the password for this interaction. This field is only available for interactions using non-pooled connections.



TRANID Y This optional field can hold or override a custom transaction identifier that is used to account for application resources for each transaction. This identifier becomes the transaction on whose behalf the connection to CICS is made and under which all Plug-in interactions on this CICS region or regions are run.



TRACE-LEVEL Y Override the trace level in cases where tracing is desired only for specific interactions. This enables the process designer to obtain detailed trace records without the overhead of tracing all interactions. The input values must be in all upper case characters.


TRACE-FILE Y The file to which trace records will be written. The ActiveMatrix BusinessWorks instance's stdout stream will be used if no file is provided, or the file is not available.


MROTRAN Y Override the four character transaction identifier responsible for running the program on the remote CICS system.


MROSYS Y Override the four character system identifier for the CICS region where the program will ultimately be run.


MROSYNC Y Override the Boolean. Indicates whether the CICS LINK is done with or without SYNCONRETURN parameter.

The valid input are the words TRUE or FALSE.





Output TabTable 13 lists and describes the fields under the Output tab.

ChannelName Y Optionally, enter the name of the CICS Channel object which will contain the input containers for this program execution. This is only required to support programs which explicitly open a named channel rather than use the default.

InputContainer

This node represents a container object to be sent as input to the called program. For programs that require or accept multiple containers as input, simply duplicate the provided node as many times as is necessary and map the fields appropriately.

InputOnly N Indicates that this container is not to be returned to the activity. It is input only. Containers that are not changed by the program need not be returned by the interface. Setting this option to '1' will save network resources.

Default: 0 Range: 0/1

ContainerName Y A required one to 16 character name for the container. Most programs require specific named containers for input.

bytes N Map the data that will be used to represent the body of the container. This will usually be the output of the Render Copybook Data activity, but any mechanism which provides valid input is permitted.



Table 13 Fields Under Output Tab: CICS Container Interaction Activity

Field Description

InteractionOutput



Error Output TabErrors encountered at any stage of the CICS Interaction will cause an exception of type CicsPiException to be thrown.

OutputContainer This node represents an output container produced by the activity. Unless input containers had their "Input Only" values set to '1', they will be duplicated here.

• ContainerName The name given to the container by the program.

• bytes The body of the container

responsetimemillisec

Provides the number of milliseconds that the CICS interaction took for performance monitoring reasons.

Table 13 Fields Under Output Tab: CICS Container Interaction Activity

Field Description


Pool Manager | 31

Pool Manager

The Pool Manager activity provides information about the internal state of the connection pool, as well as some usage statistics. It is also possible to terminate existing pooled connections by providing the name of the pool and the ID of the connection to terminate.

If the Pool Manager runs before any pooled connections are instantiated, a document containing only the topmost node will be returned.

The ActiveMatrix BusinessWorks Plugin for CICS's connection pool is slightly different from most pooling mechanisms. The remote end of the connection, in this case the CICS socket listener program, is managed by the CICS administrator and will terminate idle connections once they exceed thresholds established by the CICS administrator. This means that the ActiveMatrix BusinessWorks activity could obtain a pooled connection that has been closed since it was last used. In this case, the connection is simply re-established incurring a small overhead.

From the performance tuning point of view, this connection pool provides throughput improvements only so long as connections do not remain idle for long periods of time. The time period in question will be the shorter of the maximum connection lifetime established by the CICS administrator, or the pool's max lifetime parameter.

When sizing the connection pool, ask the CICS administrator how many connections he will permit the socket listener to instantiate at any given time. Then divide that number by the number of machines your application will be deployed on since each deployment uses its own instance of the pool. Exceeding the limits established by the CICS administrator will result in activities getting errors when acquiring a connection.



Configuration TabTable 14 lists and describes the fields under the Configuration tab.

Input TabTable 15 lists and describes the fields for Input (root node).

Table 14 Fields Under Configuration Tab: Pool Manager Activity


Name N A name for this activity.

Default: CICS Connection Pool Manager

Description N Description of the activity.

Table 15 Fields Under Input Tab: Pool Manager Activity


ConnectionPool A node representing a region's connections. If there is any question about what to use for input, simply run the activity with no input and refer to the activities output for reference.

regionresource N The URL name of the region resource. The named region node is the subject of the KillConnection and SetActiveHost commands. It does not limit the report to connections in this node. Each invocation of the ConnectionPool activity reports the status of all connections in all pools.

Example: /Regions/AbcPooled.cicspi

KillConnection N A string representation of the connection number to terminate, or an '*' to terminate all connections in the pool.

SetActiveHost N Specify a host and port for the Poolmanager to use.

For region resources defined to represent a group of CICS regions which are all similarly configured, you can explicitly tell the Poolmanager to change to another host:port. This provides a highly available application deployment.

Enter the region name in the regionresource field and the URL of the CICS region to connect to in the SetActiveHost field and run the pool manager interaction.


Pool Manager | 33

Output TabTable 16 lists and describes the fields for the Output tab. It provides an xml document describing the current state of all connection pools for the ActiveMatrix BusinessWorks instance on which the activity runs. The root node is "PoolmanagerOut" and has a single repeating child.ConnectionPool:

Error Output TabIf an error is encountered, for example if no pooled sessions exist, an exception of type CicsPiException will be thrown.

Table 16 Fields Under Output Tab: Pool Manager Activity

Field Description

ConnectionPool

regionresource The URL name of the region resource.

Example: /Regions/AbcPooled.cicspi

ActiveHost If the region represents a set of hosts for redundancy purposes, the currently active host URL is displayed. If there is only one host on the Region Resource, this field is empty.

PoolSize The number of connections this pool is configured to create.

PoolmanagerRequests

The number of requests for a connection made to this pool since its instantiation.

PoolmanagerWait The number of requests which were required to wait because all connections in the pool were occupied.

PoolmanagerTimeout

The number of requests which were timed out while waiting for a connection.

Connection Statistics for each individual connection

ConnectionID The numerical number of the connection. This is the number to enter in the input tab's KillConnection field to have this connection terminated.

ConnectionRequested

The number of times this connection has been used.

ConnectionClosed The number of times this connection was requested only to find that the associated CICS sockets listener had hung up due to its own timeout. In these cases the connection is simply reestablished.


| 35

Chapter 3 Sample ActiveMatrix BusinessWorks Projects

This appendix describes the sample ActiveMatrix BusinessWorks project included in the Plug-in.

Topics

• Downloading the Sample Project, page 36

• Using the Sample Project, page 37


36 | Chapter 3 Sample ActiveMatrix BusinessWorks Projects

Downloading the Sample Project

The Plug-in contains a sample ActiveMatrix BusinessWorks project, which is located in the directory TIBCO_HOME\bw\plugins\bwcp\samples\bwCicsSample.zip.

To open the sample project in TIBCO Designer, do the following:

1. Copy the file bwCicsSample.zip to the directory TIBCO_HOME\bw\plugins\bwcp\samples.

2. Unzip the file.

3. Start TIBCO Designer and click Open existing project.

4. In the Project Directory file chooser, navigate to TIBCO_HOME\bw\plugins\bwcp\samples\bwCicsSample\BWCPSample.

5. Click OK.

The sample project is displayed in Figure 1.

Figure 1 ActiveMatrix BusinessWorks Project


Using the Sample Project | 37

Using the Sample Project

The sample project contains three application folders:• Activities These are processes meant to demonstrate the features of the

Plug-in. Available activities in this sample are: Cics Adapter Legacy Invocation of IVP, IVP Using Commarea, IVP Using Containers, and IVP Using Multiple Containers

• AESchemas This is folder that was created by default for TIBCO Designer project and is used for adapter schema resources.

• CopyBookSchemas These are the schemas generated from having parsed the copybooks for the sample programs. This sample contains one copybook schema: SXGCCI01.cpy

• Shared Resources This folder contains definitions for CICS regions. You will have to modify these to suit your environment. These available shared resources in this sample are: Region, and RegionPooled.

ActivitiesThe Activities folder contains these activities:

CICS Adapter Legacy Invocation of IVP

This activity is intended for use in situations where only the software TIBCO Adapter for CICS is installed on the host. TIBCO ActiveMatrix BusinessWorks Plug-in for CICS can operate in compatibility mode with this software, however only the features supported by the TIBCO Adapter for CICS will be available.

If the region resource for this activity is correctly configured, the CICS Adapter Legacy Invocation of IVP should run in the tester.

IVP Using Commarea

This activity is essentially the same as Cics Adapter Legacy Invocation of IVP, except that it uses the new host interface in the CICS region to run a simple commarea-based program. If the region resource is correctly configured, this activity should run in the tester. You can experiment with modifying the contents of the input in order the render process to alter the input to the program.

IVP Using Containers

This activity runs a program that takes its input in the form of a CICS container instead of a commarea. The program (SXCCI014) accepts a single container as input and returns the same container for output. The container name must be SXCCI014 in both cases.


38 | Chapter 3 Sample ActiveMatrix BusinessWorks Projects

IVP Using Multiple Containers

This activity runs a program that takes its input in the form of a group of CICS containers.

Each input container requires a name and a body. The name is a 1-16 character name, and the body is a 1 - 4M data area.

Containers can be used for input and output by a program and, therefore, all input containers are returned from the program after execution. If you know that a particular container is not altered by the program, you can indicate on the input schema that it is input only and it will not be returned. This way, you will conserve network resources.

The program provided for this activity is SXCCIO034. It accepts one container (SXCCIO034-INPUT) as input, and provides one or more containers as output.

The output containers will be named SXCCIO034-OUTPUT or SXCCIO034-xx, where xx is the number of the container. The number of containers returned is controlled by the input parameter in the field: IVP-WRITES (check the render activity's input tab).

Shared ResourcesThe Shared Resources folder contains two resources: one for a non-pooled connection to the CICS region, and one for pooled connections. For both regions, modify the host name and port values to match the CICS system which you intend to use.

There are two diagnostic buttons on the region resource panels: one that ensures that the port is open on the selected host, and one that actually runs a sample diagnostic transaction on that system. Use them to validate your configuration and to verify that the TCP/IP listener is operating correctly in the CICS region.

Creating an ActiveMatrix BusinessWorks EAR

It is critical that you manually add the CICS Region definitions to the Shared Archive under the Resource tab.

The Validate Project before Deployment option will not reveal if this resource is missing, and your ActiveMatrix BusinessWorks processes will deploy with errors.

The input and output for this activity is not configured on the configuration panel, but instead in the input schema for the activity.


| 39

Chapter 4 Security Modes for z/OS Components

This chapter explains the security modes for the Plug-in components on z/OS.

Topics

• Security Modes, page 40

• Current Plug-in Security, page 42


40 | Chapter 4 Security Modes for z/OS Components

Security Modes

There are several security modes in which the Plug-in can run:

Unsecured ModeThe characteristics of the Unsecured mode are as follows:

• The CICS region has been started with SEC=NO in the SIT.

• Userid and password specified in the Plug-in are not used in the CICS region. They can be present in ActiveMatrix BusinessWorks activities and sent to the CICS region but are not used.

• The security exit in the Sockets Setup is blank.

• If the unmodified SXNASEXT Security Exit is used, then it will return an error since the CICS region is not installed and the IBM Listener will return an error. The CICS User program will not be executed. It is strongly advised to use the new SXNSECUR Security Exit, which is designed to work with SEC=NO or SEC=YES and both plain and encrypted USERID/PASSWORD from the Plug-in.

• All SXNE transactions run with the Userid that started Socket Listener thru the EZAO transaction, PLT start or Userid on Listener Configuration Setup (field USERID).

• The listener accepts on bind requests and starts the child listener SXNENTER for all initial messages that are sent in.

• In ActiveMatrix BusinessWorks activities, Userid and password are optional and not used in the CICS region.

• The password is encrypted

Verify ModeThe characteristics of the Verify mode are as follows:

• The CICS region has been started with SEC=YES, XTRAN=YES and XPCT=YES in the SIT.

• In ActiveMatrix BusinessWorks activities, both the USERID and PASSWORD are required.

• The USERID and PASSWORD are used in the CICS region.


Security Modes | 41

• Both the user ID and password are encrypted. TIBCO program SXNSECUR security routine can handle both the encrypted and Clear Text User ID and password.

• The security exit in Sockets Setup is SXNSECUR. The TIBCO COBOL Security routine SXNSECUR provided by TIBCO runs in the Verify mode.

• The IBM Listener calls SXNSECUR with USERID and PASSWORD. SXNSECUR decrypts and verifies both the USERID and PASSWORD, and allows the transaction to continue only if the External Security System (usually RACF) indicates that the two parameters match.

• All SXNE transactions run with the USERID and security of the USERID for the Plug-in.

• The Userid value for TIBCO ActiveMatrix BusinessWorks Plug-in for CICS must be a SURROGATE of the userid that CSKL is running under. The CSKL transaction must be allowed to start transaction SXNE or SXNT with the USERID for the Plug-in.

Identify ModeThe characteristics of the Identify mode are as follows:

• The the CICS region is started with SEC=YES, XTRAN=YES and XPCT=YES in the SIT.

• In the Plug-in activities, the Userid is required while the password is optional.

• The USERID and PASSWORD are encrypted.

• The USERID is used in the CICS region while the password is not used.

• The security exit in Sockets Setup is SXNSECUR (TIBCO COBOL exit is modified to identify only).

See <userhlq>COB(SXNSECUR) on how to change this routine to Identify Mode.

• IBM Listener calls SXNSECUR with USERID and PASSWORD. SXNSECUR sets the SXNE transaction to run under the USERID for the Plug-in.

• All SXNE transactions run with the userid and security of the USERID for the Plug-in.

• The USERID value for the Plug-in must be a SURROGATE of the Userid that CSKL is running under. The CSKL transaction must be allowed to start the transaction SXNE or SXNT with the Userid for the Plug-in.



Current Plug-in Security

Security is currently used depending on the way the Plug-in runs.

Running in POOL or NON-POOL Mode

Pool Mode

When the BusinessWorks Plug-in is communicating in Pool mode, only the USERID and PASSWORD from the Region Definition are used. The USERID and PASSWORD from CICS Interaction (if present) are ignored. This means that all transactions using the pooled session will have the same security credentials.

SECEXIT in CICS can be set up as follows:

• CICS with SEC=NO on the SIT

— Both the USERID and PASSWORD are ignored.

— The SXNx transaction runs under the USERID of CSKL.

• CICS with SEC=YES on the SIT

— No SECEXIT is set

The USERID and PASSWORD from the Plug-in are ignored.

The SXNx transaction runs under the USERID of CSKL.

— SECEXIT=SXNSECUR with the security mode Verify (default)

The USERID and PASSWORD are tested with RACF for validity.

The SXNx transaction runs under the USERID of the Plug-in.

— SECEXIT=SXNSECUR with the security mode Identify

No RACF call


Userid of the Plug-in must be a surrogate of Userid of CSKL.


Current Plug-in Security | 43

Non-Pool Mode

In the Non-Pool mode, the Plug-in security depends on the following:

• Use of the USERID and PASSWORD

— If the activity CICS Interaction in the Plug-in has a mapping to the Userid and password on the Input tab, then the mapping fields are used.

— If the Plug-in CICS Interaction activity has a static Userid and password on the Configuration Tab, then the Configuration fields are used

— Else, the fields on the CICS Region Definition are used

• Setup of SECEXIT in CICS

a. CICS with SEC=NO

The USERID and PASSWORD are ignored.


b. CICS with SEC=YES

— No SECEXIT

The USERID and PASSWORD are ignored.


— SECEXIT=SXNSECUR with the security mode Verify (default)

The USERID and PASSWORD are is tested with RACF for validity.


USERID of the Plug-in must be a surrogate of USERID of CSKL.

— SECEXIT=SXNSECUR with the security mode Identify

No RACF call


USERID of the Plug-in must be a surrogate of USERID of CSKL.


| 45

Appendix A Transport Layer Security

Application Transparent Transport Layer Security (AT-TLS) provides a mechanism for securing the connection between the Plug-in’s application engine and the CICS regions to which it connects. This appendix provides a brief description of what it is and how to configure the mechanism.

This is not intended to replace any of the AT-TLS documentation, but only to provide the project developer with enough information to communicate properly with their mainframe administrators.

Topics

• RACF Configuration, page 46

• BWCP Project Configuration, page 51


46 | Appendix A Transport Layer Security

RACF Configuration

This procedure requires the assistance of your RACF and Networking administrators. The two main components in this part of the configuration are a Personal Certificate and the AT-TLS rules that control which ports are to be secured.

Personal CertificateIn order to configure RACF, you must have a personal certificate and the userid which starts the CICS region must have read access to this certificate.

The personal certificate should be created by your RACF administrator create a personal certificate, using RACF commands similar to those shown in the example below. Note that the exact requirements will depend on your system version, configuration, and site standards.

Example

The following JCL illustrates the requirements for one possible configuration. In this example, the certificate named BWCP_Server_Cert is the personal certificate that is used to secure the connection. It has been exported with its private key included as a P12 file.

The signing certificate, TIBCO Software Inc CA is exported as a DER-formatted certificate without its private key because it is not needed. There is no need to expose the signing certificate outside of RACF.

This sample sets up the keyring, generates the certificates, and exports the certificates for downloading to the client:

//#JOBNAME JOB (&SYSUID),'CERT CREATE',CLASS=A//GENCERT EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSTSIN DD *RACDCERT GENCERT CERTAUTH - SUBJECTSDN( - OU('TIBCO Software Inc CA') - CN('TIBCO Software Inc Mainframe Server Root CA') -

Much of this will be completely familiar to your RACF administrator and he/she will have to customize this approach to your local situation. For instance, it is very likely that you already have a CA with which to sign the personal certificate, making that part of the job unnecessary. Also, you will want names that make sense to your organization.


RACF Configuration | 47

O('TIBCO Software Inc.') - L('Palo Alto') - SP('CA') - C('US') ) - SIZE(2048) - NOTAFTER( DATE(2030-02-04) TIME(23:59:59) ) - WITHLABEL('TIBCO Software Inc CA') - KEYUSAGE(CERTSIGN HANDSHAKE DATAENCRYPT DOCSIGN) RACDCERT ID(TCPIP) GENCERT - This id may be an id you use to own all of your application certs if you choose SUBJECTSDN( - OU('BWCP_Server_Cert') - O('TIBCO Software Inc.') - L('Palo Alto') - SP('CA') - C('US') ) - SIZE(4096) - See IBM RACDCERT GENCERT doc on this. Allowed maximum values: 512, 1024, 2048, 4096 NOTAFTER( DATE(2030-02-04) TIME(15:50:00) ) - WITHLABEL('BWCP_Server_Cert') - SIGNWITH(CERTAUTH LABEL('TIBCO Software Inc CA')) - Use this as the LABEL in subsequent CONNECT and EXPORT commandsKEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN) RACDCERT ID(TIBUSER) ADDRING(Personal_TIBUSER) RACDCERT CONNECT(CERTAUTH LABEL('TIBCO Software Inc CA') -RING(Personal_TIBUSER) USAGE(CERTAUTH)) ID(TIBUSER) RACDCERT CONNECT(ID(TIBUSER) LABEL('BWCP_Server_Cert') + RING(Personal_TIBUSER) DEFAULT) ID(TIBUSER) SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

To export the certificate and the signing CA to datasets for transfer to the client://EXPORT EXEC PGM=IKJEFT01,COND=(2,LT) //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RACDCERT EXPORT(LABEL('BWCP_Server_Cert')) ID(TCPIP) - FORMAT(PKCS12DER) DSN('TIBUSER.BWCP.SERVER.CERT.DER') - PASSWORD('password') RACDCERT EXPORT(LABEL('TIBCO Software Inc CA')) CERTAUTH - FORMAT(CERTDER) DSN('TIBUSER.BWCP.CA.DER') /* //

AT-TLS Configuration with RulesOnce the personal certificate has been created, you must configure the z/OS TCP/IP stack's application transparent TLS feature to secure the connection.



AT-TLS can secure a single port or a range of ports using a single set of rules. As long as the use of a single certificate is acceptable for all connections to CICS regions on your z/OS system, you can allocate a range of ports and accomplish the whole task with one set of rules.

AT-TLS configuration is covered in the z/OS Communications Server bookshelf which even includes a configuration assistant to simplify the process.

With the assistance of your z/OS network administrator, you may customize the set of rules shown in the example below so that your port or ports are secured by the personal certificate created previously.

Example

This example shows a set of AT-TLS rules customized to configure ports for use with the personal certificate created in the Example on page 46. Your z/OS network administrator will be familiar with the documentation required to make the customizations needed for your system. Note that, in order to make the necessary customization, you must be aware of the keyring, label and personal certificate name stored in RACF.

TTLSGroupAction grp_Action { TTLSEnabled On Trace 2 # Log Errors to syslogd } # Common StartUp Group that new Rules may use # Shows how each connection maps to policy TTLSGroupAction grp_StartUp { TTLSEnabled On Trace 6 # Log Errors and Info messages to syslogd } # Common Diagnostic Group that a problem Rule may use # Shows AT-TLS events and result of each System SSL call TTLSGroupAction grp_Diagnostic { TTLSEnabled On Trace 255 # Log Error, Info, Event and Flow to syslogd } # Common Environment that most servers could use TTLSEnvironmentAction Generic_Server_Env { HandshakeRole Server TTLSKeyRingParms {

The Plug-in allows you to define several CICS regions in one region resource definition. If such a region definition uses AT-TLS to secure its connections, then all CICS regions must use the same certificate to secure their ports.


RACF Configuration | 49

Keyring Server_Ring } } ################################################################### # # # BWCP Specific Rules and Actions # # # ################################################################### # Server # ################################################################### TTLSRule BWCP_Server { LocalAddr ALL RemoteAddr ALL LocalPortRange 6810-6819 RemotePortRange 1024-65535 # Jobname (do not know, do not care) Direction Inbound Priority 255 TTLSGroupActionRef grp_Action TTLSEnvironmentActionRef BWCP_Env_Action_Server TTLSConnectionActionRef BWCP_Connection_Action_Server } # BWCP Environment TTLSEnvironmentAction BWCP_Env_Action_Server { HandshakeRole Server TTLSKeyringParms { # In this configuration (non-z/OS client), this cannot be a shared # keyring with a site certificiate. It must be a keyring and # certificate owned by the userid assigned to the application. # Keyring Personal_TIBUSER } } # BWCP Connections TTLSConnectionAction BWCP_Connection_Action_Server { HandshakeRole Server TTLSCipherParms { V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA } TTLSConnectionAdvancedParms { ApplicationControlled Off HandshakeTimeout 10 ResetCipherTimer 0 SecondaryMap Off } CtraceClearText Off



Trace 3 } ################################################################### # Client # ################################################################### TTLSRule OSB_Client { LocalAddr ALL RemoteAddr ALL LocalPortRange 6810-6819 RemotePortRange 1024-65535 # LocalPortRange 0 # any local port, we are not sure# RemotePortRange 0 # any remote port, we are not sure# Jobname (not applicable) Direction Outbound Priority 255 TTLSGroupActionRef grp_Action TTLSEnvironmentActionRef BWCP_Env_Action_Client TTLSConnectionActionRef BWCP_Connection_Action_Client } # BWCP Environment TTLSEnvironmentAction BWCP_Env_Action_Client { HandshakeRole Client TTLSKeyringParms { # In this configuration (non-z/OS client), this cannot be a shared # keyring with a site certificiate. It must be a keyring and # certificate owned by the userid assigned to the application. # Keyring Personal_TIBUSER } } # BWCP Connections TTLSConnectionAction BWCP_Connection_Action_Client { HandshakeRole Client TTLSCipherParms { V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA } TTLSConnectionAdvancedParms { ApplicationControlled Off HandshakeTimeout 10 ResetCipherTimer 0 SecondaryMap Off } CtraceClearText Off Trace 3 }


BWCP Project Configuration | 51

BWCP Project Configuration

Once the personal certificate has been created and the AT-TLS ports have been configured, you can configure a Plug-in project to create a secure connection to the CICS region.

Task A Obtain a copies of the certificates.

Move copies of the personal certificate and the signing CA previously exported to z/OS datasets to the local workstation.

1. Create copies of the certificates. For example, a batch job like the following transfers a pkcs12 encoded copy of the certificates created previously, along with all its signers, from RACF to sequential files:

//#JOBNAME JOB (&SYSUID),'CERT COPY',CLASS=A//* //STEP1 EXEC PGM=IKJEFT01,DYNAMNBR=20 //SYSTSPRT DD SYSOUT=O //SYSTSIN DD * RACDCERT EXPORT(LABEL('BWCP_Server_Cert')) ID(TCPIP) - FORMAT(PKCS12DER) DSN('TIBUSER.BWCP.SERVER.CERT.PCKS12') - PASSWORD('password') RACDCERT EXPORT(LABEL('TIBCO Software Inc CA')) CERTAUTH - FORMAT(CERTDER) DSN('TIBUSER.BWCP.CA.DER')/*

2. Transfer the copies from the z/OS system in binary format to your local workstation. You can use any mechanism you have available. For example, FTP:

ftp> binftp> get 'TIBUSER.BWCP.SERVER.CERT.PCKS12' server_cert.p12ftp> get 'TIBUSER.BWCP.CA.DER' server_ca.der

We now have the pkcs12 encoded RACF certificate (named server_cert.p12) and the CA it was signed with (encoded as a plain DER file named server_ca.der) in a workstation directory.

3. Once the transfer is complete, you should delete the z/OS copies of these sensitive files in order to minimize any security exposure related to having them outside RACF.

The descriptions given in this section apply to Linux and Windows workstations.



Task B Configure the Transport Layer Security panel

AT-TLS can now be configured using the Transport Layer Security panel on the designer:

1. Complete the fields in the Transport Layer Security panel:

— Client Identity File Specify the name and location of the RACF personal certificate. In the example for Task A, the local copy of this certificate was named server_cert.p12.

— Identity Password Specify the password used to extract the Client Identity File from RACF, as specified in the JCL from Task A.

— Server Cert Chain Specify the signing CA (or CA's). In the example for Task A, the local copy was named server_ca.der.

Click Select in order to select multiple signer certificates from a directory.

2. Click the Load Certificates button. This stores the certificate information in an encrypted format in the project's XML files.

3. Click the Test Connection button to verify that your configuration. See Common Problems below if you experience any problems with the connection.

Once you have loaded the certificates and verified that the connection can be created, the local copies of the certificates are not needed. You should permanently delete these files for security reasons.


BWCP Project Configuration | 53

4. Click Apply to save your configuration changes.

Common Problems• The connection fails silently. Check the designer log file to see if there are any

stack traces. If you see a trace item noting that the password was "null", it is likely that you forgot to press the Load Certificates button.

• If, when clicking Load Certificates, you receive a message that there is a error in the certificate or key file, it is most likely that the password is wrong. In this case, be particularly aware of any characters used in the password which may not translate reliably between the character set used on your z/OS system and the one running Designer.


| 55

Index

C

changes from the previous release viCics Adapter Legacy Invocation of IVP 37CICS Adapter Mode Interaction 10

Configuration tab 10Error Output tab 12Input tab 12Output tab 12

CICS Container Interaction 23Configuration tab 23Error Output tab 30Input tab 27Output tab 29

CICS Interaction 13Advanced tab 19, 19Configuration tab 13Error Output tab 22Input tab 20Output tab 22

CICS Region Resource 4Configuration tab 4Pooling tab 7

CICS Region security 8creating an ActiveMatrix BusinessWorks EAR 38current Plug-in security 42customer support xii

D

downloading the sample project 36

I

identify mode 41

IVP Using Commarea 37IVP Using Containers 37IVP Using Multiple Containers 38

N

non-pool mode 43

P

Pool Manager 31Configuration tab 32Error Output tab 33Input tab 32Output tab 33

pool mode 42product overview 2

R

running in POOL or NON-POOL mode 42

S

sample ActiveMatrix BusinessWorks project 35sample project

activities 37shared resources 38

securityz/OS components 39

security modes 40


56 | Index

support, contacting xii

T

technical support xiiTIBCO_HOME ix

U

unsecured mode 40using the sample project 37

V

verify mode 40

Z

z/OSsecurity 39


tibco activematrix businessworks plug-in for cics … · tibco activematrix businessworks plug-in...

Documents