Front cover

CICS Transaction Server V3R1 Channels and Containers Revealed
Converting a COMMAREA based application to use channels and containers Configuring systems, including sample application Simplifying process for code page conversion

Chris Rayns Pietro De Angelis Steve Burghard David Carey Scott Clee Peter Klein Erhard Woerner

ibm.com/redbooks

International Technical Support Organization CICS Transaction Server V3 R1 Channels and Containers Revealed September 2006

SG24-7227-00

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

First Edition (September 2006) This edition applies to Version 3, Release 1 of CICS Transaction Server for z/OS, product number 5655-M15, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.
© Copyright International Business Machines Corporation 2006. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

. . . . . . . . . . . .1 Communication area for data passing. . . . . . . 15 1. . . . . . .6 Migrating COMMAREA to channels and containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2. . . . . . 17 1. . . . . . . . . . . .3 Containers. 8 1. viii Preface . . . . . .1. . . . . . . . . . . . . vii Trademarks . 7 1. . . . . . . 5 1. . . . . . . . . . . . . . . . . . ix The team that wrote this IBM Redbook . . . . . . . . . . . . . . . . . . . . . . 23 2. . . . . . . . . . . . . . . . . . . . . . . .4 Creating a channel . . . . . . . . . 24 2. . . . . . . . . . . . . . . . . . . . . 20 Chapter 2. . . . . . . . . . . . . . . . . . . . . . . .2 Basic channel example . . . . . . . .4 Channels and business transaction services . . . . .4 Channels and containers concepts . . . . . . . . .6 Data conversion . 18 1. . . . . . . . . . . . . . . . . . . . . . . 26 2. . . . . . . . . . . . . . . . . . . . . . . .3 Overloaded COMMAREAs . .1. . . . . . . . . . . . . . . . . . . . . .1 Basic COMMAREA example. . . . . 30 2. . . . . . . . . . . .2 Flexible way to pass multiple pieces of data . . . . . . . . . . .4. . . . . . . . . . . . . . . .2.4 STARTBROWSE application programming interface . . . . . . . . . . . . 2006. . 19 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 2. . . . . . . . .1 Memory constraints . . . . . . . . . . .1 COMMAREA size limit . . . . . . .3 The evolution of the 32 KB COMMAREA . . . . . . . . . . . . . . . . . .4. . .2 Methods of passing COMMAREA data larger than 32 KB . . . ix Become a published author . . . . . . . 3 1. . . . . . . . . . . . . .5 Channels and CICS Java . . . .Contents Notices . . . . . . . . Introduction to channels and containers . . . . . . . . . . . . . . . . . . . . . 31 2. . . . . . . . . . . . . . . . . . . . . .1 General concepts . . .4. . . . . .5 Channels and containers in called subroutines. . . . . . . . . . . . .3 Channel name character set . . . . . . . . . . . . .3 COMMAREA constraints and alternate solutions . . . . . . . . xi Comments welcome. . .1 Container usage as a replacement to COMMAREAs . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. . . . . . 25 2. . . . . . . . . . iii . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2. . . . . . . . . . . . . . .2 Flexibility of the channels and containers approach . . . 16 1. . . . . . . . . . .2. . . . . . . .2 Channels . . . . . . . . . 10 1. Application design and implementation. . . . . 38 © Copyright IBM Corp. . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . .3. . . . .5 Benefits of using channels and containers . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . .2. . .2 Channel solution . . . . . . . . . . . . . . . . . 32 2.1. . . . . 6 1. . . . . . 9 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Chapter 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . . . . . . . .1 COMMAREA solution . . . . . . . . . 1 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All rights reserved. . . . . . . . . . .2 The requirement for change . . . . . . . . . . . . . . 33 2. . .4. . . . . . . .2. . . . . . . . . . . . . . . . . . . 3 1. . . . . . . . . . . . . . . 5 1. . . . . . . . . . . . . .

. . . . .5 Getting data from a container . . . . . . . .6. . . . . . . . . . . . 86 3. . . . . . . . . .2. . . . . . . . . . . . . . . .3 Migrating from COMMAREAs to channels . . . 39 2. . . . . . . . . .1 Application components . . . . . . . . . . .1 Creating channels and containers in JCICS . . . . . . . . . . . 72 3. . . . . .2. . .1 Data conversion with channels . . . . . . . .5 File example . . . . . . . . . . . . . . . . . . . . . 53 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. .1 COMMAREA . . . 88 iv CICS Transaction Server V3 R1 Channels and Containers Revealed . 73 3. .6. . . . . . .3 Passing a channel to another program or task . . . . . . . . 68 3. . . . . . . . . . . . . . . . . . . . . . . . . .1 . . . . . . . . . . . .4 Receiving the current channel. . . . 59 3. .2. . . . . . . . . . . . . . . . . . . . . . .2 Placing data in a container . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . .1 EXEC CICS application programming interface . . . . . . . . . .2 Channel. . . . . . 77 3.3 Passing a channel to another program or task . . . . . . . . . . . . . . . . . . . .2.4. . . .2 CICS Java . . . . . . . . . . . . .8 Dynamic routing application considerations . . . . . . . . . . . . . . . . . . 49 2. .3 Using containers to do code page conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Data conversion and code page conversion .2 Placing data in a container . . . . . . . . . . . . . . . . . . .3 APAR .3 Business transaction services . . . . . . . . . . . . . . . .9. . . . . . . . . . . . . . .6. . . . . . 60 3.4. . .4 Web services. . . . . .1. . . .3. . . . . . . . . .9. . . . 68 3. . . . . . . . . . . . . . . . . 62 3. . . . . . . .8. . . . . 70 3. . . . . . . . . . . . . . . . . . .PK15904 on CICS Transaction Server version 3. . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 3. . . . 47 2. . .8. . . 69 3. . . .6. . . . . . . . . . . .1 Designing a channel . . . . . . . . . . . . . . . . . . 70 3. . . . . . 63 3. . . . . 60 3. . . 45 2. . . .7 Storage . . . . . . . . . . . . . . . . . . 73 3. . 72 3. .1. .6. . . . .5 Getting data from a container . . . . .2. . . . . . . .2 How to cause CICS to convert data automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Code page considerations .7 Deleting a container . . . . . . . . 50 2. . . . . . . . 84 3. . . . . . . . 52 2. . . . . . . . . . . . . . . . . .4 Receiving the current channel. . . . . . . . . . 42 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . .2. . . . . . .1 . . . . . . . . . . . 44 2. . . . . . . . . . 86 3. . . . . . . . . . . . .4 SOAP example . . . . . . . . . . . . . . . . . . . . . . . . . .1. .1. . . . . . . . . . . . . . . . . . . . . 66 3. . . . . . . . . . . . . . . . . . . . . . . . .6 Browsing the current channel . . . . . .9 Best practices . . . . .9. . . . . . . . . . . . . . . .4. . . 64 3. . . . . . . . . . . . . . .2. . . . . . . .2 Channel and container options . .PK23547 on CICS Transaction Server version 3. . . . . . . . . . . . . . . . . . . . . 54 Chapter 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 42 2. . . . . .1. . . 76 3. . . . . . . . .6 Browsing the current channel . . . . . . . . .6 Command-level interpreter CICS-supplied transaction example . . . . . . .1 Creating a channel . . . . . . . . . .2 APAR . . . . . . . . . . . . . . . . . . . .8 Deleting a container . . . . . . . . . . . . .2 Naming a channel .7 Browsing a name channel. . . . . 60 3. . . . . . . 39 2. . . 40 2. . . . . . . . . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 2. . . . . . . . .1. . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Using channels and containers in CICS Web services . . . . . . . 48 2. . . . . . . . . . . . . Programming. . . 74 3. . .8 Moving containers between channels . . . . 69 3. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . and user-replaceable modules . . . . . . . . . . . . . . . . . . . . . . 182 5. . . . . . . . . . . . . . .2 New trace entries . . . . . .5. . . . . . . . . . . . . . . .2 TRUEs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Migration planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . 102 4. . . . . . . . 135 5.7 Running the application. . . . . . . . . . . . . . . . . . . . . . . . .1 Configuration . . . . . . . . . . . . . . . . . . .1 Administration questions . . .1 Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . .4 Conclusion. . . . . . . . . . . 111 4. . . . . . . . .3 Dynamic routing by data content. . . 176 5. . . . .2 Running the Java SOAP client . . . . . . . . . . . . . . . . . . . . . . .1 The CICS catalog manager example application . . . . . . . .4 Stage1: migration to the new function . . . . . . . . . .6 Defining the 3270 interface . . . . . . . . . . . . . . . .2 Application programming questions . . . . .5 Installing and setting up the base application . . . . . . . . . . . . . . . . .1 Back level toleration . .7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Chapter 5. . . . . . . . . . . . . . .6 Intersystem communication flow . . . . . . . . . . . . . . . . . 191 Contents v . . . . . . . . . . . . . .1 Implementation scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . .7. . . . . . . . . . . . . .2 z/OS Unicode conversion services . . . . . . . .4 Performance considerations . 101 4. . . . . . . . . . .5.1. . . . . . . . . . . . . . . . . .2. Systems management and configuration . . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . . . .3 Catalog manager application: performance . . . . . . . . . . . . . . 99 4. . . . . .7. . . . . . . . . . . . . . 190 6. . . . 90 4. . . .7. . . . . . . 122 4. . . . . . . . . . . .4 Sample application trace flow . . . . . . . global user exits. . . . . . . . . . .2 The base application . .7 Problem determination . . . . . . . . . . . 90 4. . . . . . . . 104 4. . .1. . . . .5 Multiregion operation flow . . . . . . . . . . . . . . . . . . . . . . . . .3 Code page conversion . . . . . 99 4. . . . . . . . . 168 5. . . .2 Performance data . . . . . . . . .3 Tracing channels and containers applications . . . . . . . . . . . . . . . . . . . . . . . . . . 174 5. 96 4. . . . . . . . .3 Migration steps: CICS back end . . . . . . . .1 Monitoring changes . 93 4. . .1. . . . . . . . . . . . . . . . . . . . . . . . . . 134 5. 93 4. . . . . . . .4. . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . 89 4. . . Frequently asked questions . . . . . . . . . . . . .1. . . . . . . 106 4. . . . . 164 5. . . . . . . . 133 5. . . . . . . . . . . . . . . . . . . . . .2 Running the stage 2 code . . . . . . . . . . 138 5. . . . 189 6. . .4. . 105 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample application . . . . . . . . .1 New abend codes . . . . . . . 102 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 5. . . . . . . . . . . . .2. 91 4. . 92 4. . . . . . . .1. . . . . .1. . . . . . . . . .1. . . . . . . . . . . . . . . . . 105 4. . . . . . . . . . . . . . . . . . .5 Monitoring and statistics . . . . . . . . . . . . . . . . . . . .1 Simple code page conversion . . . . . . .Chapter 4.7. . . . . . . . . . . . . . . 188 Chapter 6. . . 139 5. . . . . . . . . . . .2 Statistical changes . . . . . .1 Installing and setting up the stage 2 application . . . . . . . . . . . . .8 Stage2: catalog item images support . 110 4. .3. . . . . . . . . . .2 The DFHROUTE container . . . . . . . . . . . . . . . . . . . . . . . 163 5. .1. . . . . . . . . . . . . . . . . . 136 5. . . . . . . . . 91 4. . . . . . . . . . . 174 5. . . . . . . . . . . . . . . . . . . . . . 104 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . 200 JCICS business method. . . . . . . . . . 213 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Online information about channels and containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 System requirements for downloading the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Using the Web material . . . . . . . . . . . . . . . . . . 208 Sample server program used in some examples . . . .4 6. . . . . . . . . . . . . . . . . . . . . . 215 vi CICS Transaction Server V3 R1 Channels and Containers Revealed . . . . . . . . . . . . . . . . . . . . . . . . . . 199 JavaServer pages . . . . . . . . . . . . . . . 208 How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Appendix A. 198 What the JCICS EJB example does . . . . . . . . . . . . . . . . . . . . . . . .6 Performance questions . . . . . . . . . . . . . . . . . . . 208 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Locating the Web material . . . . . . . . . . . 204 Installation . . . . . . . . . . . 195 Hints and tips. . . . .5 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Channel and containers JCICS EJB example . . CICS Java Enterprise JavaBeans example . . . . . . . 193 Functions not supporting channels and containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Other publications . . . . . . . . . . . . . . . . . . 213 How to get IBM Redbooks . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . . . . . . . 214 Index . . . . . . . . . . . . . . . . . . . . . . 214 Help from IBM . . . . . . . . . . . . Additional material . . . . . . . .3 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 CICS back end program. 205 Appendix B. . . . . . . . . . . . . . . . . . 213 Online resources . . . . . . . .

or function of these programs. to: IBM Director of Licensing. which illustrates programming techniques on various operating platforms. program. program. All rights reserved. the examples include the names of individuals. You can send license inquiries. EITHER EXPRESS OR IMPLIED. for the purposes of developing.A. These examples have not been thoroughly tested under all conditions. IBM may not offer the products. and distribute these sample programs in any form without payment to IBM. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any functionally equivalent product. marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. Consult your local IBM representative for information on the products and services currently available in your area. IBM may have patents or pending patent applications covering subject matter described in this document. NY 10504-1785 U. this statement may not apply to you. therefore. Changes are periodically made to the information herein. MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. This information contains examples of data and reports used in daily business operations. vii . or service is not intended to state or imply that only that IBM product. To illustrate them as completely as possible. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. © Copyright IBM Corp. and products. or service may be used. Some states do not allow disclaimer of express or implied warranties in certain transactions. IBM. these changes will be incorporated in new editions of the publication. using. COPYRIGHT LICENSE: This information contains sample application programs in source language. in writing. modify. marketing. or service that does not infringe any IBM intellectual property right may be used instead. services. or service. compatibility or any other claims related to non-IBM products. Information concerning non-IBM products was obtained from the suppliers of those products. their published announcements or other publicly available sources. or distributing application programs conforming to IBM's application programming interfaces. The furnishing of this document does not give you any license to these patents. However.S. IBM has not tested those products and cannot confirm the accuracy of performance. program. it is the user's responsibility to evaluate and verify the operation of any non-IBM product. INCLUDING. companies. therefore. cannot guarantee or imply reliability. You may copy. modify. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT.A. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. and distribute these sample programs in any form without payment to IBM for the purposes of developing. 2006. brands. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. serviceability. program. using. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND. North Castle Drive Armonk. IBM Corporation. You may copy.Notices This information was developed for products and services offered in the U. BUT NOT LIMITED TO. Any reference to an IBM product.S. or features discussed in this document in other countries. This information could include technical inaccuracies or typographical errors.

or both. or service names may be trademarks or service marks of others. product. Java. EJB. or both: CICS® CICSPlex® CICS/VSE® DB2® eServer™ IBM® iSeries™ MQSeries® MVS™ OS/390® Redbooks™ Redbooks (logo) S/390® TXSeries® VSE/ESA™ WebSphere® z/OS® ™ The following terms are trademarks of other companies: Enterprise JavaBeans. other countries. JavaBeans. other countries. or both. Inc. Other company. Windows. and the Windows logo are trademarks of Microsoft Corporation in the United States. Linux is a trademark of Linus Torvalds in the United States. and all Java-based trademarks are trademarks of Sun Microsystems. in the United States. or both. viii CICS Transaction Server V3 R1 Channels and Containers Revealed . other countries.Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States. JVM. JavaServer Pages. other countries. J2EE. JavaServer.

© Copyright IBM Corp. Before joining the ITSO. the book explains the channels and containers application programming interface (API) and how it can be used in a traditional CICS application and also a CICS Java™ (JCICS) application. alongside these techniques. Then. Some authorized program analysis reports (APARs) are introduced. Chris Rayns is an IT Specialist and Project Leader at the ITSO. The business transaction services (BTS) API is discussed as a similar yet recoverable alternative to channels and containers. which you must consider when implementing a channels and containers solution. which allows CICS to fully comply with emerging technology requirements in terms of sizing and flexibility. This book describes the constraints they may be subject to. he worked in IBM Global Services in the United Kingdom (UK) as a CICS IT Specialist.1. It provides examples to show how to evolve channels and containers from communication areas (COMMAREAs). The book begins with an overview about the techniques used to pass data between applications running in CICS. Chris writes extensively on all areas of IBM S/390® security. 2006. ix . and how a channels and containers solution can provide solid advantages. The book chooses a sample application in the CICS catalog manager example and describes how you can migrate an existing CICS application to exploit channels and containers rather than using COMMAREAs. Specializing in security.Preface This IBM® Redbook discusses the new channels and containers support in IBM Customer Information Control System (CICS®) Transaction Server 3. All rights reserved. Poughkeepsie Center. The book also presents information from a systems management point of view discussing the systems management and configuration tasks and techniques. which enable more flexible Web services features through the use of channels and containers. The book then goes on to discuss application design and looks at implementing channels and containers from an application programmers point of view. Poughkeepsie Center in New York. The team that wrote this IBM Redbook This book was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO).

the IBM WebSphere® MQ family of products. Linux®. His areas of expertise include OS390. where he provides defect and non-defect support for CICS. He has more than 20 years experience working with CICS in different roles. His expertise includes WebSphere MQ. He has 18 years of experience working as a technical support specialist with IBM software products. CICS. he has worked as a Systems Programmer. CICS VSAM Recovery (CICSVR). Peter has contributed to several other IBM Redbook publications and ITSO projects sponsored by IBM Learning Services. The last nine years. David has been working in the IT industry for 25 years and has written extensively about diagnostic processes for the ITSO. He has 23 years of experience in CICS and has been with IBM for 10 years. A senior member of his team. and distributed transaction systems. and Networking products. and Assembler. Dave Carey is a Senior IT Advisory Specialist with the IBM Support Center in Sydney. Common Business Oriented Language (COBOL).Pietro De Angelis is a Senior Product Support Software Service Specialist: IBM Certified in the Italy Technical Support Centre. UK. Peter Klein is a CICS Team Leader at the IBM Germany Customer Support Center. Scott is always looking at new ways to push automated test generation and execution. and the IBM Multiple Virtual Storage (MVS™) System Logger. His areas of expertise include Virtual Storage Access Method (VSAM). CICSPlex System Manager. working as a CICS Technical Solutions Specialist prior to joining the Change Team. He has contributed widely to other ITSO CICS IBM Redbook publications. and for new and novel ideas that add to the mainframe. Steve Burghard is a member of the CICS 390 Change Team based in Hursley. Scott Clee works as a CICS Tester for IBM in the UK. He holds a degree in Mathematics and Computing from the University of Bath. and IBM z/OS®. and has a vast range of experience in all areas of IBM CICSPlex® Systems Manager and IBM CICS Transaction Server for OS/390®. Erhard Woerner is a Software Support Specialist in Germany. He holds a degree in Classical Studies from Liceo Classico Socrate in Rome. CICSPlex or System Manager. Java. He has excellent knowledge in the CICS programming languages COBOL. Areas of expertise include CICS. x CICS Transaction Server V3 R1 Channels and Containers Revealed . and Testing. He has worked for IBM as CICS Level 2 Support for seven years. Australia. PL/I. He has 22 years of experience in Transaction Systems on the Mainframe platform.

CICS Transaction Server IBM Hursley Steve Zemblowski. You team with IBM technical professionals.Thanks to the following people for their contributions to this project: Mark Cocker. and apply online at: ibm. CICS Technical Strategy and Planning IBM Hursley Rich Conway ITSO Technical Support International Technical Support Organization.com/redbooks/residencies. Find out more about the residency program.html Preface xi . Technical Planner IBM Hursley Steve Wood. Software Specialist. Poughkeepsie Center Phil Hanson.to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions. browse the residency index. CICS Transaction Server Team Lead IBM Hursley Phil Wakelin. Business Partners or customers or both. Hursley Product Line Manager. you'll develop a network of contacts in IBM development labs. while getting hands-on experience with leading-edge technologies. and increase your productivity and marketability. CICS Product Manager IBM Hursley Colin Penfold. CICS Transaction Gateway. Your efforts help increase product acceptance and client satisfaction. Advanced Technical Support IBM Dallas Become a published author Join us for a two. As a bonus.

Comments welcome Your comments are important to us! We want our IBM Redbook to be as helpful as possible. Send us your comments about this or other IBM Redbooks in one of the following ways: Use the online Contact us review IBM Redbook form found at: ibm. International Technical Support Organization Dept.com Mail your comments to: IBM Corporation. NY 12601-5400 xii CICS Transaction Server V3 R1 Channels and Containers Revealed . HYJ. HYJ Mail Station P099 2455 South Road Poughkeepsie.com/redbooks Send your comments in an e-mail to: redbook@us.ibm.

All rights reserved. Introduction to channels and containers This introduction provides an overview about the techniques used to pass data between applications running in Customer Information Control System (CICS). 1 .1 Chapter 1. and how a channels and containers solution can provide solid advantages. alongside these techniques. which allows CICS to fully comply with emerging technology requirements in terms of sizing and flexibility. 2006. © Copyright IBM Corp. We describe the constraints they may be subject to.

When one program uses an xctl command to transfer control to another program. CICS may copy the specified COMMAREA into a new area of storage. the address of the area is passed to the program that is receiving control. Program A EXEC CICS LINK PROGRAM ('program') COMMAREA (structure) Program B EXEC CICS ADDRESS COMMAREA (structure-ptr) Figure 1-1 Sample of a link using COMMAREA 2 CICS Transaction Server V3 R1 Channels and Containers Revealed . or to transfer information between two transactions from the same terminal. Information in a COMMAREA is available only to the two participating programs. unless those programs take explicit steps to make the data available to other programs.1 Communication area for data passing In 1975 command-level programming was introduced in CICS using an in-memory process called the communication area (COMMAREA). because it can return the maximum storage. This is because the invoking program and its control blocks may no longer be available after it transfers control. In either case. it is significantly more for a distributed program link (DPL). It is slightly more with the xctl and return commands. However. However. the COMMAREA may be any data area to which the linking program has access.1. The COMMAREA was limited in size to 32 KB. and the CICS command-level interface sets up addressability. as a method of passing data from one application to another. which may be invoked later in the transaction. Figure 1-1 shows a diagram representing a link using a COMMAREA. this was not a concern. when CICS creates the COMMAREA from a larger area of storage used by the program. The overhead for using COMMAREA in a link command is minimal. because application data was 3270 based and so not resource hungry. The 32 KB limit was enough to manage data propagation between applications. It is often in the working storage or Linkage Section of this program. the linking program can both pass data to the program it is invoking and receive results from the specified program. Characteristics of a COMMAREA A COMMAREA is a facility used to transfer information between two programs within a transaction. When one program links to another. In this area.

and return commands pass is 32 KB. in both Extensible Markup Language (XML) and Chapter 1. 1. which is based on Web technologies and which requires large amount of data to pass between applications. meaning the maximum length for an area that the link. A COMMAREA is available only to the first program in the next transaction. This puts a theoretical upper limit of 32763 bytes on length.The length option of a CICS command is generally expressed as a signed half-word binary value. Previously. but merely enhancing the technique of passing data. xctl. we are not changing at all. and based on which the major part of CICS applications have been built? The answer is. the current CICS applications are required to process large quantities of structured parameter data. This enhanced design also provides the possibility to dynamically add or remove parts of the passed data. The following is a summary of some of the characteristics of a COMMAREA: Processor overhead is low. The use of the COMMAREA option on the return command is the principal example of a safe programming technique that you can use to pass data between successive transactions in a CICS pseudo-conversational transaction.2 The requirement for change Considering that the COMMAREA is the most popular technique used to pass data between applications that run in CICS. However. CICS applications were highly optimized to be memory efficient and were easily able to pass the required parameter data within the size constraints imposed by the CICS API on COMMAREA memory size. unless this program explicitly passes the data to another program or a succeeding transaction. CICS holds a COMMAREA in CICS main storage until the terminal user responds with the next transaction.1 Memory constraints CICS applications have traditionally passed parameter data using the EXEC CICS LINK application programming interface (API) specifying a COMMAREA. COMMAREA is not recoverable. the question is: Why do we require to change such a valid method which historically demonstrates its strength. Introduction to channels and containers 3 . 1.2. This is for the benefit of the new evolution of application design.

XML structures can accommodate a varied mix of data types. a new way to exchange data is required alongside the COMMAREA solution. and it is common for an XML document to contain large binary objects such as images in addition to character and numeric payload data. 4 CICS Transaction Server V3 R1 Channels and Containers Revealed . The consequence of effectively extending CICS applications to new enterprise solutions is that the constraints imposed on the COMMAREA size by the system may be too inflexible. the parameter data contained within it is different from the data format previously known to CICS programmers. is becoming the norm. 1. This is because the integration of CICS applications with the elements of enterprise solutions. the 32 KB limit together with the static structure imposed on the traditional CICS COMMAREA is insufficient for such applications.1 introduces a new approach that provides an easy and more flexible mechanism for exchange of large volumes of structured parameter data between CICS programs. XML is extensible. This new approach is known as the channels and containers model. This may not be acceptable for the modern application design. While the COMMAREA remains the basic way to pass data between CICS application programs with the recognized qualities mentioned earlier. even if only part of this data is required. By design.non-XML formats. When you add the lengthy tag descriptions. If an XML document has to be exchanged. where the flexibility of data structure is a basic component that offers the possibility of accommodating future business requirements. CICS Transaction Server Version 3.2 Flexibility of the channels and containers approach The COMMAREA is a large and contiguous block of data that contains all of the data to be passed to the called program. outside the bounds of the CICS environment. XML-based parameter data areas can require large areas of memory when passed by value between program elements.2. so you can add further data elements when application requirements change. This provides an alternative way to satisfy the requirements introduced by the usage of new application programming styles. Therefore.

This 32 KB constraint can also affect the exchange of data between multiple CICS tasks in the following cases: – When data is passed between two tasks via the use of the EXEC CICS START TRANSID FROM command.1. ECI. – In CICS transactions involved in a pseudo-conversational sequence where you can exchange data through the use of the EXEC CICS RETURN TRANSID COMMAREA command. To deal with this type of content. between two CICS regions. 1. These constraints are also applicable to those COMMAREAs that programs participating in a DPL use.3 COMMAREA constraints and alternate solutions The following is a more detailed look at the COMMAREA in order to understand its constraints and the techniques you might consider using to bypass them.3.1 COMMAREA size limit The size limit of the COMMAREA can be explained as follows: The EXEC CICS API constrains the size of a COMMAREA to a maximum of 32 KB. The 32 KB COMMAREA restriction also applies to the external CICS interface (EXCI) and the external call interface (ECI) used by the CICS Transaction Gateway and the CICS Universal Clients.1. and CICS Universal Client are not suitable for using channels and containers in CICS Transaction Server 3. circumvention methods are required. Note: EXCI. It is in the processing of large XML documents that the constraints of the traditional COMMAREA application become more prominent. Introduction to channels and containers 5 . The 32 KB COMMAREA size constraint is applicable to both link and xctl commands in a single region. Chapter 1.

6 CICS Transaction Server V3 R1 Channels and Containers Revealed . using the appropriate EXEC CICS API. Depending on the configured resource characteristics these may be accessible across multiple CICS regions. These may include: Using the FLENGTH option of the GETMAIN command to acquire a storage area larger than 32 KB and passing the address of the large storage area in the COMMAREA. – Require to ensure that programs use same data key and data lock. Additional systems configuration and management may be required depending on the nature of the shared managed resource. These solutions require the application to manage unique resource naming conventions and implement life cycle management for the resource used. By placing the data in temporary storage more than 32 KB of data can be passed between programs or tasks. Using Virtual Storage Access Method (VSAM) files or IBM DB2® data. only works in a single CICS address space. Allocation of program specific managed resources such as VSAM files or DB2 data to contain large parameter payload and passing the resource name within the COMMAREA structure. perhaps introducing additional processing overhead. If the temporary storage queue is placed in a temporary storage.3. the data can be accessed across multiple CICS regions. Passing the name of a IBM WebSphere MQSeries® queue in the COMMAREA.2 Methods of passing COMMAREA data larger than 32 KB There are a number of options you might consider implementing to circumvent the 32 KB COMMAREA restriction both within a single CICS region and between multiple CICS regions. while simple. Passing the name of a temporary storage (TS) queue in the COMMAREA. By placing the data in WebSphere MQSeries queues and only passing the queue name. – This solution. a larger amount of data can be passed between the communicating programs or tasks. owning region or a shared temporary storage server. Applications may also be required to implement the resource setup and initialization.1. A region affinity between the two programs or transactions is created. The following considerations apply to many cases in the previous mentioned techniques: Applications may create new managed resources of the types listed.

By contrast.3. Loss of compatibility Merely changing the COMMAREA length to a full word length could result in the loss of object and source code compatibility for existing CICS programs. Inefficient transmission of overloaded COMMAREAs: – The current overloaded COMMAREA structure does not lend itself to being efficiently transmitted between CICS regions. Some of these issues include: Overloading of the copybooks The current copy books used in the exchange of data today tend to be overloaded and these structures are redefined a number of times depending on whether the copybook is passing input. CICS must always return the full COMMAREA structure from a DPL. the COMMAREA remains the most used method to pass data between applications running under CICS. The COMMAREA structure size must account for the maximum size of the data which can be returned. By addressing the COMMAREA structure directly. Also. the channel construct offers a simple way to get character data returned in the code page your application program requires. Note: Further information regarding this argument is presented in 2. even if nothing has been changed. In this case a program would have difficulty determining if EIBCALEN was valid or whether to check a new EXEC interface block (EIB) field. Business transaction services (BTS) exploitation This approach addresses many of the concerns associated with the previous circumvention techniques and is available on all currently supported CICS Chapter 1. with the various techniques available to bypass the 32 KB restriction.1. – The current COMMAREA structure does not allow for easy separation of binary and character data. While such an implementation would ease the 32 KB restriction. it would not resolve all the problems that exist in exchanging data today.3. This leads to confusion on exactly when the fields are valid. Introduction to channels and containers 7 . Therefore. it would exacerbate some of the problem areas. or error information.3 The evolution of the 32 KB COMMAREA It is worth mentioning. output. CICS cannot determine if you have changed the data contents. the simplest solution to this problem would have been to make the COMMAREA capable of handling lengths greater than 32 KB. “Overloaded COMMAREAs” on page 33.

CICS provides EXEC API verbs to create. which associates a named channel with a collection of one or more containers. This is an easy way of grouping parameter data structures which may pass to a called application. when a channel becomes out of scope. This allows CICS components to process XML or other structure data in places where the 32 KB COMMAREA limit cannot satisfy the application requirements. it requires the adoption of a new programming approach for CICS applications with consequential application re-engineering. A channel is analogous to a COMMAREA. The adoption of channels and containers in existing applications can preserve the existing application architecture while overcoming the most common constraints exposed by the new data format. However. and binary payload data. A container is a named reference to a CICS-managed storage area that can hold any form of application data. access. CICS destroys a channel when it can no longer be referenced. numeric. 1. 8 CICS Transaction Server V3 R1 Channels and Containers Revealed .4 Channels and containers concepts CICS Transaction Server Version 3. which means. delete. A channel is a uniquely named reference to a collection of application parameter data held in containers. XML requirement In the contemporary enterprise solution context a CICS application may expect to exchange parameter data in the form of an XML document. This may be an ambitious undertaking for a mature critical CICS business application suite. either from a system component external to CICS or as part of the request processing path with other CICS applications.versions. This new approach is provided by two new capabilities known as channels and containers. and manipulate a container as well as to associate it with a channel. but it does not have the constraints of a COMMAREA. An application can reference any number of containers. reference. CICS provides EXEC API . A container may be any size and can hold data in any format that the application requires. Depending on the nature of the request XML documents may be large while containing large volumes of character.1 introduces a new approach that provides an easy and more flexible mechanism for exchange of large volumes of structured parameter data between CICS programs.

4. Chapter 1. think of it as a parameter list.1. It can do this by creating new containers. xctl. To create named containers and assign them to a channel. You can think of them as named COMMAREAs. Example 1-1 shows how to pass a channel on a link. or by reusing existing containers. Programs can pass a single channel between them. Containers are grouped together in sets called channels. Introduction to channels and containers 9 . Size of containers is limited only by the amount of storage available.1 General concepts Some general concepts are identified as follows: Containers are named blocks of data designed for passing information between programs. Example 1-1 Passing a channel on a link EXEC CICS PUT CONTAINER(structure-name) CHANNEL(channel-name) FROM(structure) EXEC CICS LINK PROGRAM(PROG2) CHANNEL(channel-name) The second program can read containers passed to it using the following command: EXEC CICS GET CONTAINER(container-name) This command reads the named container belonging to the channel that the program was invoked with. it can also return containers to the calling program. start. See Example 1-2. Example 1-2 Receiving a container EXEC CICS GET CONTAINER(structure-name) CHANNEL(channel-name) INTO(structure) If the second program is invoked by a link command. The same channel can be passed from one program to another. or return commands. a program uses the following command: EXEC CICS PUT CONTAINER(container-name) CHANNEL(channel-name) It can then pass the channel and its containers to a second program using the CHANNEL(channel-name) option of the EXEC CICS link.

offering an easy way to group parameter data structures that may pass to a called application. use CICS business transaction services containers. If you require to use recoverable containers. 1. Because programB receives the data from programC in a container. a channel name might be <employee-info>. CICS Transaction Server removes a channel when it can no longer be referenced. programA can pass data in a COMMAREA to programB. CICS automatically destroys the containers and their storage. EXEC CICS XCTL. For example in a human resource application. Channel and containers are not recoverable. and this is where programA expects to find it.2 Channels A channel is a uniquely named reference to a collection of application parameter data held in containers. This collection of application parameter data serves as a standard mechanism to exchange data between CICS programs. and EXEC CICS RETURN can only pass a channel or a COMMAREA. CICS Transaction Server provides an EXEC API that associates a named channel with a collection of one or more containers. programB moves the container data into a COMMAREA. meaning when it becomes out of scope.4. When these programs terminate. It’s analogous to a COMMAREA but is not subject to the constraints of a COMMAREA. Example 1-3 Returning a container EXEC CICS PUT CONTAINER(structure-name) FROM(structure) EXEC CICS RETURN Channels and containers are visible only to the program that creates them and the programs they are passed to. Channels and COMMAREAs are mutually exclusive. However. which then creates a channel to pass the data on to programC.See Example 1-3. You can choose a channel name which is a meaningful representation of the data structures that the channel is associated with. The relationship between channel and BTS containers is described in channels and BTS activities. in the sense that an EXEC CICS LINK. 10 CICS Transaction Server V3 R1 Channels and Containers Revealed .

through a link. Program A EXEC CICS LINK PROGRAM('PROGRAMB') CHANNEL('EMPLOYEE-INFO') Current Channel: none Program B EXEC CICS LINK PROGRAM('PROGRAMC') CHANNEL('EMPLOYEE-INFO') Current Channel: EMPLOYEE-INFO Program C EXEC CICS LINK PROGRAM('PROGRAMD') Current Channel: EMPLOYEE-INFO Program D EXEC CICS LINK PROGRAM('PROGRAME') CHANNEL('MANAGER-INFO') Current Channel: none Program E EXEC CICS RETURN Current Channel: MANAGER-INFO Figure 1-2 The current channel Chapter 1. the current channel is used as the default value for the CHANNEL (channel-name) parameter on the EXEC CICS command. If a channel is not explicitly specified. It is analogous to a parameter list. the current channel. for a particular invocation of a particular program. xctl. start. never changes. Introduction to channels and containers 11 .The current channel A program's current channel (if any) is the channel with which it was invoked. Figure 1-2 shows the previously mentioned process. Although the program can create other channels. by transferring the control to the called program. The current channel is set by the calling program or transaction. and pseudo-conversational return with the channel parameter.

but typically.4. “STARTBROWSE application programming interface” on page 36. this is not necessary. programs that exchange a channel are written to handle that channel. if it issues the following command: EXEC CICS ASSIGN CHANNEL If there is no current channel.Typically. Example 1-4 Browsing containers in a channel EXEC CICS STARTBROWSE CONTAINER BROWSETOKEN(data-area) EXEC CICS GETNEXT CONTAINER(data-area) BROWSETOKEN(token) EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(token) Having retrieved the name of its current channel and. and the names and number of the containers in that channel. a server program can adjust its processing to suit the kind of data that it has been passed. meaning the channel with which it was invoked. both client and server programs know the name of the channel. the command returns blanks. the assign channel command returns blanks unless it was invoked via start. Meaning. A program written to handle several channels is often coded to be aware of the names and number of the containers in each possible channel. it must discover which of the possible channels it has been passed. link. Note: A browse does not guarantee the order in which containers are returned. if necessary. Note: For a program creating a channel. if a server program or component is written to handle more than one channel. To get the names of the containers in the current channel. 12 CICS Transaction Server V3 R1 Channels and Containers Revealed . for example. on invocation. or xctl. use the browse commands as Example 1-4 shows. A program can discover its current channel. specifying channel name. The program can also retrieve the names of the containers in its current channel by browsing. However. The browsing of a channel is discussed in detail in 2. the names of the containers in the channel.

Refer to Figure 1-3 that illustrates the scope of channel. and program C (for which it is also the current channel). Scope of Channel EMPLOYEE_INFO Program A EXEC CICS LINK PROGRAM('PROGRAMB') CHANNEL('EMPLOYEE-INFO') Current Channel: none Program B EXEC CICS LINK PROGRAM('PROGRAMC') CHANNEL('EMPLOYEE-INFO') Current Channel: EMPLOYEE-INFO Program C EXEC CICS LINK PROGRAM('PROGRAMD') Current Channel: EMPLOYEE-INFO Scope of Channel MANAGER_INFO Program D EXEC CICS LINK PROGRAM('PROGRAME') CHANNEL('MANAGER-INFO') Current Channel: none Program E EXEC CICS RETURN Current Channel: MANAGER-INFO Figure 1-3 Example showing the scope of a channel Figure 1-3 shows the scope of channel EMPLOYEE-INFO. Chapter 1.The scope of a channel The scope of a channel is the code. Figure 1-3 shows the scope of channel MANAGER-INFO. from which you can access it. meaning the program or programs. Introduction to channels and containers 13 . which consists of programs A (the program which created it). Additionally. program B (for which it is the current channel). which consists of programs D (which created it) and Program E (for which it is the current channel).

on a local or remote system. passing the channel and container data to the next transaction Figure 1-4 API to create and manage a channel API used to manage channels and containers are further described in 3.Lifetime of a channel A channel is created when it is named on an EXEC CICS command. on a local or remote system. if one exists EXEC CICS LINK PROGRAM CHANNEL Links to the program. copying the named channel and container data and passing it to the started task EXEC CICS RETURN TRANSID CHANNEL Returns control to CICS.1. This causes CICS to delete the channel. Figure 1-4 shows the APIs used to create and manage a channel. which means that no programs are able to access it. The usual command to create a channel is the following: EXEC CICS PUT CONTAINER In the previously given command. EXEC CICS PUT CONTAINER CHANNEL Creates a channel and places data into a container within the channel EXEC CICS GET CONTAINER CHANNEL Retrieves the container data passed to the called program EXEC CICS MOVE CONTAINER CHANNEL AS TOCHANNEL Moves a container from one channel to another channel EXEC CICS DELETE CONTAINER CHANNEL Deletes a container EXEC CICS ASSIGN CHANNEL Returns the name of the program’s current channel. 14 CICS Transaction Server V3 R1 Channels and Containers Revealed . “EXEC CICS application programming interface” on page 60. A channel is deleted when it goes out of scope to the programs in the linkage stack. specifying the channel parameter creates the channel and also associates the container with it. passing the channel and container data EXEC CICS XCTL PROGRAM CHANNEL Transfers control to the program passing the channel and container data EXEC CICS START TRANSID CHANNEL Starts a task.

It can include data in any format that an application requires. and making the association between data structure and purpose clear. reference. The potential errors are minimized by isolating different data structures. and manipulate a container and also to associate it with a channel.3 Containers A container is a uniquely named block of data that can be passed to a subsequent program or transaction. and a container size is constrained only by the available user storage in the CICS address space.4. It also minimizes the potential for errors that commonly arise when parameter data for multiple applications is overloaded in a single memory area. the container name might be <employee-name>.1. It refers to a particular parameter data structure that exists within a collection of virtually any form of application parameter data. access. This capability helps ensure that each container structure is based on a unique area of memory. Chapter 1. in a human resource application. EXEC CICS PUT CONTAINER CHANNEL Creates a channel and places data into a container within the channel EXEC CICS GET CONTAINER CHANNEL Retrieves the container data passed to the called program EXEC CICS MOVE CONTAINER CHANNEL AS TOCHANNEL Moves a container from one channel to another channel EXEC CICS DELETE CONTAINER CHANNEL Deletes a container from a channel EXEC CICS STARTBROWSE CONTAINER Start a browse of the containers associated with a channel EXEC CICS GETNEXT CONTAINER Return the name of the next container associated to the channel EXEC CICS ENDBROWSE CONTAINER Ends the browse of the containers associated with the channel Figure 1-5 Container related API A container can be any length. such as binary and character data. You can choose a container name which has a meaningful representation of the data structure. See Figure 1-5 for more details. Introduction to channels and containers 15 . For example. delete. An application can create any number of containers and can use separate containers for different data types. CICS Transaction Server provides EXEC API verbs to create.

as part of a channel application or as part of a BTS activity. If there is no current channel. CICS first checks to see if there is a current channel. There is no limit to the size of a container in BTS. The containers used in the channel context are similar to those used in BTS and the commands used to access the container data are similar. and delete container commands used to build and interact with a channel are similar to those used in CICS BTS applications. BTS implemented containers as a way of passing information between activities and processes. move container. If this is part of a BTS activity. move. move container. When a container command is executed. The BTS approach requires the adoption of a new programming approach for CICS applications with consequential application re-engineering. It is possible to have the same server program invoked in both a channel and a BTS context. a program that issues container commands can be used. or delete a read-only container. there have been white papers written to describe how a programmer might use BTS containers as a Big COMMAREA. put. get. This may be an ambitious undertaking for a mature critical CICS business application suite. if you specify a read-only container on a put container. If the program has no channel context and no BTS context.4 Channels and business transaction services The put container. You cannot overwrite. 1. without change. move. CICS checks to see if this is part of a BTS activity. then the context is BTS. which CICS requires on return from the user program. To accomplish this the server program must avoid the use of options that specifically identify the context.4. then an INVREQ is raised. In some cases CICS marks these containers as read-only. If there is a current channel. The server program must call CICS to determine the context of a command. and pass them to user programs. so that the user program cannot modify data. get container. 16 CICS Transaction Server V3 R1 Channels and Containers Revealed . then the context of the command is channel. Therefore. delete. User programs cannot create read-only containers. In fact. The channels and containers approach is more simple and does not require as much effort to change applications. Thus. for example.CICS read-only containers CICS can create channels and containers for its own use. or delete container command you receive an INVREQ condition.

cics. Note: You can use channel and container related JCICS commands when writing CICS enterprise beans.2. for example.Channel A Channel class used to create new containers in a channel com.server.server.server.server. If you require to use recoverable containers.ChannelErrorException Class that represents the CICS CHANNELERR condition com. use CICS BTS containers.ibm.Note: Channel containers are not recoverable.ContainerErrorException Class that represents the CICS CONTAINERERR condition Figure 1-7 JCICS classes for channels error handling Details on this item are further provided in 3.cics.4. “CICS Java” on page 69. CICS Java (JCICS) classes are provided to enable channels and containers to be used as the mechanism to exchange data between CICS Java 2 Platform. In the CICS Java environment. com.ibm. com. Chapter 1. CICS does not support the transmission of channels over Internet Inter-ORB Protocol (IIOP) request streams. This means that you cannot.ibm.server.CCSIDErrorException Class that represents the CICS CCSIDERR condition com.cics. However. pass a channel to an enterprise bean on a remote region.cics. 1.ibm.ibm.Container A Container class used to place data in a container com.5 Channels and CICS Java CICS provides EXEC API support for channels and containers in all supported CICS programming languages.cics.server. See Figure 1-6 for details on the JCICS classes that CICS Java programs can use to pass and receive channels.ibm.cics. Introduction to channels and containers 17 .ContainerIterator A ContainerInterator class used to browse the current channel Figure 1-6 JCICS classes managing channels CICS also provides the exception classes for handling errors shown in Figure 1-7. Enterprise Edition (J2EE™) style applications and traditional CICS procedural applications.

CICS converts the system data automatically. When you want to change the encoding of some character data from one coded character set identifier (CCSID) to another. where it is necessary. the conversion takes place under the control of the system programmer. 18 CICS Transaction Server V3 R1 Channels and Containers Revealed . is much simpler than the model that COMMAREA applications use. which is optional. when conversion is required. Extended Binary Coded Decimal Interchange Code (EBCDIC) and American Standard Code for Information Interchange (ASCII). The following are the processes that the application programmer supports: The application programmer is responsible only for the conversion of user data. Further information about data conversion is presented in 2. which is the data in containers that the application programs create.4. using simple API commands. Here are some cases in which data conversion is necessary: When character data is passed between platforms that use different encoding standards. Applications that use channels to exchange data use a simple data conversion model. for example. The data in channel and containers is converted under the control of the application programmer.1. Using channels Channel applications use the data conversion model. Using COMMAREA For applications that use the COMMAREAs to exchange data. you can use a single programming instruction to tell CICS to handle it automatically.6 Data conversion The data conversion model that channel applications use. and the DFHUCNV user-replaceable conversion program. This uses the DFHCNV conversion table. Conversion models There are two conversion model applications. the DFHCCNV conversion program. Frequently. “Data conversion and code page conversion” on page 39. no conversion is required and.6. This is because the system programmer controls the data conversion in COMMAREA applications. which is much simpler than the one that the COMMAREA applications use. while the application programmer controls the data conversion in channel applications. using API commands.

CICS supported method of passing parameter data Segregation of parameter data structures. between big-endian and little-endian. remember to add a temporary channel. then you are relying solely on the program to be called along with a channel.The application programmer is concerned only with the conversion of character data. Note: While using Example 1-5. Example 1-5 converts data from codepage1 to codepage2.5 Benefits of using channels and containers The life cycle and scope of channels and containers are completely under the control of the CICS system ensuring data integrity and storage resource management. Additionally. each part represented by a named container structure A loose functional coupling approach The freedom to dynamically determine the nature of the passed data and to select the appropriate processing required A CICS standard API for optimized exchange of data between CICS programs implemented in any CICS supported language CICS managed life cycle for channel and container resources Ease of parameter passing by use of unique named references Chapter 1. is not supported. Introduction to channels and containers 19 . These are the major benefits obtained by applications exploiting the capabilities of the channels and containers methodology: An unconstrained. Applications can use the container API as a simple means of converting character data from one code page to another. Example 1-5 API to convert code page EXEC CICS PUT CONTAINER(temp) DATATYPE(CHAR) FROMCCSID(codepage1) FROM(input-data) EXEC CICS GET CONTAINER(temp) INTOCCSID(codepage2) SET(data-ptr) FLENGTH(data-len) 1. The conversion of binary data. such as CHANNEL(temp). you must perform a delete container operation immediately. If you fail to add this temporary channel. if the data is large.

Existing application with COMMAREA Program A EXEC CICS LINK PROGRAM ('program') COMMAREA (structure) Program B EXEC CICS ADDRESS COMMAREA (structure-ptr) Changed application using channels Program A Program B EXEC CICS PUT CONTAINER(structure-name) CHANNEL(channel-name) FROM(structure) EXEC CICS LINK PROGRAM('programb') CHANNEL(channel-name) EXEC CICS GET CONTAINER(structure-name) INTO(structure) EXEC CICS GET CONTAINER(structure-name) INTO(structure) EXEC CICS PUT CONTAINER(structure-name) FROM(structure) EXEC CICS RETURN Figure 1-8 Changes from COMMAREA to channels using link The same applies to programs using the start command with the COMMAREA. Figure 1-8 shows you an example of this.Ease of understanding by use of unique named references to parameter payload Explicit code page conversion operations The internal CICS implementation of channels and containers is optimized for efficient memory management and data transfer. 1. This is to optimize the performance of the calling mechanism. Provided the containers separate the different parameter structures.6 Migrating COMMAREA to channels and containers To migrate programs that are exchanging data through a COMMAREA on a link command. CICS ensures that only the necessary new and modified containers are transferred between the calling applications. the calling applications benefit from complete access to the data content in all containers that are in scope. 20 CICS Transaction Server V3 R1 Channels and Containers Revealed . the format of the command must be changed and proper commands must be added to use channels and containers.

CICS starts one transaction for each start request. The example shows the commands that require to be added or changed. and DYRVER fields of the DFHDYPDS communications area. continue to work as before. When using the channel option on the start. EXEC CICS LINK and EXEC CICS START commands. DYRTYPE. Chapter 1. which use traditional COMMAREAS to exchange data. you must modify your program to handle the new values that it may pass in the DYRLEVEL. If you employ a user-written dynamic or distributed routing program for workload management. can be dynamically routed.Figure 1-9 shows an example of the changes necessary to convert an application program using an EXEC CICS START with data to start passing a channel. which can pass either COMMAREAs or channels. Introduction to channels and containers 21 . The started transaction is able to access the contents of a single channel and also get a copy of the channel. rather than CICSPlex System Manager. Existing application with START data Transaction 1 EXEC CICS START TRANSID('TRN2') FROM(structure) Transaction 2 EXEC CICS RETRIEVE INTO(structure) Changed application using channels Transaction 1 EXEC CICS PUT CONTAINER(structure-name) CHANNEL(channel-name) FROM(structure) EXEC CICS START TRANSID('TRN2') CHANNEL(channel-name) Transaction 2 EXEC CICS GET CONTAINER(structure-name) INTO(structure) Figure 1-9 Changes from COMMAREA to channels using start Items you may wish to consider when migrating from a COMMAREA to channels and containers: CICS application programs. CICS starts one instance of the transaction. The program can issue multiple retrieves to get the data. A program may issue multiple starts with data for a single transaction ID.

because the size of COMMAREAs is limited to 32 KB and channels were not available. some applications used TS queues to pass more than 32 KB of data from one program to another. Typically. In previous releases. a TS queue.9. the storage requirements of the new. the storage requirements of the migrated application are likely to be greater than those of the existing application. Channels have several advantages over COMMAREAs and it is advantageous to design your channels to make the most of these improvements. be aware that: – If the TS queue used by your existing application is in main storage. it is not good practice to do this. While this may seem the simplest way to move from COMMAREAs to channels and containers. 22 CICS Transaction Server V3 R1 Channels and Containers Revealed . This is because container data is held in storage rather than being written to disk. Also. and reads from. be aware that a channel may use more storage than a COMMAREA designed to pass the same data. – If the TS queue used by your existing application is in auxiliary storage. migrated. you must implement the best practices for channels and containers. this involved multiple writes to. Details about COMMAREA migration to channels and containers are provided in 2. “Migrating from COMMAREAs to channels” on page 54. Because you are taking the time to change your application programs to exploit this new function.It is possible to replace a COMMAREA using a channel with a single container. application are likely to be similar to those of the existing application. If you migrate one of these applications to use channels.3.

2 Chapter 2. 2006. The code page conversion. © Copyright IBM Corp. Examples are provided to show how to evolve channels and containers from communication areas (COMMAREAs). is now an issue for an application programmer. Application design and implementation In this chapter we discuss implementing channels and containers from an application programmers point of view. 23 . formerly an issue for the systems programmer. when utilizing channels and containers. All rights reserved.

the subroutine returns the same phonetic string for all names.1 Basic COMMAREA example This section shows an example of how to replace a COMMAREA by a channel and container solution. EXEC CICS LINK PROGRAM (PHONETIC) COMMAREA(MYCOMMAREA) END-EXEC. 03 LNAME PIC X(40). The first part of Example 2-1 shows the classic COMMAREA solution. The first variable is treated as the input field for the subroutine and the second variable receives the output the called program creates. Mayer. For instance. Therefore. . 03 PNAME PIC X(40). 2. The second part in Example 2-1 shows a name as input. Example 2-1 COMMAREA example 01 MYCOMMAREA. DISPLAY PNAME. 24 CICS Transaction Server V3 R1 Channels and Containers Revealed . 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. if you call the subroutine with different names. *** PNAME CONTAINS ‘MAYR’. MOVE 'MEYER' TO LNAME. or Maier.2.1. the subroutine returns MAYR when it is called for Meyer. The subroutine changes the name into a phonetic string and returns this string to the caller. . Example 2-1 is a program fragment that demonstrates how to call the subroutine PHONETIC with a COMMAREA. examples are presented of how to replace a COMMAREA with a channel and container solution.1 Container usage as a replacement to COMMAREAs In this chapter. A program calls a subroutine providing two variables grouped together into a COMMAREA structure. all of which sound the same but are spelled differently. For example. Meier.

EXEC CICS GET CONTAINER(OUTPUTCONTAINER) INTO(PNAME) CHANNEL(CHANNELNAME) END-EXEC. In Example 2-2. PNAME PIC X(40). MOVE 'MEYER' TO LNAME. DISPLAY PNAME. EXEC CICS PUT CONTAINER(INPUTCONTAINER) FROM(LNAME) CHANNEL(CHANNELNAME) END-EXEC.1. CHANNELNAME PIC X(16) VALUE IS 'MYCHANNELNAME'.1.2 Basic channel example Example 2-2 shows how to transform the small piece of code into a channel and container solution. EXEC CICS LINK PROGRAM (PHONETIC) CHANNEL(CHANNELNAME) END-EXEC. OUTPUTCONTAINER PIC X(16) VALUE IS 'MYOUTPTCONTAINER'. PHONETIC PIC X(8) VALUE IS 'PHONETIC'. We recommend that you perform this data separation.3 Channel name character set A channel name consists of 1-16 characters. even though it is still possible to send both variables in one container. This means that the two variables can be defined independently. Example 2-2 Channel and container example 01 01 01 01 01 01 LNAME PIC X(40). *** PNAME CONTAINS ‘MAYR’. you can see that the input to the subroutine can now be treated as two separate objects. INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. 2.2. Application design and implementation 25 . . The acceptable characters are as follows: A-Z a-z 0-9 $ @ # / % Chapter 2.

& ? ! : | " = ¬ , ; <> . _ Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks.

2.1.4 Creating a channel
You can create a channel if you name and place it with one of the following commands to transfer the control to another program or transaction: EXEC EXEC EXEC EXEC CICS CICS CICS CICS LINK PROGRAM CHANNEL START TRANSID CHANNEL XCTL PROGRAM CHANNEL RETURN TRANSID CHANNEL

Note: Start makes a copy of the channel. If there are subsequent changes in the program that issued the start, these changes are not reflected in the copy of the channel. Normally a PUT or MOVE is used to create a channel: EXEC CICS PUT CONTAINER CHANNEL EXEC CICS MOVE CONTAINER CHANNEL TOCHANNEL If the channel does not already exist within the current program scope, it is created. Note: If the channel name on the previous commands does not already exist within the current program scope, an empty channel is created. If this is done by accident, it leads to unpredictable results.

26

CICS Transaction Server V3 R1 Channels and Containers Revealed

A simple means to create a channel, and populate it with containers of data, is to issue a succession of commands as follows: EXEC CICS PUT CONTAINER(container-name) CHANNEL(channel-name) FROM(data-area) The first PUT command creates the channel, if the channel does not already exist, and adds a container to it. The subsequent commands add further containers to the channel. If the containers already exist, their contents are overwritten by the new data. An alternative way to add containers to a channel is to move them from another channel. To do this, use the command as follows: EXEC CICS MOVE CONTAINER(container-name) AS(container-new-name) CHANNEL(channel-name1) TOCHANNEL(channel-name2) You can use move container, instead of get container and put container, as a more efficient way of transferring data between channels. Note: The following are a summary of points that you must keep in mind: If the channel or TOCHANNEL option is not specified, the current channel is implied. The source channel must be in the program scope. If the target channel does not exist within the current program scope, it is created. If the source container does not exist, an error occurs. If the target container does not already exist, it is created. If it already exists, its contents are overwritten. When subroutines are called from various programs that use both COMMAREA and channel techniques, the subroutines must be able to recognize which technique is being used in the current invocation. The recommended method to check whether a channel is being used, is to use the Customer Information Control System (CICS) application programming interface (API) command EXEC CICS ASSIGN CHANNEL. If the returned value is not equal to spaces, then a channel has been passed and you can process it, otherwise use a COMMAREA. It is feasible to do the check if you reverse the process. Checking the EIBCALEN field for greater than zero indicates that this is a COMMAREA version. However, we do not recommend this, because if it is a pseudo conversational program the COMMAREA length is always zero on the first invocation. Therefore, in this case, you cannot trust this as an indication for COMMAREA or channel technique.

Chapter 2. Application design and implementation

27

In Example 2-3 we show the back end program phonetic, which has been written to use both techniques.
Example 2-3 Decide channel or COMMAREA: PHONETIC

WORKING-STORAGE SECTION. 01 CURRENTCHANNELNAME PIC X(16). 01 MYBROWSETOKEN PIC 9(8) BINARY. 01 INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. 01 OUTPUTCONTAINER PIC X(16) VALUE IS 'MYOUTPTCONTAINER'. 01 LASTNAME PIC X(40). LINKAGE SECTION. 01 DFHCOMMAREA. 03 LNAME PIC X(40). 03 PNAME PIC X(40). PROCEDURE DIVISION USING DFHCOMMAREA. EXEC CICS ASSIGN CHANNEL(CURRENTCHANNELNAME) END-EXEC. IF CURRENTCHANNELNAME IS EQUAL TO SPACES THEN * /* CONTINUE WITH COMMAREA */ CONTINUE ELSE * GET THE CONTAINER NAME EXEC CICS STARTBROWSE CONTAINER CHANNEL(CURRENTCHANNELNAME) BROWSETOKEN(MYBROWSETOKEN) END-EXEC EXEC CICS GETNEXT CONTAINER(INPUTCONTAINER) BROWSETOKEN(MYBROWSETOKEN) END-EXEC EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(MYBROWSETOKEN) END-EXEC EXEC CICS GET CONTAINER(INPUTCONTAINER) CHANNEL(CURRENTCHANNELNAME) INTO(LASTNAME) END-EXEC END-IF

28

CICS Transaction Server V3 R1 Channels and Containers Revealed

The STARTBROWSE example shown previously, only works when the subroutine is called with one container in the channel. We recommend that you access containers directly as described in the following section. A STARTBROWSE loop makes sense, where a subroutine is written to handle more than one channel. Therefore it must be able to discover which of the possible channel’s it has been passed. To learn more about this, read 2.4, “STARTBROWSE application programming interface” on page 36.

Current channel
If the container name that the subroutine uses is already known, then you can access the container directly. If you know that you are always using channels, the assign channel statement is not required. In this case, the channel used to invoke the subroutine is known as the current channel. Even though the subroutine may create other channels, the current channel does not change. A main program started for the first time does not have a current channel. You must reinvoke this program with an EXEC CICS RETURN TRANSID command with a channel, for this main program to have a current channel. Subroutines have a current channel when they are invoked with a channel. Example 2-4 shows the process you can use to get the input container directly, without using a browse loop. In this case, the name must be standard and not changed. Always check the response code for unexpected events, for example, CONTAINERERROR, which means that the specified container could not be found. See Example 2-4.
Example 2-4 Get container directly

WORKING-STORAGE SECTION. 01 L PIC 9(8) BINARY. 01 LASTNAME PIC X(40). 01 RC PIC 9(8) BINARY. 01 INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. 01 CURRENTCHANNELNAME PIC X(16). LINKAGE SECTION. 01 DFHCOMMAREA. 03 LNAME PIC X(40). 03 PNAME PIC X(40). PROCEDURE DIVISION USING DFHCOMMAREA. EXEC CICS ASSIGN CHANNEL(CURRENTCHANNELNAME) END-EXEC. IF CURRENTCHANNELNAME IS EQUAL TO SPACES THEN * /* CONTINUE WITH COMMAREA */

Chapter 2. Application design and implementation

29

However. and so on. This is a realistic situation. As Example 2-7 on page 32 shows. The following sections compare this application scenario in both variations. the data return by the subroutine could exceed the limit of a COMMAREA. It is conceivable that. in this situation. However. the subroutine does not simply return a phonetic string. 30 CICS Transaction Server V3 R1 Channels and Containers Revealed . output data with an unpredictable size. there are situations where the channel technique is much more easier to implement than the COMMAREA. and error data. it could be questioned which is better.2 Flexible way to pass multiple pieces of data There is more to coding with the channel technique than there is with the COMMAREA technique. Assume that there are applications that call the previously defined phonetic subroutine. DB2. especially existing running applications. providing a name as input. it also translates the name in a phonetic and reads from an input source. the question arises how to structure the data in the COMMAREA. status data. Virtual Storage Access Method (VSAM). We do not recommend replacing all COMMAREAs with channels. You require to provide input data. One such instance is explained in the following paragraph. 2. for example.CONTINUE ELSE * GET THE CONTAINER NAME EXEC CICS GET CONTAINER(INPUTCONTAINER) CHANNEL(CURRENTCHANNELNAME) INTO(LASTNAME) FLENGTH(L) RESP(RC) END-EXEC IF RC NOT = DFHRESP(NORMAL) THEN * *** DO SOME ERROR PROCESSING HERE *** CONTINUE END-IF END-IF. Furthermore.

2. If the subroutine returns the COMMAREA and the return codes and reason codes indicate that the request was successful. 03 CUSTOMERRECORD PIC X(800) OCCURS 0 TO 40 TIMES DEPENDING ON I. 03 REASONCODE PIC 9(8) BINARY. Partially successful means that the name has been successfully translated into a phonetic. Therefore. Although. Chapter 2. The return codes and reason codes indicate whether the request was successful. additional status data is required. because additional processing is necessary to retrieve all the data. Because you cannot determine the size of the returned data. 03 RETURNCODE PIC 9(8) BINARY. a loop is necessary to check on each return. Application design and implementation 31 . you have insufficient space remaining to add another client record of 800 bytes. so that this key can be used to start again. additional calls are required. An example of how this COMMAREA would look is provided in Example 2-5. 03 STATUSDATA PIC 9(15). the COMMAREA here is not exactly the maximum size of 32 KB. 03 NAME PIC X(40). partially successful. but the result set is too large and does not fit into the largest available COMMAREA.2.1 COMMAREA solution In addition to the mandatory input data. 03 I PIC 9(4) BINARY. or not successful. you also require some kind of return information data like return codes and reason codes. you must set up a maximum COMMAREA size. This is because the largest COMMAREA you can have is 32 KB. but there are more client records available that could not be returned because of the size limit of the COMMAREA. For instance the subroutine must receive the key of the latest record returned. This must be reflected in the return codes and reason codes. Example 2-5 COMMAREA example for a complex request 01 MYCOMMAREA. whether more data is still available or not. On a subsequent call to the subprogram.

is much easier and more logically structured. 32 CICS Transaction Server V3 R1 Channels and Containers Revealed .You can see this in Example 2-6. 01 P POINTER. CONTINUE END-PERFORM. 01 CHANNELNAME PIC X(16) VALUE IS 'MYCHANNEL'. 01 LNAME PIC X(40). and error prone. Example 2-6 COMMAREA programming example EXEC CICS LINK PROGRAM(PHONETIC) COMMAREA(MYCOMMAREA) END-EXEC. and the subroutine returns the result in another container. The input data is provided in a container to the subroutine. Example 2-7 Channel programming example WORKING-STORAGE SECTION. 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. If no container is returned then there is no client data available. 2. See Example 2-7.2. 01 OUTPUTCONTAINER PIC X(16) VALUE IS 'MYOUTPTCONTAINER'. complex in programming.2 Channel solution The program coding requirement to use channels and containers for the application scenario mentioned previously. * CHECK WHETHER ADDITIONAL CUSTOMER RECORDS ARE AVAILABLE IF RETURNCODE = 4 AND REASONCODE = 1 THEN PERFORM UNTIL RETURNCODE = ZERO * CALL PHONETIC AGAIN * PROCESS RESULTS CONTINUE END-PERFORM END-IF. then all the client records are in this container.. If a container is returned. 01 INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. This process is processor intensive. but this is not mandatory because the existence of an output container would indicate success. * PROCESS ALL RETURNED CUSTOMER RECORDS IN A LOOP PERFORM VARYING J FROM 1 BY 1 UNTIL J IS GREATER THAN I * . Error data could optionally return..

PROCEDURE DIVISION. Before using dummy sections a SET ADDRESS is required to establish addressability. Chapter 2. EXEC CICS PUT CONTAINER(INPUTCONTAINER) FROM(LNAME) CHANNEL(CHANNELNAME) END-EXEC. It is much easier and more straightforward.3 Overloaded COMMAREAs The current copybooks used in the exchange of data. LINKAGE SECTION. EXEC CICS GET CONTAINER(OUTPUTCONTAINER) CHANNEL(CHANNELNAME) SET(P) FLENGTH(L) END-EXEC. output. Meaning. depending on whether the copybook is passing input. The variable FLAG indicates whether the following data is input data. An alternative to redefinitions is the use of dummy sections (see variable ERROR-STRUCTURE). No loop is necessary to process additional subroutine invocations. tend to overload. 2. the structures are redefined several times. or error data. Also. Redefinitions are necessary to work with meaningful variable names. On comparison of the two examples. Differentiation between LNAME and PNAME is only possible by using redefinitions. otherwise the name of the variable is misleading. or error information. This leads to confusion about the validity of the various fields at any particular time. EXEC CICS LINK PROGRAM(PHONETIC) CHANNEL(CHANNELNAME) END-EXEC.01 L PIC 9(8) BINARY. Application design and implementation 33 . * CHECK HERE L FOR GREATER THAN ZERO (RECORDS RETURNED) AND THAN * PROCESS THE RETURNED TABLE STARTING AT POINTER P In Example 2-7 there is no logical requirement to check the availability of records left. Example 2-8 is an expanded replica of the earlier mentioned fragment code in Example 2-1 on page 24. it can be seen that the complexity increases from one to the other. 01 CUSTOMERRECORD PIC X(800). output data.

03 PNAME REDEFINES FIELD PIC X(40). 03 EFLAG PIC X(1). DISPLAY PNAME ELSE FLAG CONTAINS UNEXPECTED VALUE. 03 FLAG PIC X(1). E = ERROR IF FLAG = 'E' THEN DO SOME ERROR PROCESSING. * * * * * * * * 34 CICS Transaction Server V3 R1 Channels and Containers Revealed . 03 LNAME REDEFINES FIELD PIC X(40). 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. 03 FIELD PIC X(40). The subroutine could be wrong. 01 MYCOMMAREA. 01 ERROR-STRUCTURE. See Example 2-8. PROCEDURE DIVISION..checking for an invalid flag is necessary. 03 EMSG PIC X(40).. CONTINUE ELSE O = OUTPUT IF FLAG = 'O' THEN PNAME SHOULD CONTAIN 'MAYR'. SET ADDRESS OF ERROR-STRUCTURE TO ADDRESS OF MYCOMMAREA . DO SOME OTHER ERROR PROCESSING. MOVE 'MEYER' TO LNAME. returning an unexpected value in this variable. CONTINUE END-IF END-IF. I = INPUT MOVE 'I' TO FLAG EXEC CICS LINK PROGRAM (PHONETIC) COMMAREA(MYCOMMAREA) END-EXEC. LINKAGE SECTION. Example 2-8 Overloaded COMMAREA: FIELD is for input as well as for output WORKING-STORAGE SECTION.

Chapter 2. 01 LNAME PIC X(40). In Example 2-9 we have expanded fragment code in Example 2-2 on page 25 by introducing an error container. Application design and implementation 35 . CONTINUE END-IF. Example 2-9 Introduction of an error container IDENTIFICATION DIVISION. you can avoid the confusion of redefinitions and dummy sections. 01 RC PIC 9(8) BINARY. 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. EXEC CICS GET CONTAINER(OUTPUTCONTAINER) INTO(PNAME) CHANNEL(CHANNELNAME) END-EXEC. because an * error container exists. 01 OUTPUTCONTAINER PIC X(16) VALUE IS 'MYOUTPTCONTAINER'. RESCC05. DATA DIVISION. Exit. 01 ERRORCONTAINER PIC X(16) VALUE IS 'MYERRORCONTAINER'. IF RC = DFHRESP(NORMAL) THEN * Do some error processing here. EXEC CICS PUT CONTAINER(INPUTCONTAINER) FROM(LNAME) CHANNEL(CHANNELNAME) END-EXEC. EXEC CICS GET CONTAINER(ERRORCONTAINER) INTO(ERRMSG) CHANNEL(CHANNELNAME) RESP(RC) END-EXEC. 01 INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. 01 PNAME PIC X(40). ENVIRONMENT DIVISION. 01 CHANNELNAME PIC X(16) VALUE IS 'MYCHANNELNAME'. EXEC CICS LINK PROGRAM (PHONETIC) CHANNEL(CHANNELNAME) END-EXEC. PROCEDURE DIVISION. The program code is more straightforward. PROGRAM-ID. WORKING-STORAGE SECTION. 01 ERRMSG PIC X(40). MOVE 'MEYER' TO LNAME.When using channels and containers.

2. and the names and number of the containers in the channel. by issuing an EXEC CICS ASSIGN CHANNEL command. This means that both client and server programs know the name of the channel. A STARTBROWSE loop is provided in Example 2-10. Example 2-10 Display all container names in a channel IDENTIFICATION DIVISION. The program can browse to get the names of the containers in its current channel. 36 CICS Transaction Server V3 R1 Channels and Containers Revealed . PROGRAM-ID. ENVIRONMENT DIVISION. END PROGRAM RESCC05. Typically. if necessary. The loop displays all container names in the channel and their lengths. meaning the channel with which it was invoked. for example. DATA DIVISION. it must discover which of the possible channels it’s been passed. this is not necessary. A program can discover its current channel. WORKING-STORAGE SECTION. A program written to handle several channels is often coded to be aware of the names and number of the containers in each possible channel.4 STARTBROWSE application programming interface Typically. the command returns blanks. RESCC04. GOBACK. programs that exchange a channel are written to handle that channel. If there is no current channel. a server program or component is written to handle more than one channel. if. use the browse commands as follows: EXEC CICS STARTBROWSE CONTAINER BROWSETOKEN(data-area) EXEC CICS GETNEXT CONTAINER(data-area) BROWSETOKEN(token) EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(token) Having retrieved the name of its current channel and. However. on invocation. To get the names of the containers in the current channel.DISPLAY PNAME. a server program can adjust its processing to suit the kind of data that it's been passed. EXEC CICS RETURN END-EXEC. the names of the containers in the channel.

IF XRESP = DFHRESP(NORMAL) THEN EXEC CICS GETNEXT CONTAINER(CONTAINERNAME) BROWSETOKEN(XTOKEN) RESP(XRESP) END-EXEC PERFORM UNTIL XRESP = DFHRESP(END) EXEC CICS GET CONTAINER(CONTAINERNAME) NODATA FLENGTH(XLENGTH) RESP(XRESP) END-EXEC DISPLAY ' CONTAINER NAME= ' CONTAINERNAME ' CONTAINER LENGTH= ' XLENGTH EXEC CICS GETNEXT CONTAINER(CONTAINERNAME) BROWSETOKEN(XTOKEN) RESP(XRESP) END-EXEC END-PERFORM EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(XTOKEN) RESP(XRESP) END-EXEC ELSE * DO SOME ERROR PROCESSING. 01 XRESP PIC 9(8) BINARY. the invoking program knows the name of the channel. EXEC CICS STARTBROWSE CONTAINER BROWSETOKEN(XTOKEN) RESP(XRESP) END-EXEC. 01 XLENGTH PIC 9(8) BINARY. PROCEDURE DIVISION. However. GOBACK. 01 XTOKEN PIC 9(8) BINARY. END PROGRAM RESCC04.01 CONTAINERNAME PIC X(16). The question to be answered is: does the returned channel contain the Chapter 2. because it is the same name used to invoke the subroutine. which has been returned. On program return. CONTINUE END-IF EXEC CICS RETURN END-EXEC. Application design and implementation 37 . it does not necessarily know the names of the containers in the channel.

channels that were passed to or created by the calling program are available to the called program. It is more efficient to perform a GET for a container. The NODATA option can be used if only one requires to know of its existence. If the calling program does not have a current channel. Failure to provide a channel name in this case causes the container-related EXEC CICS command to return an INVREQ with a RESP2=4(no current channel). and return data in channels and containers using the CICS API. Therefore. transfer. if the called program issues a container-related EXEC CICS command with no channel name specified. 38 CICS Transaction Server V3 R1 Channels and Containers Revealed . because CICS treats both the calling and called program as the same logical link level.5 Channels and containers in called subroutines In the previous sections we have discussed how to create. must specify the channel name. you require to note the importance of specifying channel name on any container-related EXEC CICS command issued in the called program. the calling program's current channel is also the called program's current channel. we recommend browsing through the channel as shown in Example 2-10. In the following section we discuss how dynamically called subroutines can participate. However. this channel is available to the called program. where the channel has been created. rather than browse through the containers. to see if it exists. if the calling program creates its own channel. or remote. This could be unpredictable. Note: Do not rely on the order in which the container names are returned. Thus. or has the subroutine deleted some or created others? In this case. any container-related EXEC CICS command that the called program issues to access this channel. because it may depend on various factors such as whether the STARTBROWSE runs local. then the called program also does not have a current channel. In this case. then the called program. 2. However.same containers as the passed channel. assumes this as the channel name. Processing containers in a called subroutine When using either a dynamic or static Common Business Oriented Language (COBOL) call. by default. If the calling program has a current channel. the calling program's current channel is assumed. Also the order could change from release to release.

Data for conversion is expected to come from Hypertext Markup Language (HTML) or Extensible Markup Language (XML).1 Data conversion with channels Applications that use channels to exchange data use a simple data conversion model. meaning. The data conversion model that a channel application uses. if a CICS Transaction Server C-language program calls a CICS Transaction Server COBOL program to pass it some containers holding character data. because both programs use Extended Binary Coded Decimal Interchange Code (EBCDIC) encoding. Chapter 2. Applications that use COMMAREAs to exchange data use the traditional data conversion model. In contrast. 2. no data conversion is required. no conversion is required and. a single programming instruction can be used to tell CICS to handle it automatically. the DFHCCNV conversion program. and subsequently convert results back to the appropriate form on return. using the DFHCNV conversion table. the data in containers that application programs create. CICS converts system data automatically when necessary. the data in channel containers is converted under the control of the application programmer. using API commands. Conversion is done under the control of the system programmer. you would require to provide the other channel's name in any container-related EXEC CICS command you use in the called program. 2. you must ensure that you always provide the correct channel name on any container-related command that you issue in a called program. is much simpler than that a COMMAREA application uses. Application design and implementation 39 . when a (non-Java) CICS Transaction Server program calls another (non-Java) CICS Transaction Server program. which is optional. Therefore. If you want to access any other channel. then the called program also has a current channel.6 Data conversion and code page conversion CICS is now able to convert received data to another encoding format. and the DFHUCNV user-replaceable conversion program. the only reason for using conversion would be the unusual one of wanting to change the coded character set identifier (CCSID) of the data. For example. Input data from any interface can be processed with suitable conversion.6. unless you wish to use the current channel.If the calling program has a current channel. when it is. The application programmer is responsible only for the conversion of user data. Frequently. apart from the current channel in the called program. Note the following: Usually. but the new function is not limited to these.

is not supported. you must put each character string of a DBCS code page into a separate container. BIT All non-character data is everything that is not designated as being of type CHAR.2 How to cause CICS to convert data automatically In the client program. As the following example shows how to put data into a container eligible for conversion: EXEC CICS PUT CONTAINER(cont_name) CHANNEL(channel_name) FROM(data1) DATATYPE(DFHVALUE(CHAR)) There is no requirement to specify the FROMCCSID option. To ensure that it is obvious that you are using DBCS and that the data conversion works correctly. for double-byte character set (DBCS) code pages this is not the case. use the DATATYPE(DFHVALUE(CHAR)) option of the put container command to specify that a container holds character data and that the data is eligible for conversion. Your applications can use the container API as a simple means of converting character data from one code page to another. CICS recognizes two types of data: CHAR Character data is a text string. The data in the container cannot be converted. 40 CICS Transaction Server V3 R1 Channels and Containers Revealed .6. since a structure consisting of several character fields can be interpreted as a single-byte character string.Containers only support the conversion of character data. The default CCSID is implied. unless FROMCCSID is specified. unless the data is not in the default CCSID of the client platform. The conversion of binary data. However. if necessary. in which case CHAR is the default. All the data in a container is converted as though it were a single character string. then this is an ASCII code page. For data conversion purposes. The API commands used for data conversion are: EXEC CICS PUT CONTAINER [CHANNEL] [DATATYPE] [FROMCCSID] EXEC CICS GET CONTAINER [CHANNEL] [INTOCCSID] 2. This is the default value. The data in the container is converted. If the application that retrieves the data is a client on an American Standard Code for Information Interchange (ASCII) based system. For single-byte character set (SBCS) code pages this is not a problem. between big-endian and little-endian. This is because DBCS code pages may consist of character strings made up of double-byte characters or a mixture of single-byte and double byte characters. to the code page of the application that retrieves it.

Application design and implementation 41 . In the following sample. Chapter 2. which may not be the case.Note: For CICS Transaction Server regions. There is no requirement to specify the INTOCCSID option unless you want the data to be converted to a CCSID other than the default. In the following example you find the get container command to retrieve the data from the program’s current channel. If client and server platforms are different. A programmer must use SET. If the client and server platforms are different. data conversion takes place automatically. data conversion takes place automatically. the client program issues a get container command to retrieve the status returned by the server program. Get the data from a container and convert it automatically as shown: EXEC CICS GET CONTAINER(status) CHANNEL(channel_name) INTO(status_area) Note: We have used INTO for the get commands for code page conversion. if length of the data returned is not known. you can see that the server program issues a put container command to return a value to the client. Data retrieved from a container is automatically converted as the following shows: EXEC CICS GET CONTAINER(cont_name) INTO(data_area1) The way back is exactly the same. This is logical when you know exactly how much data is being returned. Put data in a container and make the data eligible for conversion as follows: EXEC CICS PUT CONTAINER(status) FROM(data_area2) CHAR In the example that follows. There is no requirement to specify the INTOCCSID option unless you want the data to be converted to a CCSID other than the default. For DATATYPE(DFHVALUE(CHAR)) you can specify CHAR. The status is returned in the default CCSID of the client platform. The data is returned in the default CCSID of the server platform. the default CCSID is specified in the LOCALCCSID system initialization parameter.

use a temporary channel. When using the container API in this way. copy the converted data and delete the container. Retrieves an Unicode Transformation Format 8 (UTF8) or UTF16 message from a socket or MQ message queue.6. Puts EBCDIC data structures into other containers on the same channel. 42 CICS Transaction Server V3 R1 Channels and Containers Revealed . Puts the message into a container in UTF8 format.6. but no data is returned. Makes a distributed program link (DPL) call to a handler program. on a back-end application-owning region (AOR). note the following: To avoid a storage overhead after conversion. 3. 2. unless the converted length is known. The length of the output data is calculated. EXEC CICS PUT CONTAINER(temp) CHAR FROMCCSID(codepage1) FROM(inputdata) END-EXEC EXEC CICS GET CONTAINER(temp) INTOCCSID(codepage2) SET(data-ptr) FLENGTH(data-len) END-EXEC Figure 2-1 Code page data converter The input data length can differ from the output data length. passing the channel.2. To avoid shipping the channel. All-to-all conversion is not possible. rather than the INTO option (move mode).4 SOAP example A CICS Transaction Server SOAP application: 1. We recommend that you use the SET option (locate mode). Figure 2-1 converts data from codepage1 to codepage2. 4.3 Using containers to do code page conversion Your application can use the container API as a simple means of converting character data from one code page to another. 2. This means that a code page conversion error occurs if a specified code page and the channel’s code page are an unsupported combination. You can issue a get container with the NODATA and FLENGTH option to retrieve the length of the converted data.

In this case CHAR can be omitted. no conversion is possible. which is the default. It can get the message in UTF8. To retrieve one of the messages in the region’s EBCDIC code page. the handler can issue the following command to put data into a container default CCSID: EXEC CICS PUT CONTAINER(output) FROM(output_msg) Because CHAR is not specified. or in its own EBCDIC code page. no data conversion is permitted. in UTF8. Because the FROMCCSID option is not specified. Similarly. the handler can issue the following command to get data from a container in the default CCSID: EXEC CICS GET CONTAINER(input_msg) INTO(msg) Because the INTOCCSID option is not specified. forces the insertion of data as type CHAR. Specifying FROMCCSID.The back-end handler program. or EBCDIC. the message data is selected to be in the region’s EBCDIC code page. the server program can issue the following command to specify a CCSID on returning the data: EXEC CICS PUT CONTAINER(output) FROM(output_msg) FROMCCSID(utf8) The FROMCCSID option specifies that the message data is currently in UTF8 format. also running on CICS Transaction Server. the handler can issue the following command to retrieve the data and convert it: EXEC CICS GET CONTAINER(input_msg) INTO(msg) INTOCCSID(utf8) The INTOCCSID option is necessary to prevent automatic conversion of the data to the region’s EBCDIC code page. or the region’s EBCDIC code page. Application design and implementation 43 . can use the EXEC CICS GET CONTAINER command to retrieve the EBCDIC data structures or messages. it can use EXEC CICS PUT CONTAINER commands to place data into the containers. To return output to the region’s EBCDIC code page. UTF16. This assumes that the put container command used to store the message data in the channel specified is a DATATYPE of CHAR. the message data is automatically converted to the region’s EBCDIC code page. If it specified a DATATYPE of BIT. To return some output in UTF8. To retrieve one of the messages in UTF8. Chapter 2. or UTF16.

if you want to externalize a file from an EBCDIC code page to an ASCII file. note that some older CICS InfoCenter versions specify you to use a decimal fullword for the variable. do not use the following: 01 ASCIICODEPAGE PIC 9(7) PACKED-DECIMAL VALUE 858 Instead. which is an incorrect procedure. So. The following command converts the container from the current local EBCDIC code page to ASCII: EXEC CICS GET CONTAINER(containername) CHANNEL(channelname) INTO(data-area2) INTOCCSID(858) Note: You can specify the CCSID directly or you can specify a variable containing the CCSID. In this case. To read the file records in the region’s EBCDIC code page. The FROMCCSID has been omitted. In Common Business Oriented Language (COBOL) that means. for example. Write a TD queue to externalize the file in ASCII format. the program can issue the following command: EXEC CICS READ FILE(filename) INTO(data-area1) RIDFLD(keydata-area) Copy the data and move the record into a container and make it eligible for conversion: EXEC CICS PUT CONTAINER(containername) CHANNEL(channelname) FROM(data-area1) CHAR The CHAR option specifies that the container holds character data and that the data is eligible for conversion. its easy to use the channels and containers.6. the region’s default CCSID is implied. for example. Put the EBCDIC data into a container. You must use a binary fullword. 3. 4. Read a VSAM KSDS file with client records.5 File example A CICS Transaction Server file application: 1. 2. Get the data from the container in ASCII format.2. you can use the following: 01 ASCIICODEPAGE PIC 9(8) BINARY VALUE 858 44 CICS Transaction Server V3 R1 Channels and Containers Revealed . The file interface has no code page conversion capabilities.

Application design and implementation 45 . because this terminates CECI and the current unit-of-work (UOW). Chapter 2.Figure 2-2 shows an example of how to use a variable for INTOCCSID. . 01 ASCIICODEPAGE pic 9(8) BINARY. MOVE 858 TO ASCIICODEPAGE EXEC CICS GET CONTAINER(containername) CHANNEL(channelname) INTO(data-area2) INTOCCSID(ASCIICODEPAGE) Figure 2-2 Use a variable to hold the code page number The following command is to externalize the ASCII record to a transient data (TD) queue file: EXEC CICS WRITEQ TD QUEUE(queuname) from(data-area2) 2. therefore simply overwrite the CECI input string. A new session does not have access to the container. Do not press PF3 after putting the data into a container with CECI.6 Command-level interpreter CICS-supplied transaction example Use command-level interpreter CICS-supplied transaction (CECI) to put EBCDIC data into a container and receive the container in ASCII.6.

In Figure 2-3 you can see how to put that data into a container and what the CICS system returns. CECI PUT CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) FROM(12345) CHAR returns: PUT CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) FROM(12345) CHAR STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS PUT COntainer( 'TEMP ' ) < ACTivity() | ACQActivity | Process | ACQProcess | CHANnel( 'MYCHANNELNAME ' ) > FROM( '12345' ) < FLength( +0000000005 ) > < Datatype() | Bit | CHAR > < FROMCcsid() > in hex: PUT CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) FROM(12345) CHAR STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS PUT COntainer( X'E3C5D4D7404040404040404040404040' ) < ACTivity() | ACQActivity | Process | ACQProcess | CHANnel( X'D4E8C3C8C1D5D5C5D3D5C1D4C5404040' ) > FROM( X'F1F2F3F4F5' ) < FLength( X'00000005' ) > < Datatype() | Bit | CHAR > < FROMCcsid() > Figure 2-3 Put x’F1F2F3F4F5’ into a container 46 CICS Transaction Server V3 R1 Channels and Containers Revealed .

you require to pay attention to: DSA size – Using big containers require big DSAs – SOS conditions can arise Chapter 2.' ) | Nodata ) < Flength( +0000000005 ) > < INTOCcsid( +0000000858 ) > in hex: GET CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) INTO(&OUT) INTOCCSID(858) STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS GET CONtainer( X'E3C5D4D7404040404040404040404040' ) < ACTivity() | ACQActivity | Process | ACQProcess | Channel( X'D4E8C3C8C1D5D5C5D3D5C1D4C5404040' ) > ( Set() | INTO( X'3132333435' ) | Nodata ) < Flength( X'00000005' ) > < INTOCcsid( X'0000035A' ) > Figure 2-4 Get container returns ASCII digits x’3132333435’ Note: Replacing a container with a different data type is not possible.. Also. GET CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) INTO(&OUT) INTOCCSID(858) returns: GET CONTAINER(TEMP) CHANNEL(MYCHANNELNAME) INTO(&OUT) INTOCCSID(858) STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS GET CONtainer( 'TEMP ' ) < ACTivity() | ACQActivity | Process | ACQProcess | Channel( 'MYCHANNELNAME ' ) > ( Set() | INTO( '.In Figure 2-4 you can see that CICS returns the ASCII representation of the digits ‘12345’.. 2.7 Storage When using channels and containers with sizes significantly above 32 KB. you cannot replace a container using different CCSIDs... Application design and implementation 47 .

Performance When an EXEC CICS LINK is shipped over an intersystem communication (ISC) connection and a big container is specified. COMMAREAs are shared storage between programs. except in certain circumstances. The default routing program for CICS is DFHDYP. Data location You must read any programs with data location that cannot receive containers greater than 16 MB. Application programming and systems programming must mutually agree on the header information. 48 CICS Transaction Server V3 R1 Channels and Containers Revealed . it can lead to queuing in the CICS system. Shipping big containers over ISC links can take a significant amount of time. If you use CICSPlex System Manager. Queueing If links are busy in transmitting big containers.AMODE A program running in AMODE 24 cannot receive containers greater than 16 MB. it can lead to performance issues. such as programs with different keys and amodes. The storage model for containers is different to that of COMMAREAs. it is mandatory to use EYU9XLOP as the routing program. The normal procedure you can use to do this is if you provide additional system related information in a header. Containers are a new API that convert programs to above the line. therefore there is only one copy of the data. which gets control for every transaction or program defined as dynamic to CICS. therefore it can read the header information and make a routing decision based on this information. The application program places the header at the top of the COMMAREA before the application data. The systems programmer provides a user-replaceable module. the working storage of each of the programs. Note: Do not use containers below the line. 2.8 Dynamic routing application considerations You may require to dynamically route workload based on information in the COMMAREA. This module has access to the COMMAREAs. For container storage. there are three copies of the data. and CICSs copy of the container.

user ID. and so on. M Meyer A-M AOR1 TOR1 RE02 Meyer M Meyer N Norbert DFHDYP or EYU9XLOP N Norbert N-Z AOR2 Figure 2-5 DFHDYP or EYU9XLOP influence the AOR selection The example application has a 40 byte name as input. Figure 2-5 shows the smallest system configuration for the dynamic routing environment. If the first character in the name falls between A and M. But this is not good in practice. at least two AORs connected to a terminal-owning region (TOR). and the routing exit can directly access the application data. terminal information. otherwise AOR2 is selected. timestamps. Application design and implementation 49 . 2. because the routing exit must know all the Chapter 2. but is a more simple example based on the previously introduced phonetic application. and a 40 byte phonetically translated name as output. prefix the application data with the header.An application header could have information for lengths. AOR1 is eligible for routing. The dynamic routing exit has access to the COMMAREA. we have a one byte header.8. and also as an option. application information. Additionally. password information. The exit influences the routing decision based on this header.1 COMMAREA In the COMMAREA solution. Note that in this simple example you can avoid the header. which is the first character of the name. The CICS system provides the address of the COMMAREA to the exit. Following is an example that does not provide a complete header.

to get back an output container. PROGRAM-ID. * PNAME CONTAINS 'MAYR'. PROCEDURE DIVISION.2 Channel When using a channel Example 2-11 looks slightly different. The mandatory name of this container is DFHROUTE. 01 MYCOMMAREA. EX211. The routing decision is made based on the content in this container. the channels and containers API is not valid in this context and EXEC CICS GET CONTAINER returns an invalid request comment. Therefore. DISPLAY PNAME. 2. In our example. we recommend you to separate the data in different containers. 03 LNAME PIC X(40). In Example 2-11 you can see the COMMAREA instance. GOBACK. MOVE 'MEYER' TO LNAME. 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. “Systems management and configuration” on page 89. we create an input container and a container for routing information in one channel. EXEC CICS LINK PROGRAM (PHONETIC) COMMAREA(MYCOMMAREA) END-EXEC. Therefore.structures of all the applications. On the EXEC CICS LINK we provide the channel name. EXEC CICS RETURN END-EXEC. However. The container data has to be available to the routing program.8. This exit has direct access to the DFHROUTE container only. END PROGRAM EX211. DATA DIVISION. 03 HEADER PIC X(1). 50 CICS Transaction Server V3 R1 Channels and Containers Revealed . we use a header. the routing exit gets control. Example 2-11 Provide a header in the COMMAREA for the dynamic routing program IDENTIFICATION DIVISION. ENVIRONMENT DIVISION. For further information about DFHROUTE refer to Chapter 4. As previously mentioned. Because the subroutine is defined as dynamic. Therefore. WORKING-STORAGE SECTION. the container data must be put in a special container that the routing program can read. 03 PNAME PIC X(40). put the name in an input container.

01 CHANNELNAME PIC X(16) VALUE IS 'MYCHANNELNAME'. WORKING-STORAGE SECTION. EX212. 01 INPUTCONTAINER PIC X(16) VALUE IS 'MYINPUTCONTAINER'. Note: The name of the container including the routing information must be DFHROUTE. PROCEDURE DIVISION. END PROGRAM EX212. DATA DIVISION. The routing exit has access to the DFHROUTE container but no access to other containers. EXEC CICS PUT CONTAINER(INPUTCONTAINER) FROM(LNAME) CHANNEL(CHANNELNAME) END-EXEC. PROGRAM-ID. 01 LNAME PIC X(40).In Example 2-12. MOVE 'MEYER' TO LNAME. 01 OUTPUTCONTAINER PIC X(16) VALUE IS 'MYOUTPTCONTAINER'. Example 2-12 Provide the header in a DFHROUTE container IDENTIFICATION DIVISION. 01 ROUTINGCONTAINER PIC X(16) VALUE IS 'DFHROUTE'. ENVIRONMENT DIVISION. EXEC CICS RETURN END-EXEC. GOBACK. you can find the code necessary to create the DFHROUTE container. EXEC CICS LINK PROGRAM (PHONETIC) CHANNEL(CHANNELNAME) END-EXEC. EXEC CICS PUT CONTAINER(ROUTINGCONTAINER) FROM(ROUTEINFO) CHANNEL(CHANNELNAME) END-EXEC. 01 PNAME PIC X(40). 01 ROUTEINFO REDEFINES LNAME PIC X(1). Chapter 2. 01 PHONETIC PIC X(8) VALUE IS 'PHONETIC'. EXEC CICS GET CONTAINER(OUTPUTCONTAINER) INTO(PNAME) CHANNEL(CHANNELNAME) END-EXEC. Application design and implementation 51 .

if a container has changed. Input containers whose contents have been changed by the server program. because read-only containers sent to a server region is not returned. 52 CICS Transaction Server V3 R1 Channels and Containers Revealed . They include and expand on the recommendations for achieving optimal DPL performance. it is necessary for CICS to ship its contents back to the calling region. are returned. making your programs easier to understand. must create the output containers. At the end of a DPL call. make it a separate container. for optimal DPL performance: Use separate containers for input and output data. Use separate containers for read-only and read-write data. – Avoidance of the problems with REORDER overlays. 2. making your programs easier to maintain. not the client.2. Use dedicated containers for error information. Use separate containers for read-only and read-write data. If the client program has any large containers that the server program does not require.9 Best practices This chapter provides a discussion of the best practices when using channels and containers. Use separate containers for input and output data. The server program. The following are some general hints on designing a channel.1 Designing a channel It is possible to use containers to pass data in the same manner as COMMAREAs have traditionally been used. However. channels have several advantages over COMMAREAs and it is advantageous to design your own channels to make the most of these improvements. and containers created by the server program. This leads to: – Better encapsulation of the data. Use MOVE to move the containers between the current channel and the channel passed to the server. If a structure is optional. Do not initialize containers in a client program if the server program does not require the data as input data. Therefore. use a separate channel for the DPL request. – Greater efficiency when a channel is passed on a DPL call. – Greater transmission efficiency between CICS regions.9. because smaller containers flow in each direction. This leads to: – A simplification of your copybook structure.

– The ability to pass a subset of the channel to subcomponents if you use the move container command to move containers between channels. passing a large amount of data may affect performance. This leads to: – Better documentation of what is error information. because you do not require to recompile the entire component. Chapter 2. make it a separate container. binary data and character data. connection. Do not create too many large containers. rather than multiregion operation (MRO). use separate containers for each type. When you require to pass data of different types. This is particularly true if the local and remote regions are connected by an ISC. – Greater ease in changing one of the structures. If a structure is optional. because it limits the amount of storage available to other applications. When you require to pass a large amount of data. 2. It is more efficient to check for the presence of an error container if you issue a get container (known-error-container-name) command and possibly receiving a NOTFOUND condition. for example. rather than one container with a complicated structure. you require to move the data to a container and connect the container to a channel. Note that the channel and container names are case sensitive. MyChannel differs from mychannel and MYCHANNEL. divide it between multiple containers. This improves your ability to move between different code pages. rather than putting it all in one container. For example. Use dedicated containers for error information. – Greater efficiency. This leads to greater efficiency. Therefore. When a channel is passed to a remote program or transaction.2 Naming a channel Before linking to the subprogram.Use separate containers for each structure. than it is to initiate a browse of the containers in the channel.9. putting a container into MyChannel and then linking to a program with a container name of mychannel does not give error messages during compile. because the structure is passed only if the container is present. Application design and implementation 53 . This leads to: – Better encapsulation of the data. making your programs easier to understand and maintain. but may lead to unexpected results when you run the program. because: • • The structure containing the error information is passed back only if an error occurs.

container or channel names included in quotes. 2. “Benefits of using channels and containers” on page 19. If you employ a user-written dynamic or distributed routing program for workload management. Migrating existing functions You require to take the following points into consideration: CICS application programs that use traditional COMMAREAS to exchange data continue to work as before. We do not recommend this practice. a new channel is created and transferred to the subroutine without any containers. rather than CICSPlex(R) System Manager.1.3 Migrating from COMMAREAs to channels The following sections discuss the various processes of migration from COMMAREAs to channels.CICS creates a new channel on first reference.5. To avoid this pitfall. Channels have several advantages over COMMAREAs. 54 CICS Transaction Server V3 R1 Channels and Containers Revealed . You must implement the best practices for channels and containers. Refer to the CICS Transaction Server for z/OS V3. “Designing a channel” on page 52. for example. Instead move the channel name and the container name into a previously defined variable that you can use in the API.1 CICS Customization Guide.9. because you are taking the time to change your application programs to exploit this new function. Refer to 2. It is advantageous to design your channels to make the most of these improvements. SC34-6429. This means that if there is a typo in the channel name specified on the ECEC CICS LINK command. you must modify your program to handle the new values that it may be passed in the DYRTYPE field of the DFHDYPDS communications area. even though it may seem to be the simplest means to move from COMMAREAs to channels and containers.9. Refer to 1. This ensures that your channel or container name is always correct. we recommend that you do not use strings. Migrating to the new function This section describes how you can migrate several types of existing application to use channels and containers rather than COMMAREAs. It is possible to replace a COMMAREA with a channel that consists of a single container.

. EXEC CICS GET CONTAINER(contr-name) CHANNEL(channel-name) INTO(structure) PROG2 EXEC CICS ADDRESS COMMAREA(structurePtr) . has to only issue a return command to return the data to PROG1. having put data in the COMMAREA. . PROG2. . Table 2-1 Migrating link commands that pass COMMAREAs Program PROG1 Before EXEC CICS LINK PROGRAM(PROG2) COMMAREA(structure) After EXEC CICS PUT CONTAINER(contr-name) CHANNEL(channel-name) FROM(structure) EXEC CICS LINK PROGRAM(PROG2) CHANNEL(channel-name) .. PROG2 must issue a put container command before the return.. Chapter 2. change the instructions as shown in Table 2-1. RETURN EXEC CICS GET CONTAINER(contr-name) INTO(structure) . to return data.Migrating link commands that pass COMMAREAs To migrate two programs. EXEC CICS PUT CONTAINER(contr-name) FROM(structure) EXEC CICS RETURN Note: In the COMMAREA example. Application design and implementation 55 . In the channel example.. to exchange a structure. which use a COMMAREA on a link command.

which use a COMMAREA on an xctl command. Table 2-2 Migrating xctl commands that pass COMMAREAs Program PROG1 Before EXEC CICS XCTL PROGRAM(PROG2) COMMAREA(structure) After EXEC CICS PUT CONTAINER(contr-name) CHANNEL(channel-name) FROM(structure) EXEC CICS XCTL PROGRAM(PROG2) CHANNEL(channel-name) PROG2 EXEC CICS ADDRESS COMMAREA(structurePtr) EXEC CICS GET CONTAINER(contr-name) INTO(structure) Migrating pseudo-conversational transactions COMMAREAs To migrate two programs. change the instructions shown in Table 2-3. which use COMMAREAs to exchange a structure.Migrating xctl commands that pass COMMAREAs To migrate two programs. as part of a pseudo-conversation. change the instructions as shown in Table 2-2. Table 2-3 Migrating pseudo-conversational COMMAREAs on return command Program PROG1 Before EXEC CICS RETURN TRANSID(TRAN2) COMMAREA(structure) After EXEC CICS PUT CONTAINER(contr-name) CHANNEL(channel-name) FROM(structure) EXEC CICS RETURN TRANSID(TRAN2) CHANNEL(channel-name) PROG2 EXEC CICS ADDRESS COMMAREA(structurePtr) EXEC CICS GET CONTAINER(contr-name) INTO(structure) 56 CICS Transaction Server V3 R1 Channels and Containers Revealed . to pass a structure.

The routing program is given in the DYRACMAA field of its communication area. which are handled by the distributed routing program. which is the name of the Chapter 2. For link requests and transactions. Note: The routing programs communication area is mapped by the DFHDYPDS DSECT. Table 2-4 Migrating start data Program PROG1 Before EXEC CICS START TRANSID(TRAN2) FROM(structure) After EXEC CICS PUT CONTAINER(contr-name) CHANNEL(channel-name) FROM(structure) EXEC CICS START TRANSID(TRAN2) CHANNEL(channel-name) PROG2 EXEC CICS RETRIEVE INTO(structure) EXEC CICS GET CONTAINER(contr-name) INTO(structure) Note: The new version of PROG2 is the same as that in the pseudo-conversational example. the address of the application's COMMAREA. Migrating of dynamically-routed applications EXEC CICS LINK and EXEC CICS START commands. If you migrate a dynamically-routed EXEC CICS LINK or EXEC CICS START command to use a channel rather than a COMMAREA. which terminal-related start requests begin are handled by the dynamic routing program. the routing program is passed in the DYRCHANL field of DFHDYPDS.Migrating start data To migrate two programs. which can pass either COMMAREAs or channels. inspect or change the COMMAREA's contents. change the instructions as shown in Table 2-4. depending on the type of request. and can inspect and change its contents. can be dynamically routed. which use start data to exchange a structure. When a link or start command passes a COMMAREA rather than a channel. Application design and implementation 57 . The same rule is not valid for non-terminal-related start requests. the routing program can.

and so is unable to use the DYRCHANL field to inspect or change the contents of the channel's containers. a special container named DFHROUTE. the dynamic routing program is given in the DYRACMAA field of DFHDYPDS. “Systems management and configuration” on page 89. within the channel.channel. This rule is not valid for a non-terminal-related start request. you could use its existing COMMAREA structure to map DFHROUTE. the address of the DFHROUTE container. Note that the routing program is given the name of the channel. an application that uses a channel can create. and can inspect and change its contents. If you are migrating a program to pass a channel rather than a COMMAREA. not its address. To give the routing program the same kind of functionality with channels. Refer to Chapter 4. 58 CICS Transaction Server V3 R1 Channels and Containers Revealed . If the application issues a link or terminal-related start request that is to be dynamically routed.

59 . It also discusses business transaction services (BTS) API as a similar but recoverable alternative to channels and containers. All rights reserved. Programming This chapter discusses the channels and containers application programming interface (API) and how you can use it in a traditional Customer Information Control System (CICS) application and also a CICS Java (JCICS) application. which enable further flexibility of Web service features through the use of channels and containers. This chapter introduces some authorized program analysis reports (APARs).3 Chapter 3. © Copyright IBM Corp. 2006.

Inserting data as character (CHAR) or binary (BIT) has an important difference.1 EXEC CICS application programming interface CICS provides a set of API commands that you can use to perform actions in channels and containers.ibm. The following sections discuss the various actions that you can perform using the API and some of the nuances they involve.boulder. Instead.com/infocenter/cicsts/v3r1/index. then it is created and the data inserted. You can use this with link. start. refer to the CICS Transaction Server for z/OS V3. The length of a container is specified using the FLENGTH parameter. If the container named on the command does not exist.1. or xctl command. which you have the option to omit if the compiler is able to determine the size of the data area being inserted into the container. Character data is susceptible to code page conversion and binary data is not.1 information center at: http://publib. Example 3-1 Creating a channel EXEC EXEC EXEC EXEC EXEC EXEC CICS CICS CICS CICS CICS CICS LINK PROGRAM CHANNEL MOVE CONTAINER CHANNEL TOCHANNEL PUT CONTAINER CHANNEL RETURN TRANSID CHANNEL START TRANSID CHANNEL XCTL PROGRAM CHANNEL Note: If the named channel does not exist on a link. 60 CICS Transaction Server V3 R1 Channels and Containers Revealed .1.jsp 3. Example 3-1 shows a set of commands that instantiates a named channel if it does not already exist. an instance of a channel is implicitly created when performing certain commands. then an empty channel is created and passed to the program. Its contents are overwritten if the container already exists. Note: For a detailed breakdown of the EXEC CICS API.2 Placing data in a container The put container command is used to add data to a container. as a location to place values that are to be returned from the linked to the program. 3.1 Creating a channel There is no explicit EXEC CICS API command for creating an instance of a channel.3. return.

As Example 3-2 shows that you can use DATATYPE(DFHVALUE(CHAR)) instead of CHAR. Put container CHAR Example 3-2 shows character data being put into a container with the Extended Binary Coded Decimal Interchange Code (EBCDIC) code page specified with the FROMCCSID(037) parameter. the data converts to the new code page before being given to the application. CHAR data may get converted to an alternative code page or coded character set identifier (CCSID). then the put command uses the value of the LOCALCCSID SIT parameter for the data’s code page. to the same container. in a subsequent PUT. As Example 3-3 shows that you can use DATATYPE(DFHVALUE(BIT)) instead of BIT. then the default behavior is to insert it as BIT unless you specify the FROMCCSID. Chapter 3. If LOCALCCSID is not set then the value 037 (US EBCDIC) is used. such that. This means that if you specify a different FROMCCSID value. Note: If CHAR is specified and FROMCCSID is not. After you insert a character data into a container. Example 3-3 shows how you can insert binary data into a container. if it is extracted with an alternative CCSID specification.Data inserted as BIT means it remains untouched during its life in the container. Programming 61 . Put container BIT The FROMCCSID parameter is not applicable to containers of BIT type and an INVREQ response is returned if you attempt to use it. On the other hand. then the data is converted to that of the original data’s CCSID. Note: If neither CHAR nor BIT is specified on a put container command. and the old data is overwritten. Example 3-3 Putting binary data into a container EXEC CICS PUT CONTAINER(‘ACCOUNT-NO’) CHANNEL(‘ACCOUNT-DATA’) FROM(ACCOUNT-NO) FLENGTH(LENGTH OF ACCOUNT-NO) BIT END-EXEC. its CCSID value is unchangeable. Example 3-2 Putting character data into a container with CCSID 037 EXEC CICS PUT CONTAINER(‘USER-ID’) CHANNEL(‘ACCOUNT-DATA’) FROM(USER-ID) FLENGTH(LENGTH OF USER-ID) CHAR FROMCCSID(037) END-EXEC. The CCSID value is stored alongside the data.

it is useful to understand the scope of channels as they move around. We discuss this in detail in Chapter 2. the region the data is extracted from is running on the same code page as that which inserted the data. If the new program alters any content in the container’s of the channel. then the resulting changes are reflected in the channel when it is returned to the controlling program. Because control is never given back to the calling program. 3. The example shows the passing of a channel on an xctl command: EXEC CICS XCTL PROGRAM('MY-PROG') CHANNEL(‘ACCOUNT-DATA’) END-EXEC. the facility to pass a channel also exists. This increases the portability of your applications and allow you to deploy them on different regions with different code pages. Xctl channel When transferring control to another program.You can insert a character data into a container as BIT. If the region has an alternative code page then the character data may be unrecognizable when it is extracted. you can pass a channel to the new program.3 Passing a channel to another program or task Similar to the process that you use to pass communication areas (COMMAREAs) to programs or tasks. “Application design and implementation” on page 23. you can pass a channel to the next transaction to be executed. Note: You must always insert character data as CHAR and binary data as BIT. as long as. which is similar to that of a COMMAREA. Return channel For pseudo-conversational programming. The example shows the linking of a program with a channel: EXEC CICS LINK PROGRAM('MY-PROG') CHANNEL(‘ACCOUNT-DATA’) END-EXEC.1. 62 CICS Transaction Server V3 R1 Channels and Containers Revealed . Link channel You can pass a channel on a link request using the same process you use to pass a COMMAREA. This is applicable to programs that run either locally or remotely. The example shows the passing of a channel in a pseudo-conversational program: EXEC CICS RETURN TRANSID(‘ABCD’) CHANNEL(‘ACCOUNT-DATA’) END-EXEC. When passing channels to other programs or tasks. any channels that it had access to goes out of scope and the storage is freed.

return. xctl. Programming 63 .3. this means that any changes which are made to this new channel are not reflected back in the original channel as it goes out of scope of the original program. Example 3-4 Adding a container to the current channel EXEC CICS PUT CONTAINER('ACCOUNT-NO') FROM(ACCOUNT-NO) FLENGTH(LENGTH OF ACCOUNT-NO) END-EXEC. If the current channel did not exist. The example shows a channel passing on a start call: EXEC CICS START TRANSID(‘ABCD’) CHANNEL(‘ACCOUNT-DATA’) END-EXEC. Also although the start command may not start the new transaction until after the current transaction finishes. then you can use the assign channel command: EXEC CICS ASSIGN CHANNEL(CHANNEL-NAME) END-EXEC. The channel is a copy at the time you issue the start command. The channel being passed is copied along with its containers and placed into another channel with the same name given to the program.1. If the channel specified on a link. Example 3-4 shows data being put into a container in the current channel. it is called the current channel. 3. or start does not already exist. any subsequent changes to containers are not reflected in the copy of the channel. then an empty one is created and passed to the program. “Passing a channel to another program or task” on page 62. but not both. If you require the name of the current channel for use on the previously discussed commands in 3. The value is set to blanks if no current channel exists.Start channel While starting a new task. then the command would fail with an INVREQ response. you can pass one or the other. you can pass a channel to the newly executing program.1. The application owns this channel and can use it without explicitly referencing its name. Chapter 3. Note: Key points about passing channels to programs or tasks are: COMMAREAs and channels are mutually exclusive.4 Receiving the current channel When a channel is passed to a program. without the channel parameter.

1. “Passing a channel to another program or task” on page 62. If the container has character data on a different code page in comparison to that with which it is being extracted. if INTOCCSID is not used when extracting character data. This enables you to check if the size of the data area that you have is sufficient for the converted data or not. it sets the field specified in FLENGTH to the length of the container data that you can retrieve. then the value specified in the LOCALCCSID SIT parameter is used. you can use the current channel. Example 3-5 shows a get container NODATA call on a container holding character data. Observe: When using any of the commands in 3. have the container code allocate storage for you and get it to return the address.5 Getting data from a container The get container command is used to retrieve data from a container. then the value 037 (US EBCDIC) is used. NODATA does not return the container contents in the get container command. instead. Note: Similar to put container. 3. it passes nothing at all. If LOCALCCSID is not set.Note: You can reference the current channel explicitly. Get container NODATA As the parameter name suggests.1. Example 3-5 Using NODATA to get the size of character data in a container EXEC CICS GET CONTAINER(‘USER-ID’) NODATA FLENGTH(DATA-LEN) INTOCCSID(037) END-EXEC. omitting the channel option does not cause the program or task to pass to the current channel.3. 64 CICS Transaction Server V3 R1 Channels and Containers Revealed . if you specify its name in the channel parameter on any channel supported command. Because a channel is not specified. or simply query the size of the container. Instead. This is all done through slight variations of the get container command. then the data first converts to the new code page and then the converted data length is returned. You can place the data into an existing piece of storage.

With this approach the FLENGTH parameter has the following two purposes: On input. Large character containers that require CCSID conversion can use a large amount of SET storage. The INTOCCSID option is not specified. for the same container in the same channel. it specifies the maximum size of the data that can be put into the supplied data area. The returned storage is internally managed. it holds the size of the data that was returned in the request. because it is not applicable to binary data. FLENGTH is optional depending on the compiler’s ability to determine the length of the field specified in the INTO parameter. a MOVE. Note: Each container has its own SET storage. the get container SET command dynamically allocates a piece of storage to place the container’s contents. then a LENGERR response is given to signify that the retrieved data was truncated. issues a subsequent get container command with the SET option. Get container SET For greater flexibility while working with varying length data sizes. On output. When a move container command moves the container. For example. or some forms of GET. which could change the contents of the channel. Example 3-6 shows a get container INTO command to extract binary data. When the channel goes out of program scope. or until you issue a command against that channel. Chapter 3. If the available data in the container is greater than the value specified in FLENGTH. DELETE. PUT. and therefore you cannot depend on it to exist indefinitely. Programming 65 . When a delete container command deletes the container. Situations where the data can no longer be guaranteed to exist are: When any program that can access this storage. This remains until the channel goes out of scope.Get container INTO The INTO parameter is used to retrieve the container contents and place it in an existing data area. Example 3-6 Getting the contents INTO an existing storage area EXEC CICS GET CONTAINER('ACCOUNT-NO') INTO(DATA-AREA) FLENGTH(DATA-LEN) END-EXEC. The address of the allocated storage is returned in the field specified on the SET parameter.

Example 3-8 shows you how to obtain the browse token for browsing a channel. 66 CICS Transaction Server V3 R1 Channels and Containers Revealed . Example 3-7 shows a get container set command using a pointer to hold the address of the extracted data.6 Browsing the current channel In situations where you get a channel. Example 3-7 Obtaining the address of storage representing the container contents EXEC CICS GET CONTAINER('USER-ID') SET(DATA-PTR) FLENGTH(DATA-LEN) END-EXEC. A browse token is returned in the field specified on the BROWSETOKEN parameter. Use this parameter to perform the browse on the channel. because storage management is handled internally. STARTBROWSE container You can initiate a browse on a channel using the STARTBROWSE CONTAINER command. you can perform a browse on the channel to get back the name of each container. because there is no guarantee that it exists for any prolonged period of time. then an attempt is made to browse the current channel. Important: Data is always inserted and retrieved from containers by copy. If the channel parameter is not specified.1.The FLENGTH is an output-only parameter with the SET command. If your application requires to store the data. 3. The length of the data returned is stored in the field given to it. it must move it into its own storage. but do not know what containers it has or even how many of them there are. if you want to update a container’s contents. then you must perform a put container after the original get container. The following points are important to note when using the SET option: Do not issue a FREEMAIN command to release this storage. even with a SET command. An ACTIVITYERR response is returned if no current channel exists. Example 3-8 Initiating a browse on a channel EXEC CICS STARTBROWSE CONTAINER CHANNEL('ACCOUNT-DATA') BROWSETOKEN(TOKEN) END-EXEC. Therefore.

Each container name is returned only once and there is no guarantee of the order they are in. Chapter 3.GETNEXT container After receiving the browse token. When all container names have been returned. iterates all the container names giving you something like Example 3-10. because the browse token signifies the particular channel that you are browsing. the browse token is passed to an ENDBROWSE CONTAINER call. You do not require to specify the channel name on the command. Combining all the previous commands together and wrapping the GETNEXT CONTAINER call in a loop. each GET NEXT CONTAINER call inserts the name of a container into the field specified on the container parameter. Example 3-9 Getting the next container name in a channel EXEC CICS GETNEXT CONTAINER(DATA-AREA) BROWSETOKEN(TOKEN) RESP(WS-RESP) END-EXEC. PERFORM WITH TEST AFTER UNTIL WS-RESP NOT EQUAL DFHRESP(NORMAL) EXEC CICS GETNEXT CONTAINER(DATA-AREA) BROWSETOKEN(TOKEN) RESP(WS-RESP) END-EXEC DISPLAY 'Container name: ' DATA-AREA END-PERFORM. Programming 67 . you can use it with a get container command to retrieve the container’s contents. as the example shows: EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(TOKEN) END-EXEC. Example 3-10 Browsing the containers in a channel EXEC CICS STARTBROWSE CONTAINER CHANNEL('ACCOUNT-DATA') BROWSETOKEN(TOKEN) END-EXEC. it is used to move through the list of containers in the channel. an END response condition is given. After you have a container name. EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(TOKEN) END-EXEC. ENDBROWSE container To signify the browse has finished. Example 3-9 shows a GET NEXT CONTAINER call using the browse token.

because the original container no longer exists. so that you can minimize the amount of data being transferred. 68 CICS Transaction Server V3 R1 Channels and Containers Revealed . it is created. 3. If you attempt to move a container within the same channel. it is created.1. Example 3-11 Deleting a container from a channel EXEC CICS DELETE CONTAINER('ACCOUNT-NO') CHANNEL('ACCOUNT-DATA') END-EXEC. because an internal optimization facilitates only that particular data that changes. the container is being renamed to ACC-NO. There is absolutely no way to restore a container after you delete it. then its contents are overwritten.8 Moving containers between channels You can use the move container command to pass containers between channels. in the return call. this is done implicitly whenever it goes out of program scope. Moving a container from one channel to another is destructive. its storage is released and its name is removed from the list of containers that the channel holds. Example 3-12 shows a container moving to a temporary channel that you can later use for the program link. Example 3-12 Moving a container from one channel to another EXEC CICS MOVE CONTAINER('ACCOUNT-NO') AS('ACC-NO') CHANNEL('ACCOUNT-DATA') TOCHANNEL('TMP-CHANNEL') END-EXEC. If the target container does not exist.1. If you attempt to overwrite a container with itself. When you delete a container. If the target channel does not exist. When linking to a program.3. If it does exist. Note that as part of the move. then it effectively renames the container. an error occurs. Some key points when using move container are: If the source container does not exist. Note: There is no requirement to delete a container when it returns from a remote program that it has been linked to.7 Deleting a container You can use the delete container command to permanently remove a container from a channel. nothing happens and no error condition is raised. Example 3-11 shows a container being deleted from a channel. It is impossible to delete a channel. we recommend that you pass only the necessary containers that the program requires in a channel.

Example 3-13 shows how to create a channel object. If a container of the same name already exists in the channel. a ContainerErrorException message is displayed. Note: For detailed information about the JCICS API. instead of get container and put container. Container myContainer = myChannel.com/infocenter/cicsts/v3r1/index.*. 3. The channel and container names are limited to 16 characters. Chapter 3.server. The string supplied to the createChannel() method is the name that CICS uses to recognize the channel. To create a container in the channel. Programming 69 .1 InfoCenter at: http://publib.ibm.createContainer("ACCOUNT-NO"). 3.cics. Important: When using JCICS make sure dfjcics.1 Creating channels and containers in JCICS To create a channel. Channel myChannel = task.getTask(). the interface has been developed in an object-oriented perspective.2 CICS Java You can use the Java-based JCICS API to perform all the functions that have been previously explained using the more traditional style of channels and containers API. Example 3-13 Creating a channel and container Task task = Task.boulder.ibm.jar is in your classpath. and add the following import statement to the top of your Java class: import com. refer to JCICS Class Reference on the CICS Transaction Server 3.createChannel("ACCOUNT-DATA").2. use the createChannel() method of the Task class.jsp As with any JCICS implementation.Note: You can use move container. call the createContainer() method on the channel object. and then use it to create a container object. as a more efficient way of transferring data between channels.

The String.put("00054321"). xctl.getBytes() call. they can be received in the current channel. Link and xctl To pass a channel on a program-link or transfer program control call. Note the following points based on Example 3-14: The Container. Example 3-14 Adding data to a container String custNo = "00054321".put(tmpBytes). Important: When using channels and containers in JCICS. myContainer. data is always inserted into containers as type BIT. 3.put(String) method causes an implicit String. because if it is character data then it becomes a constant and remains the same from when it is inserted. 70 CICS Transaction Server V3 R1 Channels and Containers Revealed .getBytes() call followed by a put(byte[]). // Or alternatively myContainer. It is not possible to create a CHAR container in JCICS.3.getBytes() call encodes the string into a sequence of bytes using the platform’s default code page.getBytes(). JCICS always puts data into containers as type BIT. use the link() and xctl() methods of the program class. Example 3-14 shows data insertion into a container.2. which in this case is most likely EBCDIC. however.2 Placing data in a container To add data to a container use the put() method on the container class. which means it performs the same action as an explicit String. The API allows the addition of data as either a byte array or a string.3 Passing a channel to another program or task The facility to pass a channel to programs or tasks is similar to the process of passing COMMAREAs.2. byte[] tmpBytes = custNo.

Return transid To set the next channel in a pseudo-conversational program. Example 3-18 Passing a channel on a start transid call StartRequest startRequest = new StartRequest(). startRequest.getTask(). Example 3-17 shows a channel being passed in a pseudo-conversational transaction.setName("PROG2").getPrincipalFacility(). program1.setName("PROG1").setNextTransaction("ABCD"). Programming 71 . Example 3-16 Passing a channel on an xctl() Program program2 = new Program().setNextChannel(myChannel). terminalPF. Chapter 3. Example 3-15 Passing a channel on a link() Program program1 = new Program(). program1. startRequest. use the setNextChannel() method of the TerminalPrincipalFacility class. terminalPF. Start transid To pass a channel on a start request. program2. program2. Example 3-17 Setting the next channel on a return transid call TerminalPrincipalFacility terminalPF = (TerminalPrincipalFacility) Task.Example 3-15 shows a link with a channel.link(myChannel).xctl(myChannel).issue(myChannel). Example 3-18 shows a channel being passed on a start request. Example 3-16 shows an xctl with a channel. use the issue() method of the StartRequest class.setTransId("ABCD").

2. To re-instantiate the data as character data.2. Channel currentChannel = task.out. This method always returns its data as a byte array.getContainer("ACCOUNT-NO"). use the get() method of the container class. To instantiate an instance of the current channel. If no current channel exists.5 Getting data from a container To retrieve data from a container. String custString = new String(custInfo). If you know that the data is in a different code page then you must use new String(byte[] bytes. irrespective of whether it is of character data or binary data. } 3. it becomes the current channel for the program.getTask().getCurrentChannel().get(). passing the name of that code page. which in this case would be EBCDIC. Example 3-19 shows how to reference the current channel. the byte array can be passed to the constructor of the String class as Example 3-20 shows. then null is returned from the call. Example 3-20 shows new String(byte[] bytes) decodes the byte array data using the system’s default code page. you can use the getCurrentChannel() method on the Task class.3. Example 3-20 Getting the data from a container byte[] custInfo = myContainer.println("There is no current channel"). Example 3-19 Getting an instance of the current channel // Current channel example Task task = Task. if (currentChannel != null) { Container myContainer = currentChannel.4 Receiving the current channel If a program links to the Java program and passes a channel during the link. String charsetName). } else { System. 72 CICS Transaction Server V3 R1 Channels and Containers Revealed .

You can perform this function using the containerIterator() method on a channel object. Programming 73 .containerIterator().2. } 3. 3. A way to prevent this is to pass the data in BIT containers and instantiate it using new String(byte[] bytes. This means that if the container’s original code page has characters that the system’s default code page does not support.next().next(). } Chapter 3.util. Example 3-21 shows how to browse the current channel. which here would be a flavour of EBCDIC.getTask(). can access all of the container objects without receiving the channel explicitly. // Process the container. Example 3-22 Browsing the containers in a channel instance ContainerIterator iterator = myChannel.hasNext()) { Container myContainer = (Container) iterator. then character loss can occur during the conversion.2. The code is almost identical to that of browsing the current channel. To do this. // Process the container.Note: If the container is of type CHAR.containerIterator().. The containerIterator() method on the Task object returns an Iterator for the current channel. which implements the java. ContainerIterator iterator = task.Iterator interface. Example 3-22 shows how to perform a browse on a channel instance. while (iterator.6 Browsing the current channel A channel that a JCICS program passes. Example 3-21 Browsing the containers in the current channel Task task = Task. String charsetName). then its data is converted to the default code page of the system before being returned to the Java application. it uses a ContainerIterator object... while (iterator.7 Browsing a name channel It is also possible to perform a browse on an instance of a channel.hasNext()) { Container myContainer = (Container) iterator. or a null value if there is no current channel..

put("Some data"). Unicode Transformation Format-8 (UTF-8).8 Deleting a container You can delete a container in either of the following two ways: If you have an instance of a container. Java encodes and decodes the bytes using the platform’s default code page.2.2. Example 3-23 Deleting containers in a channel Container cont1 = myChannel. // Add some data cont1. // Deleting a container using its container instance cont2. // Deleting a container using a channel instance myChannel. no channel or container is created in CICS until you perform the put() command on the Java container instance. CICS uses EBCDIC for character encodings.createContainer("CONT1"). This means that a character in Java is represented by a different code point (a number) internally to that of CICS. 74 CICS Transaction Server V3 R1 Channels and Containers Revealed . Observation: In Example 3-23. Java represents String literals using the Unicode variable length character encoding.createContainer("CONT2"). Container cont2 = myChannel. Therefore.9 Code page considerations Both Java and CICS work in two different codepages. Alternatively. Example 3-23 shows the process to delete containers using both methods. then you can call the delete() method to delete it. When using String.put("Some more data").delete(). the easiest way to convert to and from String data is to use utility methods on the String class itself. and then insert the data.3.getBytes() and new String(byte[]). Because the main input and output type when using containers is the byte array.deleteContainer("CONT1"). 3. you can call the deleteContainer() method on the channel class. when passing character data between CICS and Java programs you require to be aware of these code page considerations. cont2. It is the put() command that causes an EXEC CICS PUT CONTAINER in CICS to create the channel and container.

This is because BIT containers are not applicable to code page conversion. while specifying the original CCSID. Thus. means that when the data is extracted. Java handles a majority of the conversion between UTF-8 and EBCDIC using these two methods. this is one of the EBCDIC codepages. Programming 75 . This helps with linking between Java and non-Java programs. it is in the code page of the original system. the character data may appear corrupt in the new application. encodes it in the system’s local code page and places it in a BIT container. because the majority of these running in CICS use the EBCDIC code page. it can be extracted in the local CCSID of that system. A solution to this is if you insert the data into a temporary CHAR container in the new program.In CICS. Therefore. Chapter 3. Attention: Putting character data into a container using JCICS. Linking to a CICS program in a remote system that runs an alternative code page.

Figure 3-1 shows the bilingual application scenario that we use to call a standard CICS server program from both a BTS wrapper activity and a non-BTS client. Thus. you can call server programs that use containers from both channel and BTS applications. LINK PROGR(SERVER) PAYR 4 Server E.C.C. 5 CHNCON 1 BTSINT 2 BTSROOT Client passing channel BTS initial request BTS root activity DEFINE ACTIVITY PUT CONTAINER (employee) E. and delete container commands that you use to build and interact with a channel are similar to those that you use in CICS BTS applications. We also develop a non-BTS client program that creates a channel and links to the same server. programmers with experience of BTS find it easy to use containers in non-BTS applications.. The application uses a BTS activity to link to a standard CICS server program which is using containers. get. GET CONTAINER(employee) PUT CONTAINER(status) Figure 3-1 Bilingual channel or BTS application environment This section explains the process of developing a bilingual channel or BTS application..3 Business transaction services The put.ASSIGN CHANNEL() PROCESS() .. Furthermore. LINK PROGR(SERVER) GET CONTAINER(status) DEFINE PROCESS RUN ACQPROCESS PUT CONTAINER (employee) LINK ACTIVITY GET CONTAINER(status) PAYACT 3 BTS activity E. move.3. 76 CICS Transaction Server V3 R1 Channels and Containers Revealed .C.

BTSINIT issues a RUN ACQPROCESS command to start an instance of the business transaction.3. The module shown in Example 3-24 performs two steps: It creates the business transaction. The BTSINIT program handles this request. It is the root activity program that typically manages the ordering and execution of the child activities that make up a business transaction.STEPLIB DD //SYSPRINT DD SYSOUT=* //TRN. which is the root activity program for the BTSX business transaction. Business transaction services initial request This is the initial request to start the business transaction.1 Application components The application shown in Figure 3-1 consists of the components that we describe in the following sections. Programming 77 . BTSINIT issues a DEFINE PROCESS command. To create an instance of the BTSX business transaction. Refer to the module BTSINIT in Example 3-24. In this case. // INDEX='CICSTS31. the program is BTSROOT.SYSIN DD * DFHEISTG DSECT BTSINIT CSECT BEGIN DS 0H EXEC CICS DEFINE PROCESS ('INITREQ0002') X PROCESSTYPE('INITREQ') X TRANSID('BTSX') X PROGRAM('BTSROOT') EXEC CICS RUN ACQPROCESS ASYNCHRONOUS RETURN DS 0H EXEC CICS RETURN END /*JCTRL*/ Chapter 3.3. On return from the DEFINE Process command.OUTC=K.CICS' //TRN. The PROGRAM option of DEFINE PROCESS defines a program to run under the control of BTS. Example 3-24 Module BTSINIT //* // EXEC PROC=TCKEITAL.

Using the DEFINE ACTIVITY command to create the payroll-2004 activity. Issue the retrieve reattach event command to determine the event.//LKED. running under the transid BTSX. issue a check activity command. 2. The business transaction ends. If the event is DFHINITIAL. 5. If the child activity returns successfully.SYSIN DD * MODE RMODE(ANY). and execution of the child activities that make up the BTSX business transaction. 78 CICS Transaction Server V3 R1 Channels and Containers Revealed . we specified PAYACT on the PROGRAM option. execute the code on the initial label. 6. Then. issue a get container command to get the status from the server program. Define the child activity. issue a link activity command that calls program PAYACT. Following this. issue a EXEC CICS RETURN ENDACTIVITY command. The first event is always DFHINITIAL. BTSINIT starts the root activity. BTSROOT is sleeping. the SERVERFINISHED event triggers the root activity to reattach when the child activity completes. when the running transactions trigger the events that interest it. The logic flow of BTSROOT: 1. Therefore. When the child activity completes. BTSROOT implements a root activity that manages the inter-relationship. 7. such as BTSROOT. it triggers an event indicating that the activity is complete. If the event is SERVERFINSHED. issue two put container commands. BTSROOT. The process we used is explained in the following steps. On return. BTS1 on the TRANSID option. BTSROOT defines one child activity that is later used as a wrapper to the standard CICS server program. again. ordering. The SERVERFINISHED event drives the root activity. A root activity program. Issue a RETRIEVE REATTACH EVENT command to determine the event. and SERVERFINISHED on the EVENT option. The activity program determines the possible events that cause BTS to attach it and what to do as a result. 3. is designed so that BTS can reattach it. Issue an EXEC CICS RETURN command.AMODE(31) NAME BTSINIT(R) /* // Business transaction services root activity The BTSINIT program starts a new instance of the BTSX business transaction by starting the BTSROOT program. 4.

SYSIN DD * DFHEISTG DSECT STAT DS CL2 EVENT DS CL16 DS CL16 CS DS XL4 RESP DS XL4 RESP2 DS XL4 BTSROOT CSECT BEGIN DS 0H ******************************************************* *** CHECK POSSIBLE EVENTS .CICS' //TRN. *** *** AND RETURN USING ENDACTIVITY OPTION *** ******************************************************* Chapter 3... // INDEX='CICSTS31.Example 3-25 shows a module BTSROOT and the steps explained previously.STEPLIB DD //SYSPRINT DD SYSOUT=* //TRN.START WITH DFHINITIAL *** ******************************************************* EXEC CICS RETRIEVE REATTACH EVENT(EVENT) CLC EVENT(16).INITIAL B RETURN ******************************************************* *** ROOT DRIVEN BY SERVERFINISHED EVENT? *** ******************************************************* NXTEVENT DS 0H CLC EVENT(16).=CL16'SERVERFINISHED ' BE CHKACT B RETURN ******************************************************* *** RETURN WITH OR WITHOUT ENDACTIVITY OPTION *** ******************************************************* RETURN DS 0H EXEC CICS RETURN RETURN1 DS 0H EXEC CICS RETURN ENDACTIVITY ******************************************************* *** IF SERVERFINISHED EVENT DO CHECK ACTIVITY . Programming 79 . Example 3-25 Module BTSROOT //* /*JCTRL*/ // EXEC PROC=TCKEITAL.OUTC=K.=CL16'DFHINITIAL ' BNE NXTEVENT BAL 8.

DEFINE AND LINK ACTIVITY *** ******************************************************* INITIAL DS 0H EXEC CICS DEFINE ACTIVITY('PAYROLL-2004') X PROGRAM('PAYACT') X TRANSID('BTS1') X EVENT('SERVERFINISHED') EXEC CICS PUT CONTAINER('EMPLOYEE') X ACTIVITY('PAYROLL-2004') X FROM('JOHN DOE') EXEC CICS PUT CONTAINER('WAGE') X ACTIVITY('PAYROLL-2004') X FROM('100') EXEC CICS LINK ACTIVITY('PAYROLL-2004') EXEC CICS GET CONTAINER('STATUS') X ACTIVITY('PAYROLL-2004') X INTO(STAT) BR 8 ********************************************************************** END 80 CICS Transaction Server V3 R1 Channels and Containers Revealed .CHKACT X DS 0H EXEC CICS CHECK ACTIVITY('PAYROLL-2004') COMPSTATUS(CS) X RESP(RESP) X RESP2(RESP2) CLC RESP.DFHRESP(NORMAL) BNE RETURN B RETURN1 ******************************************************* *** INITIAL PROCESS .

AMODE(31) NAME PAYACT(R) /* // /*JCTRL*/ Chapter 3.SYSIN DD * DFHEISTG DSECT EVENT DS CL16 DS CL16 PAYACT CSECT BEGIN DS 0H EXEC CICS RETRIEVE REATTACH EVENT(EVENT) EXEC CICS LINK PROGRAM('PAYR') RETURN DS 0H EXEC CICS RETURN END //LKED.//LKED.STEPLIB DD //SYSPRINT DD SYSOUT=* //TRN. Programming 81 . Example 3-26 shows a module PAYACT.AMODE(31) NAME BTSROOT(R) /* // Business transaction services activity The child activity program PAYACT issues the EXEC CICS LINK command that calls the CICS standard non-BTS server program. Specify PAYR on the program option. The event is always DFHINITIAL. Example 3-26 Module PAYACT //* // EXEC PROC=TCKEITAL. // INDEX='CICSTS31.SYSIN DD * MODE RMODE(ANY). Do not determine the event that triggered the activity.OUTC=K.SYSIN DD * MODE RMODE(ANY). in order to keep the sample as short as possible.CICS' //TRN.

=CL35'PAYR WAS CALLED BY NON BTS CLIENT B START NEXT DS 0H ' 82 CICS Transaction Server V3 R1 Channels and Containers Revealed . 3.=CL16'STATUS ' MVC EMP.STEPLIB DD //SYSPRINT DD SYSOUT=* //TRN. Issue a get container command followed by the put container command to set the status to OK. 2. Example 3-27 shows the server module PAYR.SYSIN DD * DFHEISTG DSECT CHN DS CL16 PROCESS DS CL36 STAT DS CL16 EMP DS CL16 EMPDAT DS CL8 STATDAT DS CL2 MSGAREA DS CL35 RESP DS F RESP2 DS F PAYR CSECT BEGIN DS 0H MVC STAT.OUTC=K. The program can be called from both BTS and non-BTS clients. // INDEX='CICSTS31.=CL2'OK' EXEC CICS ASSIGN CHANNEL(CHN) PROCESS(PROCESS) X RESP(RESP) RESP2(RESP2) CLC CHN(7). Example 3-27 Server module PAYR //* /*JCTRL*/ // EXEC PROC=TCKEITAL. Therefore.=CL7'PAYROLL' BNE NEXT MVC MSGAREA(35). note the following steps: 1.=CL16'EMPLOYEE ' MVC STATDAT.Server The server program PAYR is a standard CICS server program using channels and containers. set up an informational message and issue a writeq td command. Issue an assign channel() process() command in order to determine if the caller is BTS or non-BTS.CICS' //TRN. After determining the caller identification.

Refer to Example 3-28.=CL35'PAYR WAS CALLED BY A BTS CLIENT ' START DS 0H EXEC CICS GET CONTAINER(EMP) INTO(EMPDAT) EXEC CICS PUT CONTAINER(STAT) FROM (STATDAT) FLENGTH(STATLEN) EXEC CICS WRITEQ TD QUEUE('CSMT') FROM(MSGAREA) LENGTH(LEN) RETURN DS 0H EXEC CICS RETURN LEN DC H'0035' STATLEN DC F'2' END //LKED.=CL7'INITREQ' BNE RETURN MVC MSGAREA(35). with the program name of the client as CHNCON.OUTC=K. Issue an EXEC CICS LINK PROGRAM(PAYR) command.AMODE(31) NAME PAYR(R) /* // Client To create a simple non-BTS client that links to the server passing a channel. Create a channel PAYROLL.CICS' //TRN. // INDEX='CICSTS31. 5. Specify PAYROLL on the channel option. Example 3-28 Client module CHNCON //* // EXEC PROC=TCKEITAL. note the following steps: 1.SYSIN DD * MODE RMODE(ANY).SYSIN DD * DFHEISTG DSECT CHN DS CL16 EMP DS CL16 WGE DS CL16 STAT DS CL16 STATDAT DS CL2 CHNCON CSECT /*JCTRL*/ Chapter 3. 3.STEPLIB DD //SYSPRINT DD SYSOUT=* //TRN.CLC PROCESS(7). Issue two put container commands. 2. 4. issue a get container command to get the status. Programming 83 . which shows client module CHNCON. On return.

=CL16'PAYROLL ' MVC EMP. the container commands that it issues must not specify any options that identify them as either channel or BTS commands.2 Channel and container options As the sample application previously discussed shows.3. or as part of a BTS activity. To use a program in both a channel and a BTS context. The options that you can avoid on each of the container commands are: Delete container – – – – – ACQACTIVITY (BTS-specific) ACQPROCESS (BTS-specific) ACTIVITY (BTS-specific) CHANNEL (channel-specific) PROCESS (BTS-specific) 84 CICS Transaction Server V3 R1 Channels and Containers Revealed .=CL16'WAGE ' MVC STAT. without change and as part of a channel application.BEGIN DS 0H MVC CHN.SYSIN DD * MODE RMODE(ANY).=CL16'STATUS ' EXEC CICS PUT CONTAINER(EMP) CHANNEL(CHN) FROM('JOHN DOE') FLENGTH(LEN) EXEC CICS PUT CONTAINER(WGE) CHANNEL(CHN) FROM('100') X X FLENGTH(LEN1) EXEC CICS LINK PROGRAM('PAYR') CHANNEL(CHN) EXEC CICS GET CONTAINER(STAT) CHANNEL(CHN) INTO(STATDAT) RETURN DS 0H EXEC CICS RETURN LEN DC F'8' LEN1 DC F'3' END //LKED.=CL16'EMPLOYEE ' MVC WGE. you can use a program that issues container commands.AMODE(31) NAME CHNCON(R) /* // 3.

or neither) in which it occurs. BTS. in order to determine how to process the command. Chapter 3. The command is rejected with an INVREQ condition and a RESP2 value of 4. To determine the context. CICS uses the following sequence of tests: Channel Does the program have a current channel? BTS Is the program part of a BTS activity? None The program has no current channel and is not part of a BTS activity. CICS analyzes the context (channel. it has no context in which to execute container commands.Get container – – – – – – – – – – – – – – – – – – – ACQACTIVITY (BTS-specific) ACQPROCESS (BTS-specific) ACTIVITY (BTS-specific) CHANNEL (channel-specific) INTOCCSID (channel-specific) PROCESS (BTS-specific) FROMACTIVITY (BTS-specific) CHANNEL (channel-specific) FROMPROCESS (BTS-specific) TOACTIVITY (BTS-specific) TOCHANNEL (channel-specific) TOPROCESS (BTS-specific) ACQACTIVITY (BTS-specific) ACQPROCESS (BTS-specific) ACTIVITY (BTS-specific) CHANNEL (channel-specific) DATATYPE (channel-specific) FROMCCSID (channel-specific) PROCESS (BTS-specific) Move container Put container When you execute a container command. Programming 85 . Therefore.

You can give the PGMINT parameter either of the following two values: Channel: CICS uses a channel interface to pass data to the target application. the binary format is almost impossible to read with the human eye. 3.1. 86 CICS Transaction Server V3 R1 Channels and Containers Revealed . The increase in usability is proportional to the increase in storage use. compliments the core Web services support that was also introduced in the release. then the container name defaults to DFHWS-DATA.4 Web services As previously mentioned.1. However. Using channels and containers in a service provider application You can make the decision to use channels and containers or a COMMAREA in your service provider application during the creation of the WSBind file with the Web Services Assistant.3. The increase in usability with SOAP means that the size of these messages is larger than that of a compact binary message. for it to hold the top level data structure that you use to represent the SOAP message. Web services interact through SOAP messages.1 Using channels and containers in CICS Web services In the base level of CICS Transaction Server version 3. If CICS uses channel. which are human readable text representations of message data and information. than they are at present. If you do not specify CONTID. then you can specify the optional parameter CONTID as the name of the container. This means that channels and containers become an even further integral part of Web services in CICS. COMMAREA: CICS uses a COMMAREA to pass data to the target application. one of the reasons channels and containers were introduced was to alleviate 32 KB limitations when working with Web services. You can also use channels and containers to work with arrays of varying amounts of elements. The introduction of channels and containers in CICS Transaction Server version 3. you can use channels and containers to transfer SOAP message data to a service provider application.4.

In this case. Programming 87 . the main data structure does not contain a declaration of an array. and the contents of “component-cont” is undefined.Variable arrays of elements When using DFHWS2LS to generate language structure with array elements. The container holds an array of elements and the DFHWS-component data structure maps each of these elements in the container. Example 3-29 shows a message that can contain anything from 0 to 8 string elements. then this process may be too expensive. which is large enough to hold the maximum number of elements that can be received. Instead. the first field “component-num” contains the number of times. then the component element is in the container which is named in “component-cont”. A second data structure contains the declaration of the element itself as follows: 01 DFHWS-component 02 component PIC X(8) Therefore. Chapter 3. However. if the array is a fixed length. generate an array type in the local system (LS). If it is zero. What would happen if the Web Services Description Language (WSDL) specifies that the application can receive an unbounded amount of elements? In this scenario channels and containers are an easy and reliable option. Example 3-29 Sample WSDL <xsd:element name="component" minOccurs="0" maxOccurs="8"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="8"/> </xsd:restriction> </xsd:simpleType> </xsd:element> In this case. to process the data structure in your application program. The second field “component-cont” contains the name of a container. you must examine the value of “component-num”. there is no component element in the message. zero through eight. If the value is not zero. it contains a declaration of two fields: 05 component-num PIC S9(9) COMP-4 05 component-cont PIC X(16) At run time. then DFHWS2LS can easily represent this array in the resulting language structure. if the number of elements in an array are allowed to vary at runtime. that the element is displayed in the SOAP message.

which has been migrated from the latest development release.1 This APAR gives performance improvements on Web service processing and also solves some known problems. Example 3-30 Cost comparison of encoding data xsd:base64Binary= 1. CICS can now handle the conversion. it is mapped to a separate CICS container.4. A key feature is its ability to use channels and containers to support variable length data.4.ibm. similar to the method of processing variable length arrays discussed previously. visit the Web at: http://www-306.3 APAR . along with further fixes to known problems. between binary and base64 encoded binary. with the container as a means to pass data to the application program. Additionally. An additional feature is the ability to convert to and from xsd:hexBinary on variable length data inside the containers.PK23547 on CICS Transaction Server version 3. The cost of encoding data as xsd:base64Binary compared to xsd:hexBinary is as Example 3-30 shows. You can refer to further information about arrays of elements in the CICS Transaction Server version 3. A new feature is the ability to natively support the conversion of xsd:base64Binary encoded data. 3.33 * [original data size] xsd:hexBinary = 2 * [original data size] For further details on APARs.PK15904 on CICS Transaction Server version 3.com/software/htp/cics/support/ 88 CICS Transaction Server V3 R1 Channels and Containers Revealed . When a value described in the WSDL document is known to be of variable length and is likely to be large. in addition to that provided with PK15904.1 Information Center at: Library and PDFs → Access to CICS → Web services → The CICS Web services assistant → High level language and XML schema mapping → Variable arrays of elements 3.2 APAR . This allows you to send the variable length binary data in a SOAP message using a more efficient encoding mechanism than that of xsd:hexBinary.1 This APAR provides functionality built.We recommend that you start considering how you can represent nested arrays. it opens up new functionality. This allows the application to treat the value as variable length without having to pad large fields with nulls or spaces.

you can see that.4 Chapter 4. Moreover. Although these are tasks that you would normally expect the systems programmer to undertake. © Copyright IBM Corp. Systems management and configuration This chapter discusses the systems management and configuration tasks and techniques that you must consider when implementing a channels and containers solution. Because successful systems management requires a well tuned software implementation. this chapter discusses the performance criteria which can assist you. It also discusses the changes made to investigating performance considerations and options available to the systems programmer for problem determination. 89 . in a channels and containers implementation. and temporary storage (TS). this chapter also looks at the enhancements that have been made to monitoring and statistics. some of these tasks are no longer the responsibility of the systems programmer role. this chapter provides the results of a performance comparison evaluation carried out on the transfer of data using channels and containers. 2006. All rights reserved. In addition. communication areas (COMMAREAs).

4. it fails with an INVREQ message appearing. but you must still encourage the application programmer to limit the amount of storage they use for a channel at any given time. if the routing program attempts to use the DYRCHANL as a parameter on an EXEC CICS GET CONTAINER CHANNEL command. or your version of it. The routing program cannot inspect or modify the contents of the channel’s containers that are passed to it. you must use the delete container command whenever it is appropriate. the Customer Information Control System (CICS) does not enforce any size limitation regarding how big the container can be. after calling a program with the container as input.1 Storage When the application programmer creates a container. and to ensure that the routing program has the same kind of functionality with channels as it had with COMMAREAs.2 The DFHROUTE container If you use a channels and containers solution in an application that employs dynamic transaction routing. The only upper limit for size is the amount of available user storage in the CICS address space. CICS deletes channels when they are no longer in scope. When the application issues a link or terminal related start (but not a non-terminal related start request) to be dynamically routed. a special container named DFHROUTE is available to the application programmer in the channel to be passed to the routing program. the DFHDYPDS COMMAREA still passes to the dynamic routing program. Because it is the name of the channel passed. How the routing program uses DFHROUTE When you migrate a dynamically-routed EXEC CICS LINK or EXEC CICS START command to use a channel rather than a COMMAREA. rather than the name of the channel address. To circumvent this problem. This container can hold the data that the routing program requires to access the channel. encourage the use of the EXEC CICS MOVE CONTAINER command to move data from one channel to another. to ensure that multiple copies of the same data are not processed. the dynamic routing 90 CICS Transaction Server V3 R1 Channels and Containers Revealed . For example. the routing program DFHDYP is passed the name of the channel in the DYRCHANL field of DFHDYPDS. such as. Also. This is an important change made to DFHDYPDS to remove what was previously a restriction.4.

Chapter 4. the task of data conversion simplifies such that the application programmer can perform the operation as part of the application code. This is especially important if you rely on the contents of all or part of your COMMAREA to influence the decision the dynamic routing program makes regarding where to route work. The systems programmer handled data conversion when it was required because the process was complex. 4. which is an optional choice. Therefore. If you are migrating a program to pass a channel rather than a COMMAREA. Systems management and configuration 91 . a CICS Transaction Server program. it was the responsibility of the systems programmer to handle the code page conversion using the DFHCNV conversion table. it can now inspect and change its contents if required. using the same process discussed earlier in this chapter. This is discussed in more detail in Chapter 2.3 Code page conversion Traditionally. or both parameters. and the EXEC CICS GET CONTAINER command with the INTOCCSID parameter. the application programmer now has the ability to perform a simple code page conversion. For example. consider using the program’s existing COMMAREA structure to map DFHROUTE. 4. “Application design and implementation” on page 23. However.program is passed the address of the DFHROUTE container in the DYRACMAA field of DFHDYPDS. and the DFHUCNV user-replaceable conversion program.1 Simple code page conversion If you use a combination of the EXEC CICS PUT CONTAINER command with the DATATYPE parameter.3. you can make use of the DFHROUTE container in the user-replaceable module EYU9WRAM. when a channels and containers solution replaces the COMMAREA. the DFHCCNV conversion program. Note: If you are using CICSPlex System Manager and the routing program EYU9XLOP. using Extended Binary Coded Decimal Interchange Code (EBCDIC) encoding is interacting via a COMMAREA with a JAVA program using Unicode Transformation Format-8 (UTF-8) encoding. or FROMCCSID parameter.

you can specify the relevant code page in the LOCALCSSID SIT parameter as the example shows: LOCALCSSID={037|CCSID} 4. Important: You must activate support for Unicode before you start CICS.3.However. If you require to change this. CICS use its internal tables for pairs of CCSIDs that the DFHCNV mechanism currently supports. because the services are not enabled: DFHAP0801I applid z/OS Conversion Services are not available The following message is issued to report that this system does not support a particular conversion between two specific CCSIDs: DFHAP0802 applid Data conversion using CCSID ccsid and CCSID ccsid is not supported by this system Note: If you attempt to use a code page in CICS. there is still a requirement for the systems programmer to ensure that the CICS region is using the correct coded character set identifier (CCSID). Two new messages are issued resulting from failures in invoking the z/OS conversion services: The following console message is issued during CICS initialization to indicate that this CICS region does not support Unicode conversion.2 z/OS Unicode conversion services Code page conversion is performed using z/OS Unicode conversion services. which Unicode supports but has not yet enabled. anyway. 92 CICS Transaction Server V3 R1 Channels and Containers Revealed . By default this is CCSID 37. then z/OS still attempts to enable or install that conversion. It is not necessary for the system programmers to configure all possible pairs of CCSIDs that application programs require.

and current diagnosis. it may look like an obvious choice to use a channel with a single container to replace your current COMMAREA. However. Data separation If you are converting an existing application.4. which includes personal details. 4. back to the doctor. we present a scenario. are returned to the client. from a performance perspective. it may be better to separate the input and output fields in your COMMAREA into different containers. which are data separation and error data handling that are discussed in the following sections. The main performance benefit of doing this is that the amount of unnecessary data transmission is significantly reduced. and also those containers that the server program creates. Systems management and configuration 93 .1 Configuration There are two aspects of configuration. a small amount of data which is the patient’s current diagnosis. the server also re-transmits the medical history field. However. The doctor only wants to receive the current diagnosis back from the server. passes on to a server program which provides. For example. by return. even though it has probably not been altered. in which a doctor collates a large amount of data in the form of a patient’s medical history. input containers whose contents the server program has not changed do not return to the client.4 Performance considerations There are several performance related options during the design phase of a channels and containers implementation. medical history. input containers whose contents the server program has changed. Assume that an existing COMMAREA-based application. which could potentially be very large. which you must encourage the application programmer to consider. To demonstrate the previous point. On the other hand.4. Figure 4-1 shows that the COMMAREA consists of one contiguous block of data containing three separate fields for the patient. at the end of a distributed program link (DPL) call. Chapter 4.

medical history. the doctor passes the personal details and medical history containers. but with separate containers for the personal details. CURR_DIAGNOSIS. and current diagnosis data fields. Note that because the data in the PATIENT_DETAILS container and the MEDICAL_HISTORY container were not modified on the call. the server does not return these data. 94 CICS Transaction Server V3 R1 Channels and Containers Revealed . Personal details Medical history Client Server Current diagnosis Figure 4-1 Simple COMMAREA scenario Figure 4-2 shows the same scenario. PATIENT_DETAILS and MEDICAL_HISTORY.Refer to Figure 4-1 that illustrates this simple COMMAREA scenario. to the diagnosis server program and receives the patient diagnosis data back in another separate container. In this case. All that the doctor receives back is the container CURR_DIAGNOSIS in which the diagnosis data is held.

Refer to Figure 4-2 that illustrates this simple containers scenario. a NOTFOUND condition would indicate no error. PATIENT_DETAILS MEDICAL_HISTORY Client Server CURR_DIAGNOSIS Figure 4-2 Simple containers scenario Error data handling Channels and containers offer a different option for handling error data in an application. if error is found. Whereas. Systems management and configuration 95 . Additionally. because the server requires to transmit the error container only when an error occurs. can lead to improved performance and can also simplify application logic. dedicated container for error information. If you include an EXEC CICS GET CONTAINER command for the error container in your code. the application benefits from improved efficiency between CICS regions. Using a single. then you could interrogate the container for the error information. Chapter 4.

Commarea application Sender program EXEC CICS GETMAIN EXEC CICS LINK . CHANNEL EXEC CICS RETURN Receiver program EXEC CICS GET CONTAINER EXEC CICS RETURN Single container used for data No restriction on data size Figure 4-4 Container performance example 96 CICS Transaction Server V3 R1 Channels and Containers Revealed .. as Figure 4-4 shows. in the same region and also in two separate MRO-connected regions. COMMAREA EXEC CICS RETURN EXEC CICS RETURN Receiver program 32KB max data restriction Figure 4-3 COMMAREA performance example Using containers..4.4. as Figure 4-3 shows. Performance scenarios Three different methods of passing the data were used in the evaluation as follows: Using COMMAREAs..2 Performance data A evaluation was undertaken to compare the performance of two Common Business Oriented Language (COBOL) programs passing data between each other. Channel application Sender program EXEC CICS GETMAIN EXEC CICS PUT CONTAINER EXEC CICS LINK ..

Systems management and configuration 97 .Using shared temporary storage. Single Region Links greater than 32KB Figure 4-6 Performance results for less than 32 KB data size in a single region Chapter 4. as Figure 4-6 shows. TSQ application Sender program EXEC CICS GETMAIN EXEC CICS WRITEQ TS EXEC CICS LINK EXEC CICS DELETEQ TS EXEC CICS RETURN EXEC CICS RETURN Receiver program EXEC CICS READQ TS Multiple TSQ items used for data size greater than 32KB Figure 4-5 Temporary storage performance example Performance results The performance evaluation shows that when the size of the data being transferred was less than 32 KB. in a single CICS region. the COMMAREA scenario slightly out-performed the channel scenario. although both out-performed the temporary storage scenario. as Figure 4-5 shows.

when the size of the data being transferred exceeds 32 KB as Figure 4-8 depicts. across an MRO link. MRO Link greater than 32KB Figure 4-7 Performance results for less than 32 KB data size across an MRO link However. The performance of the temporary storage solution degrades. as Figure 4-7 shows. you cannot use COMMAREAs. the channel scenario was again very nearly at par with the COMMAREA scenario.The performance evaluation also shows that when the data being transferred was less than 32 KB. This time both scenarios outperformed the temporary storage scenario quite significantly. 98 CICS Transaction Server V3 R1 Channels and Containers Revealed .

5 Monitoring and statistics Several changes have been made to the monitoring and statistics domains for channels and containers support.The processor increase for the channel scenario remains linear. and also to a new monitoring group called DFHCHNL that was previously created. Chapter 4.5. as Figure 4-8 shows. The following sections discuss this new group and the new fields in the existing groups. Single Region Links greater 32KB Figure 4-8 Performance results for greater than 32 KB data size in a single region 4. Systems management and configuration 99 .1 Monitoring changes There are changes relating to channels and containers that have been made to two existing monitoring groups. 4.

in bytes. which contains monitor data for channel and container usage. Table 4-1 DFHCHNL group entries Field name PGTOTCCT PGBRWCCT PGGETCT PGPUTCT PGMOVCT PGGETCDL PGPUTCDL Field ID 321 322 323 324 325 326 327 Description Total number of CICS requests for channel containers for the task Number of browse requests for channel containers for the task Number of get container requests for the task Number of put container requests for the task Number of move container requests for the task Total length.DFHCHNL DFHCHNL is a new monitoring group. in bytes. in bytes. of the container data for a DPL Total length. of all the get container data returned Total length. of all the container data returned from a DPL Number of link requests issued with the channel option for this task Number of xctl requests issued with the channel option for this task Number of DPL requests issued with the channel option by the user task Number of return requests issued with the channel option for this task Total length. of the container data return 100 CICS Transaction Server V3 R1 Channels and Containers Revealed . in bytes. Table 4-2 New DFHPROG group entries Field name PCDLCSDL PCDLCRDL PCLNKCCT PCXCLCCT PCDPLCCT PCRTNCCT PCRTNCDL Field ID 286 287 306 307 308 309 310 Description Total length. of all the put container data returned DFHPROG Table 4-2 shows the new fields that have been added to the existing monitoring group DFHPROG. Table 4-1 shows the fields in the DFHCHNL group. in bytes.

DFHTASK
Table 4-3 shows the new fields that have been added to the existing monitor group DFHTASK for channels and containers.
Table 4-3 New DFHTASK group entries Field name ICSTACCT ICSTACDL ICSTRCCT ICSTRCDL Field ID 65 345 346 347 Description Number of start requests issued with the channel option Length of the data in the containers of all the locally-executed start channel requests Number of interval control start channel requests to be executed on remote systems Total length of the data in the containers of all the remotely executed start channel requests

4.5.2 Statistical changes
There have been changes made to certain fields in the statistics report. The new fields in the intersystem communication (ISC) or inter-region communication (IRC) system entry are as follows: Terminal sharing – Number of terminal-sharing channel requests – Number of bytes sent on terminal-sharing channel requests – Number of bytes received on terminal-sharing channel requests Program control – Number of program control link requests, with channels, for function shipping – Number of bytes sent on link channel requests – Number of bytes received on link channel requests Interval control – Number of interval control start requests, with channels, for function shipping – Number of bytes sent on start channel requests – Number of bytes received on start channel requests

Chapter 4. Systems management and configuration

101

Figure 4-9 shows a sample statistic report produced for channels and containers usage. Transaction Routing Requests ____________________________ Transaction Routing - Total...: Transaction Routing - Channel.: Max Queue Time - Allocate Purge ....: 0 0 0 Allocates Purged - Max Queue Time ..: 0

Allocates Rejected - XZIQUE ........: 0 Function Shipping Requests XZIQUE - Allocate Purge ............: 0 __________________________ File Control................: 0 Allocates Purged - XZIQUE ..........: 0 Interval Control - Total......: 0 Interval Control - Channel..: 0 Transient Data...............: 0 Temporary Storage ...........: 0 Program Control - Total .....: 0 Program Control - Channel..: 0 _______________________________________________ Total .......................: 0 Bytes Sent by Transaction Routing requests:0Average Bytes Sent by Routing request:0 Bytes Received by Transaction Routing requests:0 Bytes Sent by Program Channel requests:0 Average Bytes Sent by Channel request:0 Bytes Received by Program Channel requests:0 Bytes Sent by Interval Channel requests:0 Average Bytes Sent by Channel request:0 Bytes Received by Interval Channel requests:0
Figure 4-9 Statistics output

4.6 Migration planning
In order to implement a channels and containers solution you must run a CICS Transaction Server Version 3.1. If you are migrating to CICS Transaction Server Version 3.1, specifically to implement a channels and containers solution, there are certain migration factors to consider.

4.6.1 Back level toleration
All CICS regions participating in a channels and containers solution must be running CICS Transaction Server Version 3.1 for the solution to be successful. Because pre-CICS Transaction Server Version 3.1 systems are unable to understand the inbound channel data, it can cause problems in the pre-CICS Transaction Server Version 3.1 systems.

102

CICS Transaction Server V3 R1 Channels and Containers Revealed

In order to protect against these problems, there are a series of authorized program analysis reports (APARs) available to enable a pre-CICS Transaction Server Version 3.1 system to tolerate channels. The system can tolerate channels if it produces a meaningful abend code when a channel is passed to it. Table 4-4 shows these APARs, at each relevant release.
Table 4-4 Compatibility APARs APAR PQ93048 PQ92437 PQ93049 PK02429 IY63855 IY63888 PQ94718 SE15875 Release IBM CICS Transaction Server for OS/390 V1.3 IBM CICS Transaction Server for z/OS V2.2 IBM CICS Transaction Server for z/OS V2.3 IBM CICS Transaction Server for VSE/ESA™ V1.1 IBM CICS/VSE® 2.3 IBM TXSeries® for Multiplatforms V5.0 IBM TXSeries for Multiplatforms V5.1 IBM CICS Transaction Server for Windows® IBM CICS Transaction Server for eServer™ iSeries™

After applying the APARs described previously, you can issue abend codes, when the conditions described in the following sections occur.

AXF9
If you transmit a channel to a remote program by issuing an EXEC CICS LINK, and if that program resides on a CICS region at a release lower than CICS Transaction Server Version 3.1, then the transaction that receives the channel gets an AXF9. If you transmit a channel to a remote transaction by issuing an EXEC CICS START and if that transaction resides on a CICS region at a lower release than CICS Transaction Server Version 3.1, then the transaction that receives the channel gets an AXF9.

Chapter 4. Systems management and configuration

103

AZTD and AXTT
If you ship a channel from an application-owning region (AOR) to a terminal-owning region (TOR) using transaction routing when the pseudo-conversation ends or from a TOR to an AOR when the next transaction in a pseudo-conversation begins, the lower release of CICS gets the transaction AXTT. An exception to this is if you send the channel to an AOR where the remote terminal is unknown. In this case the abend code is AZTD. These APARs are documented on the Infocenter at: http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/topic/com.ibm.supp ort.cics.doc/html/Container/swg21190113.html

4.6.2 TRUEs, global user exits, and user-replaceable modules
Task-related user exit (TRUE) programs cannot access containers that application programs create. However, they can create their own channels and pass them on to programs that they call. The same applies to global user exits and user-replaceable modules.

4.6.3 Dynamic routing by data content
If you have an application written to be dynamically routed depending on the data passed to the dynamic routing program in a COMMAREA, but instead, you intend to migrate that application to use channels. To do this, you require to be aware that when you pass a channel to the dynamic routing program, the program is unable to read the contents of any of the containers in the passed channel. Therefore, ensure that you make use of the DFHROUTE container to include your routing specific data, because the dynamic routing program can read the contents of this DFHROUTE container. Previously, 4.2, “The DFHROUTE container” on page 90 discusses the DFHROUTE container in more detail. Also, Chapter 2, “Application design and implementation” on page 23 shows an example of using the DFHROUTE container.

104

CICS Transaction Server V3 R1 Channels and Containers Revealed

fails while trying to receive data from. However. specific to CICS Transaction Server Version 3.4. Chapter 4.1. Recreates the channel and containers from inbound data received from a remote system. Systems management and configuration 105 . or send data to. 4.1 regions in which channels and containers have been implemented. there are a set of new abend codes.1 New abend codes As 4. either because the from or into address is specified incorrectly. “Back level toleration” on page 102 previously discusses. AXTS An AXTS abnormal end indicates that an attempt was made to pass channel and container data between the transactions in a pseudo-conversation. in addition to these. AEYF An AEYF abnormal end occurs when an invalid storage area passes to CICS on a put container command or get container command. there are a series of new abend codes that APAR introduces.7. or because the FLENGTH value specifies a value large enough to cause the area to include storage that the transaction cannot access. These are depicted in the following sections.7 Problem determination This section details the various new abend codes and trace points introduced with the channels and containers support to help with problem determination. DFHAPCR performs the following functions: Extracts the contents of all containers making up a channel and transmits them to a remote system. a connected CICS system. AITI An AITI abnormal end occurs when a mirror transaction that is processing a start channel or a link channel request. AXGA An AXGA abnormal end occurs when program DFHAPCR returns an unexpected response on a function shipping request. but the next transaction in the pseudo-conversation resides in a CICS region that does not support channels and containers. which apply to back level CICS regions involved in a channels and containers conversation.6.

4.2 New trace entries There are several new trace entries pertaining to channels and containers.7. Table 4-5 Container data transformation trace points Point ID AP 4E00 AP 4E01 AP 4E02 AP 4E03 AP 4E04 Module DFHAPCR Lvl AP 1 AP 1 AP Exc AP Exc AP Exc Type Entry Data 1 APCR parameter list 1 APCR parameter list 1 APCR parameter list 1 ACPR parameter list 1 APCR parameter list 2 kernel error data 1 APCR parameter list 2 PGCR parameter list 1 ACPR parameter list 2 PGCR parameter list DFHACPR Exit DFHACPR Invalid format DFHACPR Invalid function DFHACPR Recovery AP 4E05 DFHAPCR AP Exc Delete container failed AP 4E06 DFHACPR AP Exc Put container failed 106 CICS Transaction Server V3 R1 Channels and Containers Revealed .AXTU An AXTU abnormal end occurs when program DFHAPCR returns an unexpected response on a transaction routing request. These are shown in Table 4-5.

Systems management and configuration 107 .Point ID AP 4E07 Module DFHACPR Lvl AP 2 Type Receive tioa Data 1 tioa 2 03307400 1 APCR parameter list 2 PGCR parameter list 3 03307900 1 APCR parameter list 2 03308400 1 ACPR parameter list 2 SMGF parameter list 3 03308900 1 response 2 abend code 3 sense code 4 03309400 1 ACPR parameter list 2 buffer left 3 03309900 AP 4E08 DFHACPR AP Exc Create channel failed AP 4E09 DFHACPR AP Exc No room for channel header AP 4E0A DFHACPR AP Exc Getmain failed AP 4E0B DFHACPR AP Exc DFHtc error AP 4E0C DFHACPr Ap Exc Extract total length Chapter 4.

Point ID AP 4E0D Module DFHACPR Lvl AP Exc Type Extract channel header Data 1 APCR parameter list 2 buffer left 3 03310900 1 APCR parameter list 2 buffer left 3 03310900 1 APCR parameter list 2 buffer left 3 03311400 1 APCR parameter list 2 buffer left 3 03311900 1 APCR parameter list 2 buffer left 3 03312100 1 APCR parameter list 2 channel header 3 03312200 AP 4E0E DFHACPR AP Exc Extract container header AP 4E0F DFHACPR AP Exc Premature end of data AP 4E10 DFHAPCR AP Exc More data expected AP 4E11 DFHACPR AP Exc Extract container length AP 4E12 DFHACPR AP Exc Bad channel eye-catcher 108 CICS Transaction Server V3 R1 Channels and Containers Revealed .

Point ID AP 4E13 Module DFHACPR Lvl AP Exc Type Bad container eye-catcher Data 1 ACPR parameter list 2 container header 3 03312300 1 channel length 2 03312400 1 channel header 2 03312500 1 container header 2 03312600 1 container length 2 03312800 1 container data 2 03313000 1 APCR parameter list 2 DOMAIN PLIST parameter list 1 container name 2 owner 3 03313400 AP 4E14 DFHACPR AP 2 Extract channel length AP 4E15 DFHACPR AP 2 Extract channel header AP 4E16 DFHACPR AP 2 Extract container header AP 4E17 DFHAPCR AP 2 Extract container length AP 4E18 DFHACPR AP Exc Extract container data AP 4E19 DFHACPR AP Exc Bad response to domain call AP 4E20 DFHACPR AP 2 Container added Chapter 4. Systems management and configuration 109 .

the best place to begin debugging. there is also one new trace point entry for channels and containers in the AP domain recovery set.3 Tracing channels and containers applications As with most complex problems in CICS. 110 CICS Transaction Server V3 R1 Channels and Containers Revealed . a problem arising from using channels and containers is probably best solved by obtaining a dump and inspecting it using Interactive Problem Control System (IPCS). as shown in table Table 4-6. looking first for the presence of any of the exception entries listed in these tables previously mentioned.Point ID AP 4E21 Module DFHACPR Lvl AP 2 Type container changed Data 1 container name 2 owner 3 iseq 4 cseq 5 origi03313500 1 container name 2 owner 3 03313600 AP 4E22 DFHACPR AP 2 container deleted In addition. The trace table in the dump is.7. more often than not. The channel and containers trace points have been discussed previously. Table 4-6 AP domain recovery trace point for channels and containers Point ID AP 0785 Module DFHSRP Lvl Exc Type Abend AEYF Data 1 Application program name 2 Parameter address 3 ARG0 4.

4 Sample application trace flow The following sections depict the trace output of a sample application that we ran.6 EXEC CICS PUT CONTAINER(BIGONE) CHANNEL(CHN) FROM(PTR1) X FLENGTH(LEN) EXEC CICS START TRANSID('BIG') CHANNEL(CHN) RETURN DS 0H EXEC CICS RETURN FFS DC XL1'FF' PTR EQU 6 LEN DC XL4'989680' END Figure 4-10 The BIGLOC program Chapter 4.7. This program allocates a 10M user area containing x’FF’. which uses an assembler program called BIGLOC that Figure 4-10 shows. The environment We defined a transaction BIGL.=CL16'CHN ' EXEC CICS GETMAIN FLENGTH(10000000) INITIMG(FFS) SET(PTR) USING PTR1. immediately prior to the exception entry. Note: Trace points related to channels and containers are part of the standard set of trace points in the application program domain.=CL16'BIGONE ' MVC CHN. and then starts a second transaction BIG. 4. and the trace entries. executes a put container command specifying a channel CHN. and you do not require to turn on special tracing in CETR to obtain them. PTR1 DSECT DS CL16 DFHEISTG DSECT CHN DS CL16 BIGONE DS CL16 BIGLOC CSECT BEGIN DS 0H MVC BIGONE. Systems management and configuration 111 .This is usually a good indicator of why any given problem may have occurred. may provide vital clues as to what led to the problem occurring in the first place. which includes some of the trace points listed previously.

Specifying transaction BIG as remote.2 connection between the two regions. Therefore. which executes a get container command to retrieve the 10M of x’FF’ that BIGLOC creates. Figure 4-11 provides the source code for program BIGREM. having the name BIGR. having the name BIGR.=CL16'CHN ' EXEC CICS GETMAIN FLENGTH(10000000) INITIMG(FFS) SET(PTR) USING PTR1.The BIG transaction runs assembler program BIGREM. using an ISC LU6. connecting to SCSCPTA1 via an MRO link. Therefore. and then returns. and running on CICS region SCSCPAA4 in a different MVS image. they both ran in the same CICS region SCSCPTA1.6 S EXEC CICS GET CONTAINER(BIGONE) CHANNEL(CHN) INTO(PTR1) X FLENGTH(LEN) RETURN DS 0H EXEC CICS RETURN FFS DC XL1'FF' PTR EQU 6 LEN DC XL4'989680' END Figure 4-11 The BIGREM program This application was started in three different modes: Specifying both the transactions BIGL and BIG as local. The application ran with an 8M internal trace active on all CICS and took SNAP dumps after each test. and running on another CICS region SCSCPAA1 in the same Multiple Virtual Storage (MVS) image. Thereby. 112 CICS Transaction Server V3 R1 Channels and Containers Revealed . PTR1 DSECT DS CL16 DFHEISTG DSECT CHN DS CL16 BIGONE DS CL16 BIGREM CSECT BEGIN DS 0H MVC BIGONE.=CL16'BIGONE ' MVC CHN. Specifying transaction BIG as remote.

with transaction number 00043. we GETMAIN this request into EUDSA and associate it to the task as trace entries 0002 to 0003 show. PG 0901 PGPG ENTRY . 4.FUNCTION(GETMAIN) GET_LENGTH(989680) SUSPEND(YES) INITIAL_IMAGE(FF) STORAGE_CLASS(USER) CALLER(EXEC) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A35AF9BC TIME-10:18:17. Therefore. 3. trace entry 0004. 2. The size of the area passed is 10M and it contains x’FF’. Program BIGLOC requests a 10M area (x’989680’).. the initial link to BIGLOC program completes. This leads to a check. where transaction BIGL (program BIGLOC) executes a put container command and starts transaction BIG (program BIGREM) that executes a get container. Because it does not exist. Figure 4-12 shows the first part of the trace output of this test and the results are as follows: 1.910640008 =0001 SM 0C01 SMMG ENTRY . a CHANNEL_NOT_FOUND condition is received. Systems management and configuration 113 .954004211 =0004 PG 1700 PGCH ENTRY .Transactions running locally The first test was run inside SCSCPTA1.FUNCTION(INITIAL_LINK) PROGRAM_NAME(BIGLOC) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A29404D8 TIME-10:18:17.FUNCTION(INQUIRE_CHANNEL) RESPONSE(EXCEPTION) REASON(CHANNEL_NOT_FOUND) CONTAINER_POOL_TOKEN(00000000) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A34A4260 TIME-10:18:17..9540149538 =0006 Figure 4-12 Inquire channel Chapter 4...9540127585 =0005 PG 1701 PGCH EXIT .) FIELD-B(08003416 .FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(25200008) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A35AF9BC TIME-10:18:17. trace entries 0005 to 0006..FUNCTION(INQUIRE_CHANNEL) CHANNEL_NAME(CHN) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A34A4260 TIME-10:18:17.9263680239 =0002 SM 0C02 SMMG EXIT .. trace entry 0001. After the transaction BIGL was started. to see whether channel CHN already exists or not.) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A510010C8 TIME-10:18:17. Program BIGLOC executes the put container command to move the data from the EUDSA to the container.9539912897 =0003 AP 00E1 EIP ENTRY PUT-CONTAINER REQ(0004) FIELD-A(00141008 .

Now the container is created and filled with data. GETMAIN is used for the container too.9540160007 =0007 PG 1800 PGCP ENTRY . trace entries 0007 and 0010. trace entry 0011. Because the requirement is to put a 10M user area into the container. till all the data is inside the container.9540494382 =0009 PG 1701 PGCH EXIT .FUNCTION(CREATE_CONTAINER_POOL) CCSID(25) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD43E TIME-10:18:17. 5. 2. where the last piece of data. trace entries 0016 to 0017. 114 CICS Transaction Server V3 R1 Channels and Containers Revealed . trace entries 0008 and 0009. is placed. trace entries 0018 to 0019. trace entries 0014 to 0015. several of these GETMAINs are executed.9540501413 =0010 Figure 4-13 Create channel Figure 4-14 on page 115 shows the put container process: 1. As you can see. 2. the request for the getmain is for x’1000’ bytes.9540374069 =0008 PG 1801 PGCP EXIT .FUNCTION(CREATE_CHANNEL) RESPONSE(OK) CHANNEL_TOKEN(23E2A030) CONTAINER_POOL_TOKEN(24194030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A34A4116 TIME-10:18:17. GETMAIN is used in ECDSA subpool PGCSCB4K. PG 1700 PGCH ENTRY .Figure 4-13 shows the next couple of steps as follows: 1. After the set up of the environment for container creation is complete. It is allocated into the subpool PGCHCB in ECDSA. the variable length subpool. 3. The last GETMAIN was performed for another container subpool. to copy the data from user storage. GETMAIN is used for a PGCRCB block containing general informations about the container. Meaning. the put container command was executed. The channel is now created with the name CHN. the PGCSCBV in ECDSA. which could fit outside the 4 KB boundary. 4. This is because the allocation of the PGCSCB4K subpool owning containers is in 4 KB chunks. It is allocated into the subpool PGCPCB in ECDSA. The container pool is created too.FUNCTION(CREATE_CHANNEL) CHANNEL_NAME(CHN) LINK_LEVEL(CURRENT) CURRENT_CHANNEL(NO) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A34A4116 TIME-10:18:17. trace entries 0012 to 0013.FUNCTION(CREATE_CONTAINER_POOL) RESPONSE(OK) POOL_TOKEN(24194030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD43E TIME-10:18:17.

..... 00000053) GET_LENGTH(1000) SUSPEND(YES) REMARK(CSCB4K) LOCK_POOL (YES) LMLM_ADDRESS(23DCE2B0) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3AB2 TIME-10:18:17.....0105540866 =0019 Figure 4-14 Put container process Program BIGLOC next performs a start of transaction BIG....9548341413 =0012 SM 0302 SMGF EXIT . this time a positive response is received....0105220241 =0016 SM 0302 SMGF EXIT .....9548422272 =0013 SM 0301 SMGF ENTRY ...... Systems management and configuration 115 ..FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(24197030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA11AC TIME-10:18:17.. Chapter 4..FUNCTION(PUT_CONTAINER) POOL_TOKEN(24194030) CONTAINER_NAME(BIGONE) CALLER(EXEC) ITEM_DATA(25200008 . SM 0301 SMGF ENTRY ... 00000052) SUSPEND(YES) INITIAL_IMAGE(00) REMARK(CRCB) LOCK_POOL (YES) LMLM_ADDRESS(23DCE2B0) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA11AC TIME-10:18:17..FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFFAAC ..FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(26515000) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3B1E TIME-10:18:18......9548491022 =0015 ..0105428835 =0018 AP 00E1 EIP EXIT PUT-CONTAINER OK REQ(00F4) FIELD-A(00000000 ...0105241882 =0017 PG 1901 PGCR EXIT ..FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFFC14 ..9548454069 =0014 SM 0302 SMGF EXIT .FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(2419B000) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3AB2 TIME-10:18:17..... because channel CHN now exists....................... 0098968 TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A349FD62 TIME-10:18:17. PG 1900 PGCR ENTRY ...) FIELD-B(00003416 ..FUNCTION(PUT_CONTAINER) RESPONSE(OK) CONTAINER_TOKEN_OUT(24197030) GENERATION_NUMBER(1) INITIAL_GENERATION(1) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A349FD62 TIME-10:18:18..Refer to Figure 4-14..9548288444 =0011 SM 0301 SMGF ENTRY ...... This causes an inquire_channel command to be issued. 00000054) GET_LENGTH(7D0) SUSPEND(YES) REMARK(CSCBV) LOCK_POOL(YES) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3B1E TIME-10:18:18.FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFFB60 ...) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A510010C TIME-10:18:18...

2. The copy channel.0105708366 =0023 SM 0301 SMGF ENTRY .0105723444 =0024 SM 0302 SMGF EXIT . 4. trace entries 0023 to 0031.0105822116 =0029 Figure 4-15 Copy channel and container process (1) 116 CICS Transaction Server V3 R1 Channels and Containers Revealed .FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(23E2A060) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD69E TIME-10:18:18.0105672585 =0021 PG 1701 PGCH EXIT . Again. Trace entries 0032 to 0034 show the positive end of the process.0105700163 =0022 PG 1700 PGCH ENTRY .FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFF944 . because of the size of the container to be copied. 00000051) SUSPEND(YES) REMARK(CPCB) LOCK_POOL(YES) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCEA06 TIME-10:18:18. Figure 4-15 and Figure 4-16 show the process: 1. The final GETMAIN is run in the PGCSCBV subpool for variable data.0105768522 =0026 SM 0301 SMGF ENTRY .0105739616 =0025 PG 1800 PGCP ENTRY .FUNCTION(INQUIRE_CHANNEL) RESPONSE(OK) CHANNEL_TOKEN(23E2A030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A353F628 TIME-10:18:18. and container process was started. 3.FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFF9F8 . Trace entries 0021 to 0022 shows the inquire_channel succeeding. and the previously created container is created. PG 1700 PGCH ENTRY-FUNCTION(INQUIRE_CHANNEL) CHANNEL_NAME(CHN) LINK_LEVEL(CURRENT) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A353F628 TIME-10:18:18.0105789147 =0027 SM 0302 SMGF EXIT . 00000050) GET_LENGTH(30) SUSPEND(YES) INITIAL_IMAGE(00) REMARK (CHCB) LOCK_POOL(YES) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD69E TIME-10:18:18.FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(24194058) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCEA06 TIME-10:18:18. several GETMAINs were made in subpool PGCSCB4K to hold the 10 MB of data. container pool.A copy of the channel.0105801491 =0028 PG 1900 PGCR ENTRY .FUNCTION(COPY_CHANNEL) CHANNEL_TOKEN(23E2A030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A353F6F8 TIME-10:18:18. the container pool.FUNCTION(COPY_CONTAINER) CONTAINER_TOKEN(24197030) TO_POOL_TOKEN(24194058) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCE824 TIME-10:18:18.FUNCTION(COPY_CONTAINER_POOL) POOL_TOKEN(24194030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD73C TIME-10:18:18.

..Figure 4-16 is a continuation of the previous Figure 4-15. container pool..... and all the 4 KB areas composing the container were freed. Systems management and configuration 117 . The delete function for channel.... We start transaction BIG locally in the same CICS. 4....0105895632 =0031 ..... 3..0661032895 =0034 Figure 4-16 Copy channel and container process (2) Figure 4-17 on page 118 shows the next stage of the process: 1... 2.......FUNCTION(COPY_CHANNEL) RESPONSE(OK) COPIED_CHANNEL_TOKEN(23E2A060) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A353F6F8 TIME-10:18:18...... Also the 10 MB user storage associated to the transaction was freed. program BIGLOC issues a return as trace entry 0035 shows...FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(26516000) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3AB2 TIME-10:18:18. other than the copied container......... trace entry 0042... therefore........ 00000053) GET_LENGTH(1000) SUSPEND(YES) REMARK(CSCB4K) LOCK_POOL (YES) LMLM_ADDRESS(23DCF370) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FA3AB2 TIME-10:18:18..0661005004 =0033 PG 1701 PGCH EXIT ... and container start as trace entries 0036 to 0038 show. container pool.0660977504 =0032 PG 1801 PGCP EXIT .FUNCTION(COPY_CONTAINER_POOL) RESPONSE(OK) COPIED_POOL_TOKEN(24194058) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCD73C TIME-10:18:18...FUNCTION(GETMAIN) SUBPOOL_TOKEN(22CFFB60 ...FUNCTION(COPY_CONTAINER) RESPONSE(OK) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCE824 TIME-10:18:18... SM 0301 SMGF ENTRY .... Chapter 4.0105873132 =0030 SM 0302 SMGF EXIT .... PG 1901 PGCR EXIT ..... The owned channel....

....... PG 1901 PGCR EXIT .0749004694 =0041 SM 0F0D TASK-XM 1-0000 2-0000 3-0000 SMAR EVENT ....0662312661 =0036 PG 1800 PGCP ENTRY .FUNCTION(DELETE_CONTAINER) RESPONSE(OK) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCEB78 TIME-10:18:18.See Figure 4-17 for the trace entries....FUNCTION(DELETE_CONTAINER_POOL) RESPONSE(OK) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCDC34 TIME-10:18:18......FUNCTION(DELETE_OWNED_CHANNELS) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2F9F02E TIME-10:18:18. Figure 4-18 shows the flow.) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A5100172 TIME-10:18:18.FUNCTION(DELETE_OWNED_CHANNELS) RESPONSE(OK) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2F9F02E TIME-10:18:18....... Note: The channel token is the same as the one assigned to the copy of the channel that Figure 4-15 on page 116 shows in trace entry 0025....... task number 00044.0748971335 =0040 PG 1701 PGCH EXIT ....Storage_released .0662022895 =0035 PG 1700 PGCH ENTRY ... 118 CICS Transaction Server V3 R1 Channels and Containers Revealed . The transaction environment was set up and a bind for the channel was performed...0662325161 =0037 PG 1900 PGCR ENTRY ...0748928288 =0039 PG 1801 PGCP EXIT . The channel found was set as current channel.......) FIELD-B(08000E08 ... 2. 1...0662349379 =0038 ........................ which the trace entries 0045 to 0046 show.. AP 00E1 EIP ENTRY RETURN REQ(0004) FIELD-A(00140018 ..0752469692 =0042 25200008 11 FFFFFFFF FFFFFFFF Figure 4-17 Delete channel and container Transaction BIGL ended and control was passed to transaction BIG.. trace entries 0043 to 0044..USER storage at 25200008 KE_NUM-00EA TCB-QR /007E2D98 RET-A2940B30 TIME-10:18:18.FUNCTION(DELETE_CONTAINER_POOL) POOL_TOKEN(24194030) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCDC34 TIME-10:18:18..FUNCTION(DELETE_CONTAINER) CONTAINER_TOKEN(24197030) CALLER(SYSTEM) TASK-00043 KE_NUM-00EA TCB-QR /007E2D98 RET-A2FCEB78 TIME-10:18:18..

Systems management and configuration 119 . moving the data from the container to the user storage that trace entries 0050 to 0055 show. trace entries 0048 to 0049.FUNCTION(START_PROGRAM) PROGRAM(BIGREM) CEDF_STATUS(CEDF) EXECUTION_SET(FULLAPI) ENVIRONMENT_TYPE(EXEC) SYNCONRETURN(NO) LANGUAGE_BLOCK(23E23470) COMMAREA(00000000 .0822794147 =0045 PG 1701 PGCH EXIT .0822826569 =0047 SM 0C01 SMMG ENTRY . which contains the address and length of the area into which the container was copied. 4. Chapter 4. Notice the item buffer on trace entry 0053.0845828991 =0049 Figure 4-18 BIG transaction started locally The get container command was executed.0754895629 =0043 PG 1701 PGCH EXIT .FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(25200008) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A35AF9BC TIME-10:18:18. The user storage of 10M for the transaction was getmained. BIGREM program was started in trace entry 0047.FUNCTION(SET_CURRENT_CHANNEL) RESPONSE(OK) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2F9F0B8 TIME-10:18:18. The address and the length are those getmained in previous trace entry 0049 that Figure 4-18 shows.0823004538 =0048 SM 0C02 SMMG EXIT .FUNCTION(BIND_CHANNEL) RESPONSE(OK) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A368E744 TIME-10:18:18. See Figure 4-18.0754907739 =0044 PG 1700 PGCH ENTRY -FUNCTION(SET_CURRENT_CHANNEL)CHANNEL_TOKEN(23E2A060) OWNER(YES) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2F9F0B8 TIME-10:18:18.FUNCTION(BIND_CHANNEL) CHANNEL_TOKEN(23E2A060) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A368E744 TIME-10:18:18. 00000000) LINK_LEVEL(1) SYSEIB_REQUEST(NO) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2F9C742 TIME-10:18:18. PG 1700 PGCH ENTRY .0822806022 =0046 AP 1940 APLI ENTRY .3.FUNCTION(GETMAIN) GET_LENGTH(989680) SUSPEND(YES) INITIAL_IMAGE(FF) STORAGE_CLASS(USER) CALLER(EXEC) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A35AF9BC TIME-10:18:18.

..FUNCTION(INQUIRE_CHANNEL) RESPONSE(OK) CONTAINER_POOL_TOKEN(24194058) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A34A4260 TIME-10:18:18.FUNCTION(GET_CONTAINER_INTO) RESPONSE(OK) USERACCESS(ANY) ITEM_BUFFER(25200008 .1068619692 =0054 AP 00E1 EIP EXIT GET-CONTAINER OK REQ(00F4) FIELD-A(00000000 . as trace entry 0060 shows. 120 CICS Transaction Server V3 R1 Channels and Containers Revealed .0845915241 =0052 PG 1900 PGCR ENTRY .) FIELD-B(00003414 . the program BIGREM executes the return command. and the copy of channel. container pool.) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A510031C TIME-10:18:18. and container areas are freed. AP 00E1 EIP ENTRY GET-CONTAINER REQ(0004) FIELD-A(00140018 . container pool.. and container areas as trace entries 0057 to 0059 show. which the following steps explain: Program BIGREM issues the EXEC CICS RETURN command.. Figure 4-20 on page 121 shows trace entries for this phase.1068728129 =0055 Figure 4-19 Get container into storage The process completes. FREEMAINs that are issued for the subpools owning those areas... 00000000 .FUNCTION(INQUIRE_CHANNEL) CHANNEL_NAME(CHN) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A34A4260 TIME-10:18:18. Following this..) FIELD-B(08003414 . 00989680 .0845905788 =0051 PG 1701 PGCH EXIT . Note: The address of the container area that FREEMAIN was used for is the same as Figure 4-12 on page 113 shows.. 00989680) GENERATION_NUMBER(1) INITIAL_GENERATION(1) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A34A437E TIME-10:18:18. This leads to program control deleting the owned channel..Figure 4-19 shows the get container process. as trace entry 0056 shows..FUNCTION(GET_CONTAINER_INTO) POOL_TOKEN(24194058) CONTAINER_NAME(BIGONE) CALLER(EXEC) ITEM_BUFFER(25200008 .) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A510031C TIME-10:18:18.. 00989680) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A34A437E TIME-10:18:18. This was the address of the first 4 KB area that transaction BIGL allocated to copy the container.0845861335 =0050 PG 1700 PGCH ENTRY ..0855805866 =0053 PG 1901 PGCR EXIT .

.1069061879 =0057 PG 1800 PGCP ENTRY .....1178822114 =0063 ..FUNCTION(DELETE_OWNED_CHANNELS) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2F9F02E TIME-10:18:18.1069085864 =0058 PG 1900 PGCR ENTRY ...USER storage at 25200008 TASK-XM KE_NUM-00E9 TCB-QR /007E2D98 RET-A2940B30 TIME-10:18:18.................FUNCTION(FREEMAIN) SUBPOOL_TOKEN(22CFFB60 . 00000053) ADDRESS(26516000) FREE_LENGTH(1000) REMARK(CSCB4K) LOCK_POOL(YES) LMLM_ADDRESS(23DC67C0) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2FA3DF4 TIME-10:18:18.1069156645 =0060 .FUNCTION(DELETE_OWNED_CHANNELS) RESPONSE(OK) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2F9F02E TIME-10:18:18........) FIELD-B(08000E08 ......FUNCTION(DELETE_CONTAINER_POOL) RESPONSE(OK) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2FCDC34 TIME-10:18:18............The transaction BIG completes and the user storage is freed as trace entry 0064 shows........1178791879 =0062 PG 1701 PGCH EXIT ....Storage_released .................... SM 0F0D SMAR EVENT .. AP 00E1 EIP ENTRY RETURN REQ(0004) FIELD-A(00140018 .......................... See Figure 4-20.......... Systems management and configuration 121 ...................FUNCTION(DELETE_CONTAINER) RESPONSE(OK) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2FCEB78 TIME-10:18:18.1068762661 =0056 PG 1700 PGCH ENTRY .PG 1901 PGCR EXIT .) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A5100332 TIME-10:18:18.1069114692 =0059 SM 0301 SMGF ENTRY .........FUNCTION(DELETE_CONTAINER_POOL) POOL_TOKEN(24194058) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2FCDC34 TIME-10:18:18.....FUNCTION(DELETE_CONTAINER) CONTAINER_TOKEN(24197080) CALLER(SYSTEM) TASK-00044 KE_NUM-00E9 TCB-QR /007E2D98 RET-A2FCEB78 TIME-10:18:18.........1180003911 =0064 1-0000 25200008 2-0000 11 3-0000 FFFFFFFF FFFFFFFF Figure 4-20 Ending the transaction: delete channel Chapter 4..1178739145 =0061 PG 1801 PGCP EXIT .......

The transformer 1 program is called. and container BIGONE are allocated in the proper subpools.FUNCTION(LOCATE_AND_LOCK_TRANDEF) TRANSACTION_ID(BIG2) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3540016 TIME-12:17:05. we define a transaction named BIG1 in CICS region CICSPTA1. In Example 4-1 you can see the following: 1. which is our TOR. The TCTSE for CICS PAA1 is found. and container areas to be created in the same subpools. trace entries 0001 to 0004. which is the AOR.FUNCTION(LOCATE) DIRECTORY_TOKEN(22D00040) ENTRY_NAME(23DB82E4) DIRECTORY_NAME(TXD ) NAME(BIG2) 122 CICS Transaction Server V3 R1 Channels and Containers Revealed . Here the BIG2 transaction is defined as remote with remote name BIGR and running on region CICSPAA1.7. which performed the EXEC CICS GET CONTAINER. Example 4-1 Transmitting the channel: part 1 XM 0401 XMLD ENTRY . trace entry 0010. Transaction BIG2 is located. The BIG2 transaction starts program BIGREM. the ISP CONVERSE is issued. container pool. The environment to start transaction BIG is now ready. therefore.5 Multiregion operation flow In this example. 2. trace entry 0005. 2. An estimation of the amount of data to send is performed and the result is x’9896D4’. The start was issued for transaction BIG2. Channel CHN. Tracing the terminal-owning region The initial part of this is the same as described in Chapter 3. trace entries 0011 to 0012. See Figure 4-15 on page 116 and Figure 4-16 on page 117. The related COBOL program is BIGCN1 performing the same EXEC CICS PUT CONTAINER as BIGLOC did in the previous section to pass a 10M user area to the started transaction BIG2. See Figure 4-14 on page 115.2987805710 =0001 DD 0301 DDLO ENTRY . See Figure 4-12 on page 113 and Figure 4-13 on page 114. it used GETMAIN for the 10M user area and performed an EXEC CICS PUT CONTAINER. trace entries 0006 to 0009. which caused a copy of the channel. It is found that it had to run on CICS PAA1. 3. Transaction BIG1 was started and program BIGCN1 got control. 4. 3. 5.4. CICSPTA1 and CICSPAA1 were on the same MVS image and connected via MRO. container pool. “Programming” on page 59: 1.

2987886569 =0004 AP 00DF ISP ENTRY CONVERSE REQ(0003) FIELD-A(04000000 .2988236022 =0008 AP FD8B ZISP EXIT FACILITY_REQ TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB2DC TIME-12:17:05. The export_all function over MRO link is started. Chapter 4. The 32 KB buffer is GETMAINed.2987858366 =0003 XM 0402 XMLD EXIT .) FIELD-B(D7C1C1F1 PAA1) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3541DCE TIME-12:17:05.2987988444 =0005 AP FD02 ZLOC ENTRY LOCATE ID(PAA1) LOC_REQ ID_LOCAL TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB04C TIME-12:17:05.2988892507 =0010 AP 4E00 APCR ENTRY .FUNCTION(ESTIMATE_ALL) CHANNEL_TOKEN(23E1C270) COMMAND(START_MRO) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A35720BC TIME-12:17:05.TRANSFORMER_1 PLIST_ADDR(00140080) FUNCTION(10084C6E009A00104E008000155C00E8) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB582 TIME-12:17:05. trace entry 0015.2988941647 =0012 Now the sending of the container data over an MRO link can start.2987840241 =0002 DD 0302 DDLO EXIT .FUNCTION(ESTIMATE_ALL) RESPONSE(OK) BYTES_NEEDED(9896D4) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A35720BC TIME-12:17:05...2988124616 =0007 AP FD0B ZISP ENTRY FACILITY_REQ TCTTE(23E72480) ALLOCATE FREESYNC FREEREST UNPROT Q TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB2DC TIME-12:17:05. Systems management and configuration 123 . D7000000) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A29FEFBE TIME-12:17:05. 000000BC) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3540016 TIME-12:17:05.2988920007 =0011 AP 4E01 APCR EXIT .2988871257 =0009 AP D902 XFX ENTRY . trace entries 0013 to 0014. The IOAREALEN parameter cannot alter this length.2988018991 =0006 AP EA01 TMP EXIT FUNCTION(LOCATE) TABLE(TCTS) KEY(PAA1) ENTRY_ADDRESS(23E72480) RESPONSE(NORMAL) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A344F0CA TIME-12:17:05. length x’7FFF’.FUNCTION(LOCATE_AND_LOCK_TRANDEF) RESPONSE(OK) TRANDEF_TOKEN(24162AC0 ..FUNCTION(LOCATE) RESPONSE(OK) DATA_TOKEN(241D3190 .TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A29FEFBE TIME-12:17:05. 7. Example 4-2 on page 124 shows the process of sending the buffer of data to CICSPAA1: 6.

The response more_data is received because the container is 10M long...2990432819 =0018 AP DD22 ZIS2 EVENT .. An attempt to get the whole container into the acquired area is made.. trace entry 0017.PLUS LU62 FMH5..2989208210 =0014 AP 4E00 APCR ENTRY . 00007F69) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A313570C TIME-12:17:05.1 STATE SETTING TO SEND TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31351C8 TIME-12:17:05. AP DD21 ZIS2 EVENT .FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(29F12000) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A35700E6 TIME-12:17:05.. Example 4-2 Transmitting the channel: part 2 SM 0C01 SMMG ENTRY . SEQNUM(922) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31BD072 TIME-12:17:05. 00007F69 ...FUNCTION(EXPORT_ALL) TERMINAL_TOKEN(241CC9E0) CHANNEL_TOKEN(23E1C270) COMMAND(START_MRO) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3572574 TIME-12:17:05.FUNCTION(GET_CONTAINER_INTO) RESPONSE(EXCEPTION) REASON(MORE_DATA) ITEM_BUFFER(29F120A2 .. trace entry 0016. 9....FUNCTION(GETMAIN) GET_LENGTH(7FFF) TCTTE_ADDRESS(241CC9E0) SUSPEND(YES) INITIAL_IMAGE(00) STORAGE_CLASS (TERMINAL) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A35700E6 TIME-12:17:05.2989094147 =0013 SM 0C02 SMMG EXIT ...2990444694 =0019 AP FC01 ZARQ EVENT MRO/LU6... 00007F69 DATA_TOKEN_OUT(2CF4F000 . 000000A9) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A313570C TIME-12:17:05.RETURN CODE WAS 00000000 TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31BD072 TIME-12:17:05..IRC SWITCH FIRST TO SYSTEM (SCSCPAA1) .IRC OUTBOUND REQUEST HEADER: FMH RQE BB .2989228835 =0015 PG 1900 PGCR ENTRY .. 10.. the first 32 KB buffer is sent over an MRO link.. This process is repeated using 32 KB buffers till the whole container transmits to CICS PAA1.8.....2989956491 =0017 .2989264694 =0016 PG 1901 PGCR EXIT ..Therefore... 00000000 ...FUNCTION(GET_CONTAINER_INTO) CONTAINER_TOKEN(23E2A3F0) CALLER(SYSTEM) CONVERT(NO) ITEM_BUFFER(29F120A2 . as trace entries 0018 to 0020 show.299661969 =0020 The final part of the transmission phase is shown in Figure 4-3 on page 125: 124 CICS Transaction Server V3 R1 Channels and Containers Revealed .

.RETURN CODE WAS 00000000 TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31BD072 TIME-12:17:05...4050564694 =0023 AP DD21 ZIS2 EVENT ........4050543288 =0022 AP 4E01 APCR EXIT .. 00000F11) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A313582A TIME-12:17:05.5288638522 =0026 AP D903 XFX EXIT ... 13. 00000000 ..FUNCTION(EXPORT_ALL) RESPONSE(OK) TC_RESPONSE(0) TC_ABEND() TC_SENSE(00000000) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3572574 TIME-12:17:05......At the end of the process.Trace entries 0021 and 0022 show that only 1847 bytes remain..TRANSFORMER_4 PLIST_ADDR(00140080) FUNCTION(10084C6E00330010D9038000155C00E8) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB9B8 TIME-12:17:05.....) FIELD-B(D7C1C1F1 PAA1) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A3541DCE TIME-12:17:05. 12.4050437272 =0021 PG 1901 PGCR EXIT ....) FIELD-B(00001008 ..... trace entries 0026 to 0029.4050765788 =0025 .....11..) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A510036C TIME-12:17:05.FUNCTION(GET_CONTAINER_INTO) RESPONSE(OK) ITEM_BUFFER(29F1200C ...IRC OUTBOUND REQUEST HEADER: FMH RQE CD ......TRANSFORMER_4 PLIST_ADDR(00140080) FUNCTION(10084C6E003C001000DF8000155C00E8) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31FB9B8 TIME-12:17:05.The export_all function is terminated.. The last buffer is sent. transformer 4 got control and the ISP converse and the start are terminated. 00007FFF) DATA_TOKEN_IN(2D8E6000 . 00007FFF) DATA_TOKEN_OUT(00000000 00000000) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A313582A TIME-12:17:05......... as trace entries 0024 to 0025 show.4050753444 =0024 AP DD22 ZIS2 EVENT .... Therefore.. AP D902 XFX ENTRY .. Example 4-3 Transmitting the channel: part 3 PG 1900 PGCR ENTRY .....FUNCTION(GET_CONTAINER_INTO) CALLER(SYSTEM) CONVERT(NO) ITEM_BUFFER(29F1200C ......IRC SWITCH SUBSEQUENT TO SYSTEM (SCSCPAA1) . this time the get_container_into received a response OK instead of more_data as before.. See Example 4-3 for further trace entries..........5288663132 =0027 AP 00DF ISP EXIT CONVERSE REQ(0005) FIELD-A(04000000 .5288690944 =0028 AP 00E1 EIP EXIT START OK REQ(00F4) FIELD-A(00000000 .... Systems management and configuration 125 ...... 00001847 . trace entry 0023.5288781413 =0029 Chapter 4.. SEQNUM(1227) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A31BD072 TIME-12:17:05.......

. 00000054) ADDRESS(26515000) FREE_LENGTH(7D0) REMARK(CSCBV) LOCK_POOL(YES) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FA3E58 TIME-12:17:05.FUNCTION(DELETE_CONTAINER) CONTAINER_TOKEN(23E2A030) CALLER(SYSTEM) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FCEB78 TIME-12:17:05.......5289323132 =0036 .5289190007 =0033 PG 1900 PGCR ENTRY .5381298286 =0037 SM 0302 SMGF EXIT .. the channel and container environment for transaction BIG1 is freed..... as the trace entries from 0032 to 0041 show...) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A5100382 TIME-12:17:05............5289025085 =0031 PG 1700 PGCH ENTRY . SM 0301 SMGF ENTRY .. trace entries 0035 to 0036.FUNCTION(FREEMAIN) RESPONSE(OK) 126 CICS Transaction Server V3 R1 Channels and Containers Revealed ..FUNCTION(DELETE_OWNED_CHANNELS) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2F9F02E TIME-12:17:05....5289231960 =0034 SM 0301 SMGF ENTRY .FUNCTION(START_PROGRAM) RESPONSE(OK) ABEND_CODE() IGNORE_PENDING_XCTL(NO) Program_name(BIGCN1) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2F9C742 TIME-12:17:05....) FIELD-B(08000E08 . 00000053) ADDRESS(24195000) FREE_LENGTH(1000) REMARK(CSCB4K)LOCK_POOL(YES) LMLM_ADDRESS(23DB77C0) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FA3DF4 TIME-12:17:05.... 16.... Example 4-4 End of transaction on terminal-owning region AP 00E1 EIP ENTRY RETURN REQ(0004) FIELD-A(00140018 . the normal termination for transaction BIG1 occurs and the 10M user user storage is freed.....FUNCTION(FREEMAIN) RESPONSE(OK) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FA3DF4 TIME-12:17:05..... 15...The FREEMAIN for PGCSCB4K area is repeated until all the acquired storage for the container is freed..... See Example 4-4 for the trace entries.....FUNCTION(FREEMAIN) SUBPOOL_TOKEN(22CFFB60 ....5289284069 =0035 SM 0302 SMGF EXIT .5288814538 =0030 AP 1941 APLI EXIT ....Finally...FUNCTION(FREEMAIN) SUBPOOL_TOKEN(22CFFC14 ..FUNCTION(DELETE_CONTAINER_POOL) POOL_TOKEN(23E1D030) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FCDC34 TIME-12:17:05......BIG1 transaction now terminates: 14.........Example 4-4 shows that after the return and the termination of the start function that trace entries 0030 to 0031 show..5289163288 =0032 PG 1800 PGCP ENTRY .

and container for the incoming data as trace entries 0049 to 0051 show. The CICS Mirror transaction creates channel.5381425942 =0041 Tracing the application-owning region This section discusses the AOR CICSPAA1 and explains the processes that occurred. Input is received from CICSPTA1.FUNCTION(DELETE_CONTAINER) RESPONSE(OK) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FCEB78 TIME-12:17:05.FUNCTION(DELETE_OWNED_CHANNELS) RESPONSE(OK) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2F9F02E TIME-12:17:05.2991487583 =0043 AP DD20 ZIS2 EVENT .TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FA3E58 TIME-12:17:05. therefore. trace entry 0048.5381317504 =0038 PG 1901 PGCR EXIT . The seqnum is 922. trace entry 0047. is attached to manage the receiving of the data. Systems management and configuration 127 . number 00131. In Figure 4-5 on page 127: 1. 2. See Example 4-5.IRC PULL .IRC INBOUND REQUEST HEADER: FMH RQE BB . SEQNUM(922) Chapter 4. container pool. After CICS Mirror transaction starts.5381335942 =0039 PG 1801 PGCP EXIT .FUNCTION(DELETE_CONTAINER_POOL) RESPONSE(OK) TASK-00155 KE_NUM-00E8 TCB-QR /007E2D98 RET-A2FCDC34 TIME-12:17:05.DEQUEUE WORK ELEMENT TYPE (INITIAL INPUT RECEIVED) TIMESTAMP (BED22A6B3F258743) SCCB AT 7F560AE0 TCTTE AT 252C61F0 SESSION NAME >AC1 SYSTEM SCSCPTA1 TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-80087B84 TIME-12:17:05. trace entries 0042 to 0045. it is the first buffer sent as trace entry 0019 shows in Figure 4-2 on page 124.2992428208 =0044 AP DD15 CRNP EVENT .RETURN CODE WAS 00000000 TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-A4064BF0 TIME-12:17:05. A CICS Mirror transaction.DATA FROM SYSTEM (SCSCPTA1) .5381392583 =0040 PG 1701 PGCH EXIT . 3. the import_all function is performed.2991440864 =0042 AP FD0D ZIS2 ENTRY IRC TCTTE(252C61F0) GETDATA TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-A4064BF0 TIME-12:17:05. Example 4-5 CICS Mirror transaction creating the channel AP DD18 CRNP EVENT .

. till all the 10M of data are put into the container...... as trace entry 0055 shows.FUNCTION(CREATE_CHANNEL) CHANNEL_NAME(CHN) CCSID(25) LINK_LEVEL(CURRENT) CURRENT TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3133DCE TIME-12:17:05.....2992456879 =0045 AP FD11 ZATT ENTRY ATTACH ID(>AC1) TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-A4064380 TIME-12:17:05................ the put container terminates... trace entry 0052... 3..... to receive the first 32 KB buffer of data...2995352739 =0051 Figure 4-21 shows the put container process: 1....2992521333 =0046 XM 1101 XMAT ENTRY-FUNCTION(ATTACH) TRANSACTION_ID(CSMI) EXTERNAL_UOW_ID(22D471B4 . In this case it is repeated 132 times as you can see from the generation_number in trace entry 0056. A put container command is issued. This leads to a sequence of GETMAINs in subpool PGCSCB4K to acquire the container area for the 32 KB buffer of data.... When the next 32 KB buffer of data is available..2992576567 =0047 ....... After the first 32 KB buffer is received into the container... 4. 0000001B) PRIORITY(0) START_CODE(T) RETURN_NOT_FOUND(NO) USE_DTRTRAN(YES) PRIMARY_CLIENT_TYPE(MRO_SESSION) PRIMARY_CLIENT_REQ_BLOCK(252C61F0 ... 2. AP 4E00 APCR ENTRY ..FUNCTION(CREATE_CONTAINER_POOL) RESPONSE(OK) POOL_TOKEN(2418E000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCD43E TIME-12:17:05.2995160708 =0048 PG 1700 PGCH ENTRY .....TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-80087B84 TIME-12:17:05......FUNCTION(CREATE_CONTAINER_POOL) CCSID(25) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCD43E TIME-12:17:05.2995291020 =0050 PG 1801 PGCP EXIT ......FUNCTION(IMPORT_ALL) TERMINAL_TOKEN(252C61F0) DATA_START(42) COMMAND(START_MRO) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3571A70 TIME-12:17:05. another put container is issued and the cycle repeats. 128 CICS Transaction Server V3 R1 Channels and Containers Revealed .... trace entries 0053 to 0054.. 01C10000) TASK-00021 KE_NUM-0032 TCB-QR /007E2D98 RET-A31BF2BA TIME-12:17:05.2995210083 =0049 PG 1800 PGCP ENTRY .....

. Finally..... passing the channel CHN. The request to start transaction BIGR is received. PG 1901 PGCR EXIT ........ trace entry 0057. 2.. Systems management and configuration 129 ... thereby.... and container data being created...2995405708 =0052 SM 0301 SMGF ENTRY ... and deletes the container..... it detaches itself from the channel....4053323522 =0056 Figure 4-21 Put container cycle Figure 4-22 on page 130 shows the COPY channel process 1..FUNCTION(GETMAIN) RESPONSE(OK) ADDRESS(241BF000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FA3AB2 TIME-12:17:05......... When the copy of channel and container become available........2995547817 =0054 ......... 00007F69) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3134D00 TIME-12:17:05.. trace entries 0067 to 0068... PGCRCB... the CICS Mirror transaction starts the BIGR transaction. trace entry 0066.... This leads to a copy of the channel.............. container pool. The subpool storage related to the original container is freed..... in the same subpools (PGCPCB. Receiving the complete data into the container ends the import_all function..2996225786 =0055 .FUNCTION(GETMAIN) SUBPOOL_TOKEN(4215DB60 .... but not the copied one.......... PG 1901 PGCR EXIT .FUNCTION(PUT_CONTAINER) POOL_TOKEN(2418E000) CONTAINER_NAME(BIGONE) CALLER(SYSTEM) TYPE(USER) USERACCESS(ANY) CCSID(25) DATATYPE(BIT) PUT_TYPE(REPLACE) ITEM_DATA(253330A2 ...... 5.. Chapter 4...... 00000053) GET_LENGTH(1000) SUSPEND(YES) REMARK(CSCB4K) LOCK_POOL (YES) LMLM_ADDRESS(23E9E618) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FA3AB2 TIME-12:17:05...See Figure 4-21... PG 1900 PGCR ENTRY . duplicating amounts of storage allocated.....2995505864 =0053 SM 0302 SMGF EXIT ..FUNCTION(PUT_CONTAINER) RESPONSE(OK) GENERATION_NUMBER(132) INITIAL_GENERATION(1) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3134D00 TIME-12:17:05. 4.. because this is passed to BIGR....... 6. trace entries 0058 to 0059. 3. trace entry 0065............... CICS Mirror transaction ends and BIGR gets control.... and PGCSCB4K)... After this... with transaction number 00132...FUNCTION(PUT_CONTAINER) RESPONSE(OK) GENERATION_NUMBER(1) INITIAL_GENERATION(1) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3134D00 TIME-12:17:05..........

..4053832819 =0064 ..... AP 4E01 APCR EXIT .FUNCTION(DETACH_CHANNEL) CHANNEL_TOKEN(23FB9000) DELETE(YES) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3571BA8 TIME-12:17:05.4053713210 =0061 PG 1700 PGCH ENTRY ...4342232663 =0066 PG 1800 PGCP ENTRY ....FUNCTION(DELETE_CONTAINER) CONTAINER_TOKEN(24195000) CALLER(SYSTEM) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCEB78 TIME-12:17:05.................FUNCTION(COPY_CHANNEL) CHANNEL_TOKEN(23FB9000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A353DC98 TIME-12:17:05....) FIELD-B(08001008 .FUNCTION(DELETE_CONTAINER_POOL) POOL_TOKEN(2418E000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCD9B8 TIME-12:17:05.4342270319 =0068 Figure 4-22 COPY the channel 130 CICS Transaction Server V3 R1 Channels and Containers Revealed ....4053451569 =0058 AP E160 EXEC ENTRY START TRANSID('BIGR' AT X'23E9D298') INTERVAL(0 AT X'23E9D294') CHANNEL('CHN ' AT X'A3E9D2AA') SYSEIB NOHANDLE ASM TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-80082964 TIME-12:17:05.............) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FFA10C TIME-12:17:05...Z..FUNCTION(IMPORT_ALL) RESPONSE(OK) CHANNEL_TOKEN(23FB9000) CHANNEL_NAME(CHN) TC_RESPONSE(0) TC_ABEND() TC_SENSE (00000000) SIZE(9896D4) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A3571A70 TIME-12:17:05... AP E161 EXEC EXIT START TRANSID('BIGR' AT X'23E9D298') INTERVAL(0 AT X'23E9D294') CHANNEL('CHN ' AT X'A3E9D2AA') RESP(0) RESP2(0) SYSEIB NOHANDLE ASM TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-80083F64 TIME-12:17:05.......FUNCTION(INQUIRE_CHANNEL) CHANNEL_NAME(CHN)LINK_LEVEL(CURRENT) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A353DBC8 TIME-12:17:05.FUNCTION(COPY_CONTAINER_POOL) POOL_TOKEN(2418E000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCD73C TIME-12:17:05..4342250241 =0067 PG 1900 PGCR ENTRY .....4053351569 =0057 AP 00E1 EIP ENTRY START REQ(0004) FIELD-A(23E9CFB0 ...See Figure 4-22 for trace entries....4053723210 =0062 PG 1800 PGCP ENTRY ..4053688366 =0060 PG 1701 PGCH EXIT ..FUNCTION(INQUIRE_CHANNEL) RESPONSE(OK) CHANNEL_TOKEN(23FB9000) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A353DBC8 TIME-12:17:05..4053777819 =0063 PG 1900 PGCR ENTRY .4342152585 =0065 PG 1700 PGCH ENTRY ..4053578132 =0059 PG 1700 PGCH ENTRY ........FUNCTION(COPY_CONTAINER) CONTAINER_TOKEN(24195000) TO_POOL_TOKEN(2418E028) TASK-00131 KE_NUM-00EB TCB-QR /007E2D98 RET-A2FCE824 TIME-12:17:05.

resulting in the find of the proper container... An inquiry for channel CHN is performed. trace entries 0070 to 0071.5289943989 =0073 SM 0C01 SMMG ENTRY .) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A6C0010C TIME-12:17:05. trace number 0075.5289988286 =0074 AP 00E1 EIP ENTRY GET-CONTAINER REQ(0004) FIELD-A(00141018 .5289685942 =0070 PG 1701 PGCH EXIT .) FIELD-B(08003414 ..... Container BIGONE is copied into the GETMAINed user storage as the trace entries 0078 to 0080 show. as trace entry 0069 shows.5312397663 =0075 Figure 4-23 Get container start To conclude the get container process the following steps are performed as Figure 4-24 on page 132 shows: 4...FUNCTION(SET_CURRENT_CHANNEL) RESPONSE(OK) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A2F9F0B8 TIME-12:17:05. and the current channel is set. 3. The get container command is issued. Systems management and configuration 131 . trace entries 0076 to 0077. PG 0901 PGPG ENTRY .. trace entries 0072 to 0074. 5.FUNCTION(INITIAL_LINK) PROGRAM_NAME(BIGREM) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A29404D8 TIME-12:17:05. 2.5289562270 =0069 PG 1700 PGCH ENTRY -FUNCTION(SET_CURRENT_CHANNEL) CHANNEL_TOKEN(23FB9030)OWNER(YES) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A2F9F0B8 TIME-12:17:05... The BIGR transaction performs the initial link to program BIGREM..Figure 4-23 shows the start of the get container process: 1.) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A6C000B2 TIME-12:17:05.5289882895 =0072 AP E160 EXEC ENTRY GETMAIN SET( AT X'00141188') FLENGTH(10000000 AT X'A6C00164') INITIMG(X'FF' AT X'26C00122') ASM TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-80082964 TIME-12:17:05.5289696333 =0071 AP 00E1 EIP ENTRY GETMAIN REQ(0004) FIELD-A(00141018 .FUNCTION(GETMAIN) GET_LENGTH(989680) SUSPEND(YES) INITIAL_IMAGE(FF) STORAGE_CLASS(USER) CALLER(EXEC) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A35B075C TIME-12:17:05.) FIELD-B(08000C02 . Chapter 4. BIGREM program GETMAINed the 10M user storage required.

4. 00989680) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A34A40CE TIME-12:17:05.5319576257 =0078 PG 1901 PGCR EXIT . This leads to the remaining copied channel and container storage allocated in ECDSA subpools. PG 1700 PGCH ENTRY .FUNCTION(INQUIRE_CHANNEL) RESPONSE(OK) CONTAINER_POOL_TOKEN(2418E028) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A34A3FB0 TIME-12:17:05. the communication protocol is different. 00989680) GENERATION_NUMBER(1) INITIAL_GENERATION(1) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A34A40CE TIME-12:17:05.6 Intersystem communication flow The trace activated on ISC connection between CICSPTA1 and CICSPAA4 show exactly the same behavior as the MRO tracing from a channel and container point of view. However. 00000000 .5312517038 =0077 PG 1900 PGCR ENTRY .FUNCTION(INQUIRE_CHANNEL) CHANNEL_NAME(CHN) TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-A34A3FB0 TIME-12:17:05.7. as are the modules involved.5524520944 =0080 Figure 4-24 Get container end The BIGREM program has an EXEC CICS RETURN to end the process.5312502663 =0076 PG 1701 PGCH EXIT . the trace entries for this process are not illustrated. but the management of channel and container storage inside the TOR and AOR is very similar to the MRO process discussed previously.5524355788 =0079 AP E161 EXEC EXIT GET CONTAINER('BIGONE ' AT X'001411A8') CHANNEL('CHN ' AT X'80141198') INTO( AT X'26D00008' FLENGTH(10000000 AT X'26C00123') RESP(0) RESP2(0) ASM TASK-00132 KE_NUM-00EC TCB-QR /007E2D98 RET-80083F64 TIME-12:17:05.FUNCTION(GET_CONTAINER_INTO) RESPONSE(OK) USERACCESS(ANY) ITEM_BUFFER(26D00008 .See Figure 4-24 for trace entries. However. 132 CICS Transaction Server V3 R1 Channels and Containers Revealed .FUNCTION(GET_CONTAINER_INTO) POOL_TOKEN(2418E028) CONTAINER_NAME(BIGONE) CALLER(EXEC) ITEM_BUFFER(26D00008 . 00989680 .

© Copyright IBM Corp. All rights reserved.5 Chapter 5. Sample application This chapter describes the process you can use to migrate an existing Customer Information Control System (CICS) application to exploit channels and containers rather than using communication areas (COMMAREAs). this chapter uses the CICS catalog manager example application. 133 . 2006. In order to show the migration process to the new function.

The Web service support extension for the base application provides a Web client front end and a Web service endpoint. either the Web client front end or the 3270 interface of the catalog manager application. The CICS catalog example program has a modular structure with well defined interfaces. What is the requirement to change the design of such an approved existing CICS application? For an existing CICS application the COMMAREA is equivalent to the functions that channels and containers provide. you can exceed the limit of COMMAREAs easily. If you do not have any COMMAREA constraints and if you have no plans to extend your application design. then there is no reason to migrate the application to the new function. Therefore. which eventually would exceed the COMMAREA limit. You can extend the CICS catalog example application to allow it to display the corresponding catalog item image on the Web client front end. Therefore. migrate the CICS catalog example application to utilize the new function of channels and containers.1 Implementation scenario The original CICS catalog example application is designed to demonstrate how to extend a 3270 CICS Common Business Oriented Language (COBOL) application to exploit Web service support.5. In order to deal with the relevant gif files for the catalog items. The EXEC CICS LINK commands calls these various components using a COMMAREA. can drive the business logic of the example application. This section covers the following topics: The CICS catalog manager example application The base application Migration steps: CICS back end Stage 1: migration to the new function Exploiting channels and containers: a first approach Best practise approach: replacing the COMMAREA Stage 2: catalog item images support Running the application Performance 134 CICS Transaction Server V3 R1 Channels and Containers Revealed .

an outbound Web service call is made to an external dispatch manager Web service. It is a simple application that provides the functions to list details of an item in the catalog and then selects a quantity of that item to order. Then the application updates the catalog to reflect the new stock levels. Figure 5-1 shows the application migration environment at the stage 0 level.5. Sample application 135 . to make existing information that CICS controls. S tage 0: T he base application 3270 em ulation C IC S1 BM S presentation m anager (D FH O XG U I) C atalog m anager (D FH O XC M N ) D ata store T yp e = V S AM O u tbo u nd W eb S e rvice = Y E S VSAM data handler (D FH O XV D S) D ispatch m anager (D FH O X W O D ) Pipeline (EXPIPE02) VSA M C atalog data (EXM PC AT) O rder dispatch end point (D FH O XO D E) C IC S 2 O rder dispatch end point Exam pleApp D ispatchO rder. The following is a discussion of the CICS implementation of this process.ear W e bS ph ere A pp licatio n S e rve r Figure 5-1 CICS catalog manager example application Chapter 5. The example application is a catalog management. If enabled in the application configuration. There are two stages in performing the migration.1. purchase order style application. The catalog manager example application accesses an order catalog that a Virtual Storage Access Method (VSAM) file stores. which this chapter discusses in its latter half. available to service-oriented architecture (SOA) service requestors.1 The CICS catalog manager example application The Web services example application demonstrates the process to help you use SOAP and the Web services.

The catalog manager program has other functions that it also implements. Module DFH0XGUI provides the presentation logic.1.2 The base application The base application. such as Web service. We provide a new Web client front end that has the capability to display the corresponding catalog item images. DFH0XGUI uses an EXEC CICS LINK command that passes the COMMAREA structure that Example 5-1 on page 144 shows. which makes it easier to extend the application to support newer technology. such as the outbound Web service function. which exclusively manages the process of sending and receiving the required BMS maps. the 3270 user interface and the provided Web client front end can call the catalog manager example business logic. which in turn links to the VSAM data handler stub DFH0XVDS. The catalog manager module DFH0XCMN provides the business logic. with its 3270 user interface provides functions with which you can: List the contents of a stored catalog: inquire catalog Select an item from the list: inquire single Enter a quantity to order: place order The application has a modular design. there are three modules involved in the process. Components of the base application When you call the CICS catalog manager example using the basic mapping support (BMS) 3270 interface. DFH0XGUI links to the catalog manager program DFH0XCMN in order to perform the supported functions against the catalog.5. We also provide a wrapper program for the Web client front end that invokes the catalog manager program by passing a channel rather than a COMMAREA. therefore they are not discussed in this section. As previously mentioned. Figure 5-2 shows that there are two parts that separate the application. 136 CICS Transaction Server V3 R1 Channels and Containers Revealed . They do not play a role in the channels and containers migration project.

Provide a new Web client front end to it that can additionally display the corresponding item images. Components of base application DFH0XGUI BMS presentation manager VSAM DFH0XCMN Catalog manager Data Handler VSAM DFH0XVSM Figure 5-2 Components of the base application Migration considerations You do not want to migrate the presentation logic DFH0XGUI to the new function. the catalog manager must migrate. The presentation logic of the application calls the data separation logic first. There is an alternative solution to avoid migrating the presentation logic of the catalog manager example program. the presentation logic remains unaffected. The data separation Chapter 5. Therefore. which is passing a channel to link to the catalog manager program. The gif image this chapter uses to demonstrate how to display catalog item images has a size of 46 KB. At this point. Figure 5-3 shows the new structure of the base application. However.See Figure 5-2. the relevant gif images cannot pass between the wrapper program and the catalog manager using COMMAREAs. However. Therefore. Because of their sizes. you require to migrate the catalog manager module DFH0XCMN to the new channels and container functionality. The presentation logic is using the COMMAREA and it is inconceivable that you get any constraints with it in the future. You can create an additional routine that the presentation logic DFH0XGUI can call in order to separate the COMMAREA structure to individual containers. Sample application 137 . which exceeds the COMMAREA limit. the presentation logic uses an EXEC CICS LINK command that passes a COMMAREA to call the catalog manager module DFH0XCMN. you want to use a wrapper program for the Web client front end that uses an EXEC CICS LINK command.

3.logic then calls the business logic using an EXEC CICS LINK command that is passing a channel rather than a COMMAREA. 2. They also discuss the addition of a new function to the catalog manager that allows you to retrieve the corresponding image of a catalog item before any order of the item takes place. In order to migrate the back end of the CICS catalog manager example program to the new function. 138 CICS Transaction Server V3 R1 Channels and Containers Revealed . During stage1. You have to separate the COMMAREA structure into individual containers first. This chapter discusses the structure of the data separation logic in the latter half. You do not want to migrate the presentation logic DFH0XGUI. you receive the information from the relevant containers back to the COMMAREA. You can create the data separation module DFH0XSEP. The module takes the COMMAREA structure from DFH0XGUI and creates suitable containers for the catalog manager DFH0XCMN. Data separation routine BMS presentation manager VSAM DFH0XSEP Data separation Catalog manager Data Handler VSAM Figure 5-3 Data separation module DFH0XSEP 5. you change the logic of the catalog manager module to use channels and containers. you have to perform the following steps: 1. Module DFH0XSEP does not exist so far. but you have to change the module in order to link to the data separation module DFH0XSEP.3 Migration steps: CICS back end The previous sections discuss the basic structure of the CICS catalog manager example program. Migration of the catalog manager module DFH0XCMN The catalog manger migrates in two stages. You have to create it. When the catalog manager returns.1.

you have to consider the way to separate the COMMAREA to individual containers. As mentioned previously. 5. the logic of DFH0XCMN manages the channels that get passed from either the Web client front end or from the presentation logic. After that. make sure that the basic functions of the application still work properly.Following this. The new routine gets control from the catalog manager DFH0XCMN. the item image is available when you return to the catalog manager.1. However. inquire single. Create a new module that reads the catalog item image from HFS. you can add the display catalog item support to the catalog manager module. Store the item images to a Hierarchical File System (HFS) data set. Also. This is the simplest and quickest way to migrate the catalog manager application. check that the item image is available in a container when the catalog manager returns. Verification of the extended function of the base application When you have completed step 4 and step 5. Verification of the basic functions When the stage1 migration process has completed. The catalog manager module DFH0XCMN is modified to retrieve the item image from the HFS data set. 7. You have to make sure that the basic functions inquire catalog. Before you start. Migration of the catalog manager DFH0XCMN stage2 During the stage2 migration step. and place order still work fine after migrating the catalog manager application. 6. it gets the item image from the HFS data set and puts it into a container that the current channel of the catalog manager program owns. we do not recommend replacing the COMMAREA with just one single container as a best practice. 4. 5. It is possible to use a channel with a single container to replace the COMMAREA that passes between the presentation logic and the catalog manager. you can perform a function test of the base application using the 3270 interface. Sample application 139 . Therefore. Chapter 5. This chapter describes this process later. the start is at stage 1 in order to create the data separation module.4 Stage1: migration to the new function This section describes the process of migrating the CICS catalog manager example program to exploit the functionality of channels and containers.

the names of the containers used.We recommend that the process to replace the existing COMMAREA structure must be according to the following statements: Use separate containers for input and output. Use a dedicated container for error information.ear WebSphere Application Server Figure 5-4 Catalog manager application at stage1 level 140 CICS Transaction Server V3 R1 Channels and Containers Revealed . Include the copybook in both the client and the server program. Use separate containers for each structure. Use a copybook that records the name of the channel. Stage 1: Separation of data 3270 emulation CICS1 BMS presentation manager (DFHOXGUI) COMMAREA Data separator Catalog manager (DFHOXCMN) Datastore Type = VSAM Channel Outbound WebService = YES VSAM data handler (DFHOXVDS) Dispatch manager (DFHOXWOD) Pipeline (EXPIPE02) VSAM Catalog data (EXMPCAT) Order dispatch end point (DFHOXODE) CICS2 Order dispatch end point ExampleApp DispatchOrder. and defines the data fields that map to the containers. See Figure 5-4.

The following section discusses the disadvantages of this approach.There are two migration scenarios that you can perform: A first approach is where you do not split the COMMAREA structure into separate containers. Exploiting channels and containers: a first approach The simplest approach to convert an existing CICS applications to take advantage of containers and channels may seem to be replacing an existing COMMAREA implementation by creating a new channel with a single container that holds the existing COMMAREA structure. We provide a data separation module DFH0XSEP and also a migrated version of catalog manager module DFH0XCMN. the application suite cannot take complete advantage of the benefits of the containers and channels approach. Sample application 141 . However. Chapter 5. The best practice approach is where you split the COMMAREA structure of the application into separate containers according to the statements mentioned previously. this approach does not enable you to separate a monolithic parameter block into its separate component parts. Consequently. A detailed description of the best practice approach to the new function is presented in the next section. in order to demonstrate the simplest approach to converting existing CICS applications to use channels and containers.

If you have a COMMAREA available. or place order. Create a new module DFH0XSEP that executes the structure Figure 5-5 illustrates. 2. DFH0XSEP gets control from DFH0XGUI through the EXEC CICS LINK. write an error message and issue an abnormal end EXCA through EXEC CICS ABEND. DFH0XSEP structure DFH0XGUI CA available? N abend EXEC CICS LINK PROGRAM(DFHXSEP) COMMAREA Y Create REQ container Y INQC ? create INQC container N Y INQS ? create INQS container N inv-request ORDER? Y Create ORDER container EXEC CICS LINK PROGRAM(DFHXCMN) CHANNEL DFH0XCMN Figure 5-5 DFH0XSEP structure The following steps discuss the logic of the structure: 1. create a separate input container for the required request. DFH0XGUI passes a COMMAREA. which can be inquire catalog. inquire single. If there is no COMMAREA available. 3.Best practice approach: replacing the COMMAREA This section discusses the process to migrate the CICS catalog manager example to the new function using the best practice approach. 142 CICS Transaction Server V3 R1 Channels and Containers Revealed .

Chapter 5. Fields used in place order This section of the COMMAREA structure is used for the place order function. We recommend to create the output containers in the server program. call the catalog manager using an EXEC CICS LINK command passing the channel holding the containers. It also redefines CA-REQUEST-SPECIFIC. The general part of the structure also contains a field for the result of the different requests that is CA-REQUEST-SPECIFIC. Fields used in inquire catalog This section of the COMMAREA structure is used for the inquire catalog function. evaluate the request type and create another input container according to the relevant request. The structure consists of the following parts: A general part This part contains the request type and structure items for the return code and the response message. Do not create any output containers in the data separation logic. After that.4. When the evaluation of the request type is complete. It also redefines CA-REQUEST-SPECIFIC. Fields used in inquire single This section of the COMMAREA structure is used to describe the fields used for the inquire single function. COMMAREA structure Example 5-1 shows the COMMAREA structure that the CICS catalog manager example program uses. Do not create a separate input container for return codes and messages at present. Following is a more practical discussion about how you can separate the COMMAREA structure. 5. Sample application 143 . It redefines CA-REQUEST-SPECIFIC and uses a table to store 15 catalog items. The catalog manager module creates this later. which in our case is the catalog manager module DFH0XCMN.

05 FILLER PIC X(840). 05 CA-ITEM-REF-NUMBER PIC 9(4). 07 IN-SNGL-STOCK PIC 9(4). 05 FILLER PIC 9(4). 07 ON-SNGL-ORDER PIC 9(3). 05 CA-ITEM-REF-REQ PIC 9(4). 03 CA-REQUEST-SPECIFIC PIC X(911). 05 CA-ITEM-COUNT PIC 9(3). 07 CA-DEPARTMENT PIC 9(3). 05 CA-LIST-START-REF PIC 9(4). 07 IN-STOCK PIC 9(4). 144 CICS Transaction Server V3 R1 Channels and Containers Revealed . Fields used in Place Order 03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.See Example 5-1. Fields used in Inquire Catalog 03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC. 05 FILLER PIC 9(3). 07 CA-COST PIC X(6). 07 CA-SNGL-ITEM-REF PIC 9(4). 07 CA-SNGL-COST PIC X(6). 05 CA-CAT-ITEM REDEFINES CA-INQUIRY-RESPONSE-DATA OCCURS 15 TIMES. 05 CA-LAST-ITEM-REF PIC 9(4). 07 ON-ORDER PIC 9(3). 07 CA-ITEM-REF PIC 9(4). 07 CA-SNGL-DESCRIPTION PIC X(40). 03 CA-RETURN-CODE PIC 9(2). 05 CA-QUANTITY-REQ PIC 9(3). 05 CA-CHARGE-DEPT PIC X(8). 05 CA-SINGLE-ITEM. 05 FILLER PIC X(888). Fields used in Inquire Single 03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC. 07 CA-DESCRIPTION PIC X(40). 05 CA-USERID PIC X(8). 07 CA-SNGL-DEPARTMENT PIC 9(3). Example 5-1 COMMAREA structure of catalog manager example * * * * Catalogue COMMAREA structure 03 CA-REQUEST-ID PIC X(6). 05 CA-INQUIRY-RESPONSE-DATA PIC X(900). 03 CA-RESPONSE-MESSAGE PIC X(79).

you can separate the COMMAREA structure in to the following functional parts: The request ID CA-REQUEST-ID is part of the general section and you must place it in a single input container. The catalog manager module creates the result container. Keep the CA-INQUIRE-REQUEST structure in a separate container. Keep the CA-INQUIRE-SINGLE structure in a single container. we decided to keep the structures for each function in a single container rather than using further containers. You can separate the CA-INQUIRE-REQUEST structure further.Data separation of the structure According to the best practice approach. However. Return code and response message We recommend that you place return codes and response messages in a separate output-only container. The CA-ORDER-REQUEST structure also goes to a single container. Copy the result information for each function to a separate container. to implement channel and containers. It is good practice to use different containers for input and output processing. Sample application 145 . Chapter 5.

check if you have completed the following: Used different containers for input and output operations. This simplifies the copybook structure and makes the program easier to understand. CA-SNGL-ITEM-REF CA-SNGL-DESCRIPTION CA-SNGL-DEPARTMENT CA-SNGL-COST IN-SNGL-STOCK ON-SNGL-ORDER CA-ORDER-REQUEST CA-USERID CA-CHARGE-DEPT CA-ITEM-REF-NUMBER CA-QUANTITY-REQ Container request-type return-code-msg result inquire-cat inquire-single order-item Figure 5-6 Data separation of the COMMAREA structure After separating the COMMAREA structure according to best practices in order to migrate the application to the new function. CA-Structure CA-REQUEST-ID CA-RETURN-CODE CA-RESPONSE-MESSAGE CA-REQUEST-SPECIFIC CA-INQUIRE-REQUEST CA-LIST-START-REF CA-LAST-ITEM-REF CA-ITEM-COUNT CA-CAT-ITEM CA-ITEM-REF CA-DESCRIPTION CA-DEPARTMENT CA-COST IN-STOCK ON-ORDER CA-INQUIRE-SINGLE CA-ITEM-REF-REQ CA-SINGLE-ITEM. Used a dedicated container for return code and response messages.Figure 5-6 illustrates the separation of the COMMAREA structure to different containers. 146 CICS Transaction Server V3 R1 Channels and Containers Revealed . Separated the structures of the individual functions into their own containers. Input containers that the server program has not changed are not returned to the caller.

01 GET-IMG-ERROR PIC X(16) VALUE 'error-msg'. 01 IMAGE-REF PIC X(16) VALUE 'ref-no'. 01 CHN-NAME PIC X(16). 01 CATALOG-SERVER PIC X(8) VALUE 'CTLGSERV'. 01 IMG-DIR-CONTENTS PIC X(18) VALUE '/u/cicsrs9/images/'. 01 INQC PIC X(16) VALUE 'inquire-cat'. Example 5-2 Copybook DFH0X02 * * * Channel name 01 CMN-CHANNEL PIC X(16) VALUE 'cmn-channel'. 01 RESULT PIC X(16) VALUE 'result'. Use the other containers in the structure during stage 2 of the migration. Sample application 147 . The copybook must define the data fields that map to the containers. 01 IMG-CONTAINER PIC X(16) VALUE 'gif-data'. 01 INQS PIC X(16) VALUE 'inquire-single'. Container names 01 REQ PIC X(16) VALUE 'request-type'. This chapter discusses this process later. 01 SINGLE-CNT PIC X(16) VALUE 'single'. 01 RC-MSG PIC X(16) VALUE 'return-code-msg'. See Example 5-2 that illustrates the creation of copybook DFH0X02. 01 ORDR PIC X(16) VALUE 'order-item'. 01 IMG-REF-NUMBER PIC 9(2) VALUE 10.DFH0X02 copybook It is best practice to create a copybook that records the name of the channel and the names of the containers that you use. Chapter 5. The data separation routine DFH0XSEP creates the following containers: request-type return-code-msg inquire-cat inquire single order-item The catalog manager module creates the result container. 01 IMG-DIR PIC X(16) VALUE 'img-dir'. Example 5-2 shows the copybook that our example uses for the data separation routine and for the catalog manager module DFH0XCMN. when you add the item image support to the catalog manager. The first part of the structure defines the use of the channel name and the container names to migrate the application. Define the data fields used by the program 01 XCMNPROG PIC X(8) VALUE 'EFH2XCMN'.

* Inquire catalog container structure 01 INQUIRE-CAT. * Return code & MSG container structure 01 RETCODE-MSG. If the COMMAREA is passed to DFH0XSEP. * Order request catalog container structure 01 ORDER-REQUEST. 03 RC PIC 9(2). Therefore. 03 ITEM-REF-REQ PIC 9(4). 03 FILLER PIC 9(4). Check in the mainline section of the program to see if you were passed a valid COMMAREA from DFH0XGUI. 03 RESPONSE-MESSAGE PIC X(79). then create the first input channel. you can also do the following: 1. 03 ITEM-COUNT PIC 9(3). 4. Creating DFH0XSEP This section discusses steps that we used in our example to create the data separation module DFH0XSEP. Prepare a suitable error message and issue an EXEC CICS ABEND if there is no COMMAREA available. 148 CICS Transaction Server V3 R1 Channels and Containers Revealed . 03 LIST-START-REF PIC 9(4). move CA-REQUEST to the structure that maps the request ID container. 03 LAST-ITEM-REF PIC 9(4). 03 QUANTITY-REQ PIC 9(3). 3. 03 ITEM-REF-NUMBER PIC 9(4). 03 USERID PIC X(8). Separate the existing COMMAREA structure of the catalog manager example program into different containers. 2. 03 CHARGE-DEPT PIC X(8). * Inquire single container structure 01 INQUIRE-SINGLE. 03 FILLER PIC 9(3). Copy the structure of copybook DFH0X02 to module DFH0XSEP.* Request-ID container structure 01 REQUEST-ID PIC X(6). 5. The first channel takes only the request type.

* Set up return code & Msg container MOVE CA-RETURN-CODE TO RC. Evaluate the request type and set up the appropriate container that corresponds to the request. * Create return code and message container EXEC CICS PUT CONTAINER(RC-MSG) CHANNEL(CMN-CHANNEL) FROM(RETCODE-MSG) FLENGTH(LENGTH OF RETCODE-MSG) END-EXEC.6. Example 5-3 shows the code snippet our example uses to create the request type container. MOVE CA-RESPONSE-MESSAGE TO RESPONSE-MESSAGE. 8. Example 5-3 also shows how to create the container that takes the return code and response messages. Example 5-3 Set up request ID container * Set up request-id container MOVE CA-REQUEST-ID TO REQUEST-ID. Move the return code and response message to the structure that maps the container. Sample application 149 . The name of the container is return-code-msg. 7. * Create request container EXEC CICS PUT CONTAINER(REQ) CHANNEL(CMN-CHANNEL) FROM(REQUEST-ID) FLENGTH(LENGTH OF REQUEST-ID) END-EXEC. Set up the container with the appropriate request type structure. Do not pass data structures superfluously. Chapter 5.

Example 5-4 Evaluate request type structure EVALUATE CA-REQUEST-ID WHEN '01INQC' * prepare request container for catalog inquiry PERFORM CATALOG-INQUIRE WHEN '01INQS' prepare request container for inquire single PERFORM INQUIRE-SIN WHEN '01ORDR' prepare reuest container for place order request PERFORM PLACE-ORDER WHEN OTHER * * The following three examples show the paragraphs our example uses to set up the structures that map to the data fields of the containers. Example 5-5 shows the creation of the container that takes the structure for the inquire catalog request. CATALOG-SIN creates the container for the inquire single function. PLACE-ORDER creates the container for the order function. They define the start of the item list and are a reference of the displayed item. Move two parameters from the COMMAREA to the INQUIRE-CAT structure.Example 5-4 shows how to evaluate the request type in order to create the corresponding container. This example uses three individual paragraphs to set up the containers: CATALOG-INQUIRE creates the container for the inquire catalog function. The parameters are LIST-START-REF and LAST-ITEM-REF. 150 CICS Transaction Server V3 R1 Channels and Containers Revealed .

you require to pass one parameter. In order to execute the inquire single request. Example 5-6 Create inquire single container *================================================================* * Catalog inquire single routine * * * *================================================================* INQUIRE-SIN. EXIT. * Create inquire catalog container EXEC CICS PUT CONTAINER(INQC) CHANNEL(CMN-CHANNEL) FROM(INQUIRE-CAT) FLENGTH(LENGTH OF INQUIRE-CAT) END-EXEC. Chapter 5. EXIT. Move CA-ITEM-REF-REQ from the COMMAREA to the INQUIRE-SINGLE structure. which maps the data fields of the container.See Example 5-5. * Set up inquire catalog container structure MOVE CA-LIST-START-REF TO LIST-START-REF. Sample application 151 . Example 5-5 Create inquire catalog container *==========================================================* * Catalog inquire routine * * * *==========================================================* CATALOG-INQUIRE. MOVE CA-LAST-ITEM-REF TO LAST-ITEM-REF. * Set up inquire single container structure MOVE CA-ITEM-REF-REQ TO ITEM-REF-REQ. * Create container for inquire single EXEC CICS PUT CONTAINER(INQS) CHANNEL(CMN-CHANNEL) FROM(INQUIRE-SINGLE) FLENGTH(LENGTH OF INQUIRE-SINGLE) END-EXEC. Example 5-6 shows the paragraph our example uses to create the container for the inquire single request.

QUANTITY-REQ: The number of items to order. * Create container for place order EXEC CICS PUT CONTAINER(ORDR) CHANNEL(CMN-CHANNEL) FROM(ORDER-REQUEST) FLENGTH(LENGTH OF ORDER-REQUEST) END-EXEC. Move four fields from the COMMAREA to the ORDER-REQUEST structure that was created in copybook DFH0S02. The four parameters that our example uses for the order request container are: USERID: The name of person that places the order. MOVE CA-ITEM-REF-NUMBER TO ITEM-REF-NUMBER. ITEM-REF-NUMBER: The reference number of the catalog item. CHARGE -DEPT: Name or name of the department. EXIT. * Set up request and container name MOVE CA-USERID TO USERID.Example 5-7 shows the PLACE-ORDER paragraph that our example uses to create the container for the order request. MOVE CA-CHARGE-DEPT TO CHARGE-DEPT. Example 5-7 Create place order container *================================================================* * Place order routine * * * *================================================================* PLACE-ORDER. 152 CICS Transaction Server V3 R1 Channels and Containers Revealed . Example 5-8 shows how the example links to the catalog manager. Issue an EXEC CICS LINK command passing the channel that owns the following containers: request-type return-code-msg inquire-cat inquire-single order-item result The catalog manager DFH0XCMN creates the result container. MOVE CA-QUANTITY-REQ TO QUANTITY-REQ.

After that DFH0XSEP returns to DFH0XGUI using the updated COMMAREA.See Example 5-8 that shows the process of how you can link to the catalog manager module. Chapter 5. After return from catalog manager DFH0XCMN. EXEC CICS GET CONTAINER(RC-MSG) CHANNEL(CMN-CHANNEL) INTO(RETCODE-MSG) END-EXEC MOVE RC TO CA-RETURN-CODE. MOVE RESPONSE-MESSAGE TO CA-RESPONSE-MESSAGE. The data separation routine converts the COMMAREA structure to separate containers in order to link to the catalog manager. the logic in DFH0XSEP receives the information from the outbound containers to the COMMAREA. When the catalog manager returns. Sample application 153 . Example 5-8 Link to catalog manager module *==========================================================* * Link to the catalog manager * *==========================================================* EXEC CICS LINK PROGRAM(XCMNPROG) CHANNEL(CMN-CHANNEL) END-EXEC. perform an EXEC CICS GET CONTAINER command in order to get back the return code and response message to the COMMAREA.

Extending the catalog manager module This section describes the migration of the catalog manager module to the new function. The presentation logic DFH0XGUI uses the data separation module to convert its COMMAREA structure to the channel and container design that the catalog manager module DFH0XCMN accepts. DFH0XSEP expects the result of the relevant request in the result container. The next section describes the process used to migrate the catalog manager DFH0XCMN. evaluate the request ID in order to move the data fields of the result container to the corresponding structure in the COMMAREA. 154 CICS Transaction Server V3 R1 Channels and Containers Revealed . Example 5-9 Get container commands on return EVALUATE CA-REQUEST-ID WHEN '01INQC' EXEC CICS GET CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) INTO(CA-INQUIRE-REQUEST) END-EXEC WHEN '01INQS' EXEC CICS GET CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) INTO(CA-INQUIRE-SINGLE) END-EXEC WHEN '01ORDR' EXEC CICS GET CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) INTO(CA-ORDER-REQUEST) END-EXEC When the catalog manager DFH0XCMN returns.See Example 5-9. you have developed the data separation module that you use as a converter from COMMAREA to channels and container. So far. Example 5-9 shows the evaluation of the request ID and the corresponding EXEC CICS GET CONTAINER commands. Therefore.

using a COMMAREA. The catalog manager module calls the VSAM data handler DFH0XVDS using an EXEC CICS LINK command. The initial action is to perform a check against EIBCALEN. inquire single. The catalog manager module links to a VSAM data handler module DFH0XVDS in order to perform one of the three request types. or place order. Sample application 155 . because it is not possible to get any COMMAREA constraints with it in the future. MOVE EIBCALEN TO WS-CALEN. Example 5-10 shows the start of the mainline section within the original catalog manager module. Chapter 5. If the length of the COMMAREA is zero then you can set up a response message and issue an EXEC CICS ABEND. When it calls the VSAM data handler module DFH0XVDS.Consider the following. you have to migrate the catalog manager module. You must not migrate the VSAM data handler to the function. which are inquire catalog. it uses channels and containers and also the COMMAREA. migrate the catalog manager to run in dual mode. so that it is able to perform the following: When the data separation module DFH0XSEP or the Web client front end call the catalog manager. Use an EXEC CICS LINK passing a COMMAREA to call the VSAM data handler. before the discussion of the migration steps: The original catalog manager module takes the COMMAREA from the presentation logic DFH0XGUI. after you have completed the previously mentioned checks. it expects a channel. Therefore. Therefore. Example 5-10 Before migration: check for a valid COMMAREA *---------------------------------------------------------------* * Check commarea and obtain required details * *---------------------------------------------------------------* * If NO COMMAREA received issue an ABEND IF EIBCALEN IS EQUAL TO ZERO MOVE ' NO COMMAREA RECEIVED' TO EM-DETAIL PERFORM WRITE-ERROR-MESSAGE EXEC CICS ABEND ABCODE('EXCA') NODUMP END-EXEC END-IF * Initalize COMMAREA return code to zero MOVE '00' TO CA-RETURN-CODE.

calls the migrated version of the catalog manager. Our example specifies CA-REQUEST-ID on the INTO parameter. Therefore. rather than a COMMAREA. The name of the channel must be cmn-channel. See Example 5-11. Example 5-12 Get request ID EXEC CICS GET CONTAINER(REQ) CHANNEL(CMN-CHANNEL) INTO(CA-REQUEST-ID) END-EXEC 156 CICS Transaction Server V3 R1 Channels and Containers Revealed . A channel. you can issue an EXEC CICS GET CONTAINER(REQ) command to retrieve the required request ID. If there is no channel available. set up an error message and issue an EXEC CICS ABEND. which sets up the COMMAREA structure used to call the VSAM data handler later on.Replace the code that examines the COMMAREA. Use an EXEC CICS ASSIGN CHANNEL command in order to make sure that you received the expected channel. the first thing you must do is to check if you were passed a channel. Example 5-11 Assign channel command *---------------------------------------------------------------* * Check if we were passed a channel * * If NO channel available issue an ABEND * *---------------------------------------------------------------* EXEC CICS ASSIGN CHANNEL(CHN-NAME) END-EXEC IF CHN-NAME NOT = 'cmn-channel ' MOVE ' NO CHANNEL RECEIVED ' TO EM-DETAIL PERFORM WRITE-ERROR-MESSAGE EXEC CICS ABEND ABCODE('EXCH') NODUMP END-EXEC END-IF If you have received the expected channel available. See Example 5-12.

Sample application 157 . The inquire single request 01INQS uses paragraph CATALOG-INQUIRE-S. The place order request 01ORDR uses paragraph PLACE-ORDER. Example 5-13 shows how to evaluate the request ID in order to call the corresponding paragraph. arrange the three paragraphs that issue the EXEC CICS GET CONTAINER commands to retrieve the necessary data structures required to perform the corresponding functions: The inquire catalog request 01INQC uses paragraph CATALOG-INQUIRE. Example 5-13 Evaluate request ID *----------------------------------------------------------------* * Check which operation is being requested *----------------------------------------------------------------* * Uppercase the value passed in the Request Id field MOVE FUNCTION UPPER-CASE(CA-REQUEST-ID) TO CA-REQUEST-ID EVALUATE CA-REQUEST-ID WHEN '01INQC' Call routine to perform for inquire PERFORM CATALOG-INQUIRE WHEN '01INQS' Call routine to perform for inquire for single item PERFORM CATALOG-INQUIRE-S WHEN '01ORDR' Call routine to place order PERFORM PLACE-ORDER WHEN OTHER Request is not recognised or supported PERFORM REQUEST-NOT-RECOGNISED END-EVALUATE * * * * Chapter 5.In the next step of the catalog manager migration. perform an evaluation of the request ID. Each of the paragraphs issue the relevant EXEC CICS GET CONTAINER command and an EXEC CICS LINK to the VSAM data handler module passing a COMMAREA. In this example.

Then. After this. EXEC CICS LINK END-EXEC. See Example 5-14. INQUIRE-CAT is the structure defined in the DFH0S02 copybook to map the data fields of the INQC container. MOVE LAST-ITEM-REF TO CA-LAST-ITEM-REF. Example 5-15 shows an EXEC CICS GET CONTAINER(INQS) command that you can use to store the parameter in the INQUIRE. Specify INQUIRE-CAT on the into parameter. The inquire single request only takes one parameter. move ITEM-REF-REQ to relevant COMMAREA field CA-ITEM-REF-REQ. then use paragraph CATALOG-INQUIRE-SINGLE to get the inquire single parameter from the INQS container.SINGLE structure. EXEC CICS GET CONTAINER(INQC) CHANNEL(CMN-CHANNEL) INTO(INQUIRE-CAT) END-EXEC MOVE LIST-START-REF TO CA-LIST-START-REF.Example 5-14 shows the CATALOG-INQUIRE paragraph that our example uses to get the inquire catalog request parameter from the INQC container. Move the three parameters from the INQC input container structure to the corresponding fields in the COMMAREA. Example 5-14 Paragraph catalog-inquire *================================================================* * Procedure to link to Datastore program to inquire * * on the catalog data * *================================================================* CATALOG-INQUIRE. call the VSAM data handler using an EXEC CICS LINK command passing the COMMAREA. Therefore. MOVE ITEM-COUNT TO CA-ITEM-COUNT. If the request type is inquire single. set up the COMMAREA for the VSAM data handler. PROGRAM(WS-DATASTORE-PROG) COMMAREA(WS-CHN-DATA) 158 CICS Transaction Server V3 R1 Channels and Containers Revealed . MOVE 'EXCATMAN: CATALOG-INQUIRE' TO CA-RESPONSE-MESSAGE.

You can move them from the ORDER-REQUEST structure to the relevant fields in the COMMAREA. Our example uses four parameters for the place order request type. PROGRAM(WS-DATASTORE-PROG) COMMAREA(WS-CHN-DATA) Chapter 5. Example 5-16 shows the EXEC CICS GET CONTAINER(ORDR) command that maps the required input parameters to the ORDER-REQUEST structure. MOVE 'EXCATMAN: CATALOG-INQUIRE' TO CA-RESPONSE-MESSAGE EXEC CICS GET CONTAINER(INQS) CHANNEL(CMN-CHANNEL) INTO(INQUIRE-SINGLE) END-EXEC MOVE ITEM-REF-REQ TO CA-ITEM-REF-REQ. issue an EXEC CICS LINK with COMMAREA command to link to the VSAM data handler in order to perform the request. You can move the following parameters to the COMMAREA: USERID CHARGE-DEPT ITEM-REF QUANTITY-REF When the parameters are set. Example 5-15 Paragraph catalog-inquire-s *================================================================* * Procedure to link to Datastore program to inquire a single item* * on the catalog data * *================================================================* CATALOG-INQUIRE-S. EXEC CICS LINK END-EXEC Use the third paragraph for the place order request type. Sample application 159 . which is specified on the INTO parameter.See Example 5-15.

MOVE 'EXCATMAN: PLACE-ORDER' TO CA-RESPONSE-MESSAGE. CHARGE-DEPT TO CA-CHARGE-DEPT. move the return code and response message contents to the structure that maps the data fields of the RC-MSG container. Before you return to the caller of the catalog manager. 160 CICS Transaction Server V3 R1 Channels and Containers Revealed . create an output container for the result of the corresponding request. QUANTITY-REQ TO CA-QUANTITY-REQ. Example 5-16 Paragraph place-order *================================================================* * Procedure to link to Datastore program to place order. Evaluate the request ID again to set up the output container using the appropriate structure that contains the result for the particular request-ID. EXEC CICS GET CONTAINER(ORDR) CHANNEL(CMN-CHANNEL) INTO(ORDER-REQUEST) END-EXEC MOVE MOVE MOVE MOVE USERID TO CA-USERID. EXEC CICS LINK PROGRAM(WS-DATASTORE-PROG) COMMAREA(WS-CHN-DATA) END-EXEC. After that issue an EXEC CICS PUT CONTAINER(RC-MSG) command in order to provide the return and response messages to the caller of the catalog manager. ITEM-REF-NUMBER TO CA-ITEM-REF-NUMBER. * * send request to dispatcher and notify stock manager * * an order has been placed * *================================================================* PLACE-ORDER. When the VSAM data handler returns.See Example 5-16 that shows the paragraph place-order.

Example 5-17 Set up result output container MOVE CA-RETURN-CODE TO RC. MOVE CA-RESPONSE-MESSAGE TO RESPONSE-MESSAGE. EXEC CICS PUT CONTAINER(RC-MSG) CHANNEL(CMN-CHANNEL) FROM(RETCODE-MSG) FLENGTH(LENGTH OF RETCODE-MSG) END-EXEC. EVALUATE CA-REQUEST-ID WHEN '01INQC' EXEC CICS PUT CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) FROM(CA-INQUIRE-REQUEST) FLENGTH(LENGTH OF CA-INQUIRE-REQUEST) END-EXEC WHEN '01INQS' EXEC CICS PUT CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) FROM(CA-INQUIRE-SINGLE) FLENGTH(LENGTH OF CA-INQUIRE-SINGLE) END-EXEC WHEN '01ORDR' EXEC CICS PUT CONTAINER(RESULT) CHANNEL(CMN-CHANNEL) FROM(CA-ORDER-REQUEST) FLENGTH(LENGTH OF CA-ORDER-REQUEST) END-EXEC WHEN OTHER Request is not recognized or supported PERFORM REQUEST-NOT-RECOGNISED * END-EVALUATE. which returns to the caller of the catalog manager. * Return to caller Chapter 5. Sample application 161 .See Example 5-17 where our example issues the relevant EXEC CICS PUT CONTAINER(RESULT) command.

CLASS=A.MSGCLASS=T. The other contains the sales catalog.EXMPLAPP.EXMPLAPP.5 Installing and setting up the base application Before you can run the migrated version of the catalog manager application. Our example describes the installation steps for the following application scenarios: The original base application. The first approach to migrate to the new function using a single container to replace the COMMAREA. to create the VSAM KSDS data sets. See Example 5-18. In our example. Use the job control language (JCL) Example 5-18 shows.EXMPCAT) - 162 CICS Transaction Server V3 R1 Channels and Containers Revealed . // NOTIFY=&SYSUID.POK).REGION=0M /*JOBPARM L=999.5. One data set contains configuration information for the application. Define the VSAM KSDS data sets that the catalog manager example uses.PAA1.EXMPCAT SET MAXCC=0 /* //DEFINE EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * /* */ /* DEFINE A CICS GLOBAL CATALOG */ /* */ DEFINE CLUSTER(NAME(CICSDSW.'CICS ZS'.PAA1. After this. Example 5-18 JCL to create the VSAM KSDS data sets //CICSPAZS JOB (999. we specify the data set name on the DSNAME option and use the default values for all other attributes. copy the file resource definitions from CICS supplied group DFH$EXBS.PAA1. The migrated application at the stage 1 and stage 2 level. You can use the data sets for all application migration scenarios. you must define two VSAM data sets.TIME=NOLIMIT.EXMPCONF DELETE CICSDSW. and install the relevant resource definitions for the different migration stages.1.EXMPLAPP.SYSAFF=SC04 //DELETE EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DELETE CICSDSW.

Define the two VSAM data sets that Example 5-18 on page 162 shows.EXMPLAPP. The transaction runs program EFH1XGUI. Chapter 5.1.DATA)) INDEX(NAME(CICSDSW.PAA1. XGUI The XGUI transaction runs program EFH2XGUI.PAA1.EXMPLAPP. Sample application 163 .EXMPLAPP.EXMPCONF.EXMPCONF) INDEXED CYL(1 1)KEYS(9 0) RECORDSIZE(350. which is the migrated application at the stage 1 and stage 2 level.PAA1.EXMPLAPP.PAA1. SGUI The SGUI transaction runs the application that uses a single container to replace the COMMAREA.350) SHR(2 3)VOLUME(TOTCIH) REUSE)) DATA(NAME(CICSDSW. In order to install the original and migrated applications. b. Copy the file definitions from DFH$EXBS and alter the DSNAME option.EXMPCAT.DATA)) INDEX(NAME(CICSDSW. You can also use the following definitions: EGUI The EGUI transaction is part of the original catalog manager application.EXMPLAPP. The original base application: a.EXMPCAT.6 Defining the 3270 interface Our example uses the following transaction definitions to run the different migration scenarios.EXMPCONF. perform the following steps: 1. which replaces DFH0XGUI.INDEX)) DEFINE CLUSTER(NAME(CICSDSW.80) SHR(2 3)VOLUME(TOTCIH) REUSE)) DATA(NAME(CICSDSW.INDEXED CYL(1 1)KEYS(4 0) RECORDSIZE(80.INDEX)) 5.PAA1. It runs program DFH0XGUI.

Issue a CEDA DEFINE TRANSACTION(SGUI) PROG(EFH1XGUI) G(EXAMPLE) command to define the transaction.c. a. Issue a CEDA I G(EXAMPLE) command. b. Define the two VSAM data sets that Example 5-18 on page 162 shows. if you have not defined them already. EFH2XSEP. Copy the file definitions from DFH$EXBS and alter the DSNAME option. check the flow of the programs. if you have not defined them already. The migrated application at the stage 1 and stage 2 level. Issue a CEDA I G(EXAMPLE) command. d. this section shows you the sequence of the 3270 maps and the operator input that you have to simulate later on. EFH1XSEP. Issue a CEDA DEFINE TRANSACTION(EGUI) PROG(DFH0XGUI) G(EXAMPLE) command to define the transaction. The name of the topic is Installing and setting up the base application. c. d. The first approach application using a single container to replace the COMMAREA: a. 5. b. e. Define the two VSAM data sets that Example 5-18 on page 162 shows. Before you use the Workload Simulator for a regression test. and EFH2XCMN d. 164 CICS Transaction Server V3 R1 Channels and Containers Revealed . Issue a CEDA I G(EXAMPLE) command. Issue a CEDA DEFINE TRANSACTION(XGUI) PROG(EFH2XGUI) G(EXAMPLE) command to define the transaction. You can also use the CICS information center to get a detailed installation description for the CICS catalog manager example application. c. Compile and link programs EFH2XGUI. The applications are now ready to use. 2. e.1. 3. and EFH1XCMN.7 Running the application To make sure that the migrated version of the application works as expected. use the Workload Simulator to determine the performance of the migrated catalog manager application. Copy the file definitions from DFH$EXBS and alter the DSNAME option. After ensuring the basic function of the migrated application. Compile and link programs EFH1XGUI.

The inquire catalog function provides the list. then press ENTER Action . 1 1. it calls the inquire single function. Figure 5-7 shows you the main menu panel. Sample application 165 . The remaining catalog items are provided if you scroll forward using the F8 key. Order Item Number 3. Order item number This function allows you to order an item directly from the main menu screen.Main Menu Figure 5-7 Main menu panel There are three options available: List items This function provides a list of the available catalog items. It provides a list of the first 15 catalog items. . Option number 2 calls the inquire single function first. List Items 2. The transaction starts program DFH0XGUI which sends the map. CICS EXAMPLE CATALOG APPLICATION Select an action. Exit . You can order an item from the inquire catalog panel from the main menu. . If you type a slash next to the catalog item cost column. Chapter 5. Exit This terminates the catalog manager example application. Figure 5-8 shows the result of the inquire catalog function. .Figure 5-10 shows the first screen that opens when you enter the transaction EGUI.

The inquire single function displays additional information about the item and allows to place the order for the item.44 0080 Laser Paper 28-lb 108 Bright 2500/case 33.99 0130 Wall Planner: Eraseable 36x24 18. CICS EXAMPLE CATALOG APPLICATION .90 0020 Ball Pens Blue 24pk 2.54 0090 Blue Laser Paper 20lb 500/ream 5.78 0060 Highlighters Assorted 5pk 3. When you press enter. then press ENTER Item Description Cost Order ----------------------------------------------------------------0010 Ball Pens Black 24pk 2.89 0150 Sticky Notes 3x3 Assorted Colors 5pk 5.Figure 5-8 shows how our example selects the ball pen green 24 pk item.Inquire Catalog Select a single item to order with /.35 0100 Green Laser Paper 20lb 500/ream 5. See Figure 5-8.35 F3=EXIT F7=BACK F8=FORWARD F12=CANCEL Figure 5-8 Inquire catalog map 166 CICS Transaction Server V3 R1 Channels and Containers Revealed .90 0040 Ball Pens Green 24pk 2.Toner cart 169.90 / 0050 Pencil with eraser 12pk 1.85 0140 70 Sheet Hard Back wire bound notepad 5.90 0030 Ball Pens Red 24pk 2.89 0070 Laser Paper 28-lb 108 Bright 500/ream 7.35 0110 IBM Network Printer 24 . it calls the inquire single function for item 0040.56 0120 Standard Diary: Week to view 8 1/4x5 3/4 25.

then press ENTER Item Description Cost Stock On Order -----------------------------------------------------------------0040 Ball Pens Green 24pk 2.90 0063 000 Order Quantity: 001 User Name: CICSUSER Charge Dept: ITSO F3=EXIT F12=CANCEL Figure 5-9 Order map Chapter 5. It shows the number in stock and the number of items that are currently on order. See Figure 5-9. Sample application 167 .Details of your order Enter order details. The details of your order screen shows additional information of the item. CICS EXAMPLE CATALOG APPLICATION .Figure 5-9 shows the screen that opens when you select option 2 from the main menu or when you type a slash next to an item in the list of the catalog items.

168 CICS Transaction Server V3 R1 Channels and Containers Revealed . Create a CICS Java (JCICS) program that reads the image file from the HFS directory and puts its contents to an output binary container. . CICS EXAMPLE CATALOG APPLICATION Select an action. The catalog manager issues an EXEC CICS LINK command to call the JCICS program. On return from the JCICS program the item image is provided in the output container. you provide the corresponding catalog item image. When the order is successful. Exit .8 Stage2: catalog item images support This section describes how to extend the catalog manager to allow for catalog item image support. . The name of the relevant image files correspond to the item reference number.Specify the order details and press enter. Our example stores the item image files to an HFS directory. When the Web client front end calls the catalog manager. which the inquire single function of the catalog manager module uses. See Figure 5-10. the main menu returns. List Items 2. 1. Extend the inquire single function of the catalog manager to provide the relevant images. then press ENTER Action . Order Item Number 3. .1. Message ORDER SUCCESSFULLY PLACED indicates that you have placed the order.Main Menu ORDER SUCESSFULLY PLACED F3=EXIT F12=CANCEL Figure 5-10 Main menu map 5.

ear WebSphere Application Server HFS Figure 5-11 Application migration environment at the stage 2 level Additional containers Similar to our example. you can use four additional containers for the catalog item image support. Chapter 5. Stage 2: Working with larger data Java SOAP Application SOAP CICS1 BMS presentation manager (DFHOXGUI) COMMAREA 3270 emulation Pipeline Data separator Channel Wrappers Extend catalog manager Catalog manager (DFHOXCMN) Datastore Type = VSAM Outbound WebService = YES VSAM data handler (DFHOXVDS) Dispatch manager (DFHOXWOD) Pipeline (EXPIPE02) Image Handler (JCICS) VSAM Catalog data (EXMPCAT) Order dispatch end point (DFHOXODE) CICS2 Order dispatch end point ExampleApp DispatchOrder. Sample application 169 . which are as follows: Container ref-no The catalog manager creates it within the inquire single paragraph. Put the item reference number into the container and pass the channel to the JCICS program.See Figure 5-11 that illustrates the application migration environment at the stage 2 level.

If there is no channel available. Container error-msg The JCICS program creates this container if there is a problem to read the image file from the HFS directory. Container gif-data The JCICS program creates this channel. After that. However. 170 CICS Transaction Server V3 R1 Channels and Containers Revealed . Do not change the original part of the code that reads the configuration file. if the read fails. 2. issue an EXEC CICS READ against the configuration file of the catalog manager example application. issue an EXEC LINK PROGRAM in order to call the VSAM data handler 5. After that. Extension to the catalog manager Figure 5-12 on page 171 illustrates the new structure of the catalog manager module. 3.Container image-dir The catalog manager creates it within the inquire single paragraph. If the channel is available. issue a EXEC CICS ABEND. issue an EXEC CICS GET CONTAINER to figure out which request you are going to perform. The following steps discuss the process: 1. you additionally call the JCICS catalog server program to get the catalog item image from the HFS directory. In the next step. It is the binary output channel that contains the image file. 4. put the return code and error messages into the RC-MSG container rather than using the COMMAREA to store the error information. If the inquire single request ID executes. or from the Web client front end using an EXEC CICS LINK command passing a channel. On module entry. check if there is a channel available. evaluate the request ID that you got from the request container earlier on. Execute the EXEC CICS GET CONTAINER command that corresponds to the request ID. You can call the module from either the data separation module. Put the name of the HFS directory into the container and pass the channel to the JCICS program.

evaluate the request ID and place the result to the output container that corresponds to the request ID. Link to Image server get ORDER container E. You do not have to take care of the item image within the catalog manager. You still have the catalog item image in the gif-data output container available. 3.. After that.C. update the RC-MSG container with return code and error message information that might have occurred.C. Chapter 5. DFH0XCMN structure 1 of 2 DFH0XSEP channel available? Y get REQ container Read configuration file Y INQC ? N Y INQS ? get INQC container get INQS container E.C.C. Before you can return to the caller of the catalog manger. The steps are as follows: 1. Link to DFH0XVDS N abend EXEC CICS LINK PROGRAM(DFH0XCMN) CHANNEL . The caller of the catalog manager module manages the container and passes the image to the Web client front end.. Link to DFH0XVDS E.See Figure 5-12. E. Link to DFH0XVDS N inv-request ORDER? Y 2 of 2 Figure 5-12 DFH0XCMN structure Figure 5-13 on page 172 illustrates the structure of the catalog manager module before it returns to the caller. 2. Sample application 171 .

Issue an EXEC CICS LINK command passing the current channel.C. 3. the catalog server JCICS program places the image in the output gif-data container. 2. 172 CICS Transaction Server V3 R1 Channels and Containers Revealed . Place the name of the HFS directory to the image-dir container. RETURN put RESULT container E. to call the catalog server JCICS program. Therefore.C. In order to check that there are no error messages available in the error-msg container. It illustrates the following steps: 1. DFH0XCMN structure 2 of 2 From 1 0f 2 put RC-MSG container Y INQC ? N Y INQS ? N inv-request ORDER? Y put RESULT container E. You get a CONTAINERERROR condition if there are no error messages available.C. perform an EXEC CICS GET CONTAINER(GET-IMG-ERROR). Specify the IMG-DIR-CONTENTS data field on the INTO option of the put container command.See Figure 5-13. Place the image reference of the item that you want to get from the HFS directory to the ref-no container. RETURN Figure 5-13 DFH0XCMN structure Example 5-19 shows how our example updates the catalog inquire single paragraph of the catalog manager program. use the RESP option to check if the response is normal. On return. RETURN put RESULT container E. 4. Use the ITEM-REF-REQ data field of the inquire single structure to identify the item. Data field IMG-DIR-CONTENTS contains HFS directory /u/cicsrs9/images/.

MOVE 'EXCATMAN: CATALOG-INQUIRE' TO CA-RESPONSE-MESSAGE EXEC CICS GET CONTAINER(INQS) CHANNEL(CMN-CHANNEL) INTO(INQUIRE-SINGLE) END-EXEC MOVE ITEM-REF-REQ TO CA-ITEM-REF-REQ.A response of DFHRESP(NORMAL) means that the container has been created and contains an error message. Example 5-19 Extended catalog-inquire-s paragraph CATALOG-INQUIRE-S. EXEC CICS LINK PROGRAM(WS-DATASTORE-PROG) COMMAREA(WS-CHN-DATA) END-EXEC *----------------------------------------------------------------* * before we return to the data separation routine we have to * * retrieve the corresponding image using the catalog server *----------------------------------------------------------------* EXEC CICS PUT CONTAINER(IMAGE-REF) CHANNEL(CMN-CHANNEL) FROM(ITEM-REF-REQ) END-EXEC * PUT CONTAINER command to pass the HFS directory name EXEC CICS PUT CONTAINER(IMG-DIR) CHANNEL(CMN-CHANNEL) FROM(IMG-DIR-CONTENTS) END-EXEC EXEC CICS LINK PROGRAM(CATALOG-SERVER) CHANNEL(CMN-CHANNEL) END-EXEC EXEC CICS GET CONTAINER(GET-IMG-ERROR) CHANNEL(CMN-CHANNEL) INTO(RESPONSE-MESSAGE) RESP(RESPONSE) END-EXEC IF RESPONSE = DFHRESP(NORMAL) MOVE '54' TO RC END-IF EXIT. Chapter 5. Sample application 173 . See Example 5-19.

Image handler program The image handler program is written in Java and uses the JCICS class library.itso.catalog. This is used to find the corresponding gif file for the item.jar to the Java class path in your CICS JVM™ Profile. 5.gif. for example. These are 0010. It requires to be linked to with a channel holding the following containers: ref-no The reference number of the item. You can find all Java source code and compiled classes in the X saz099. and a Java SOAP application. The value for this is configured in the COBOL copy book DFH0XS02.server. You require to configure both these applications before executing the scenario. You must place these in a directory on Unix system services. you require to perform the steps that the following sections discuss.gif.catalog. Add saz099.catalog.ImageRetriever) The supply in the additional materials holds two images for use with the scenario. 2. Here are the required steps for setting up this program: 1. This value is picked up when the catalog manager program EFH2XCMN is linked and compiled. img-dir The HFS directory where item images are stored. You must insert the explicit path of this directory into the IMG-DIR-CONTENTS field in the COBOL copy book DFH0XS02.ibm.jar file. Define and install the following CICS resource: PROGRAM(CTLGSERV) GROUP(CATALOG) JVM(Yes) JVMClass(com.2 Running the stage 2 code Before running the Java SOAP client in the stage 2 environment.5. the scenario now includes an image handler program.gif and NoImage.saz099.2. and the directory must have appropriate permissions to allow CICS to access them. 0010.1 Installing and setting up the stage 2 application As Figure 5-11 on page 169 shows. 174 CICS Transaction Server V3 R1 Channels and Containers Revealed .

visit the Web at: http://publib.cics. and corresponding WSbind files are supplied in the additional materials download. However.jsp?topic =/com. Sample application 175 . Here are the names of the Web services programs and the generated language structures they use: CATINQ: inquire request Web service program CATINP01: inquire request generated response structure CATINQ01: inquire request generated request structure CATLIST: list request Web service program CATLSP01: list request generated response structure CATLSQ01: list request generated request structure CATORDER: order request Web service program CATORP01: order request generated response structure CATORQ01: order request generated request structure The generated language structures. three small Web service programs perform the conversions from SOAP message to channel. which are used in the channel interface to the catalog manager.html To install Web services. then sample JCL has been supplied to show the parameters that the CICS Web services assistant requires with the previously mentioned WSDL.doc/prod/home. The WSDL files are: catInquire.wsdl: for INQUIRE requests catList.com/infocenter/cicsts/v3r1/index. Three Web Services Description Language (WSDL) files are supplied with CICS for you to use with the CICS Web services assistant to generate appropriate request and response language structures for use in the Web service programs.ibm.The Web service interface to catalog manager To provide the Web service front end to the new channels and containers interface of the catalog manager. Note: For more information about CICS Web services. Ensure it’s Wsdir value points in comparison to a directory containing the WSbind files that Chapter 5. You can use these to set up the Web services that the scenario uses.boulder. and vice-versa. Three COBOL Web services programs perform this mapping.wsdl: for LIST requests catOrder. you require to configure a pipeline resource.ts. Web service programs.ibm.wsdl: for ORDER requests The language structures that are generated from the WSDL files provide fields that have a direct mapping to the field structures. if you require to regenerate the WSbind files that the scenario uses.

jar is available on your pc: java -cp c:\saz099. 176 CICS Transaction Server V3 R1 Channels and Containers Revealed . you are now ready to test the extensions to the catalog manager application.ibm. This is where you insert the TCP/IP address and the port of your Web service enabled CICS region. you see three new Web service programs in CICS titled catInquire.catalog.2. It has been developed and tested using Java 1. To run the client. and catOrder. Having set up the image handler program and the Web service programs. catList.the scenario uses.4.2. the Server Address field is at the bottom.catalog.client.itso.CatalogApplication Figure 5-14 shows what the application looks like when it is executed. 1.saz099.2 Running the Java SOAP client The Java SOAP client is run from a Java enabled personal computer.catalog.jar com. 5. Figure 5-14 The default screen of the Java SOAP application Note: In Figure 5-14. perform the following command ensuring the file saz099. When the pipeline installs the Web services.

or if the Web service is unavailable. If everything has worked successfully. Chapter 5. If the Server Address field has not been set correctly. then a message is put to stdout. then a list request SOAP message is sent into CICS. Ensure that the Server Address field is set correctly and press the SUBMIT button. Sample application 177 . Press the LIST ITEMS button to enter the screen that Figure 5-15 shows.2. Figure 5-15 The list items screen The starting item number defaults to 0010.

the screen shown in Figure 5-16 opens. Figure 5-16 The list of items retrieved from the Web service call into CICS The next step enables us to see the results of the extension to the catalog manager. When the message returns. At this point. Select the first item in the list and press SUBMIT. an inquire item SOAP message is sent into CICS.3. 178 CICS Transaction Server V3 R1 Channels and Containers Revealed .

4. The response message gives you what Figure 5-17 shows.

Figure 5-17 A successful retrieval of the product image

5. Click on the image for larger view box to get a larger version of the image as Figure 5-18 shows.

Figure 5-18 A larger version of the retrieved image

Chapter 5. Sample application

179

You have now received an image from CICS which is greater than 32 KB using channels and container. For completeness, follow the path of the application through to purchasing a product. Click the X on the right upper corner of the window containing the larger image to close it. 6. The screen that Figure 5-17 on page 179 shows, opens again. Enter information regarding the user name and the department name fields, and click the SUBMIT button. 7. This sends an order request SOAP message into CICS. When the message returns you can see the screen that Figure 5-19 shows.

Figure 5-19 The successful purchase of an item

180

CICS Transaction Server V3 R1 Channels and Containers Revealed

8. To verify that the item was actually purchased, click the list items button, and press the submit button to retrieve an updated list. You are presented with something similar to that shown in Figure 5-20. Observe that the in stock field value has gone down by the value of one.

Figure 5-20 The updated item list

9. If the image retriever program cannot find an image corresponding to an item, then the image returned is shown in Figure 5-21.

Figure 5-21 The default image if a specific product image does not exist

Chapter 5. Sample application

181

5.3 Catalog manager application: performance
This section compares the performance of the original catalog manager application with the migrated application at the stage 1 level. Stage 1 of the migration does not include the item image support. The migrated catalog manager application at the stage 2 level is not comparable to the original application because of its additional function. The migrated version of the catalog manager application uses an additional module DFH0XSEP. Therefore, expect the processor consumption for the migrated version to be slightly higher. Arrange a small Workload Simulator script that allows to simulate the operator input to run the catalog manager example application. Example 5-20 shows the script our example uses to run a regression test on the catalog manager application. The following steps describe the process: 1. The variable TIMESTORUNXACTION is set to 100, therefore, the script runs the transaction of the catalog application 100 times. 2. After this, start the transaction ID. 3. Wait for input, which is the main menu. On the main menu, type 1. 4. Simulate the action of pressing the enter key and wait for the next input, which is the list of catalog items. 5. Then, evaluate a random number in the script between 1 and 15 in order to select an item from the list of 15 items. Tab to the relevant item and type a slash next to the item in the list. Simulate the enter key and wait for the order details screen. 6. Type the order details. We simulate the enter key to place the order. 7. Simulate the PF03 key to terminate the transaction. Our example omitted the simulation of the enter key after typing the order details in order to test the inquire single function only. If the comment is removed, then the place order function is also tested. This example executes the following steps for both the original application and the migrated application: 1. It issues a CEMT INQ MON to make sure that CICS monitoring is active and to collect performance records. After that it switches the SMF data set using a /I SMF command. 2. It starts the Workload Simulator network. At first it uses a network deck that simulates just two terminals to run the script.

182

CICS Transaction Server V3 R1 Channels and Containers Revealed

5. 6. and file control requests of both applications. Use the CICS Performance Analyzer to compare the performance of both versions of the catalog manager application. When the regression test completes.15) DO I=1 TO ITEM TAB END TYPE '/' TRANSMIT USING ENTER AND WAIT UNTIL ONIN TYPE '001' TYPE 'CICSUSER' TYPE 'ITSO' ************TRANSMIT USING ENTER AND WAIT UNTIL ONIN TRANSMIT USING PF03 AND WAIT UNTIL ONIN TRANSMIT USING CLEAR AND WAIT UNTIL ONIN END ENDTXT @ENDPROGRAM Figure 5-22 shows the user processor time. Analyze the smf records of 100 XGUI transactions and 100 EGUI transactions. Our example uses transaction ID XGUI for the migrated version of the application. stop the network. Chapter 5. Sample application 183 . Example 5-20 WSIM script @PROGRAM INTEGER ITEM /***************************************************************/ @INCLUDE TESTPARM CAT01: MSGTXT DO J = 1 TO TIMESTORUNXACTION TYPE 'XGUI' TRANSMIT USING ENTER AND WAIT UNTIL ONIN TYPE '1' TRANSMIT USING ENTER AND WAIT UNTIL ONIN ITEM = RANDOM(1. See Example 5-20. the processor time of the migrated catalog application is slightly higher than the processor time of the base application. As Figure 5-22 shows. response time. 4. Check the CICS job logs to find any possible problems. Issue a /I SMF to switch the SMF data set again. Transaction ID EGUI is the original ID of the base application.3.

Our example eliminates the COMMAREA constraint in the catalog manager module. The processor time is pulsing due to the behavior of the different functions.0000 original catalog application Figure 5-22 First results of resolution test The chart shown in Figure 5-23 shows the processor consumption of the base catalog application. For example: The inquire single function has less file control requests than the inquire catalog function.0003 0. because you can now access the catalog manager from the existing 3270 presentation logic DFH0XGUI and also from the Web front end client using channel and containers. XGUI Count of Tran Average of User CPU Time Max of User CPU Time Min of User CPU Time Average of Response Sum of FC Total 100.0016 seconds.0009 0. 184 CICS Transaction Server V3 R1 Channels and Containers Revealed . The overhead in the migrated catalog manager program DFH0XCMN is rather small. See Figure 5-22. The graphic shows a run of 100 transactions.0016 0.0000 0. The overhead for an application is acceptable.0000 migrated catalog application stage 1 EGUI Count of Tran Average of User CPU Time Max of User CPU Time Min of User CPU Time Average of Response Sum of FC Total 100.0000 0.The additional cost for the logic in DFH0XSEP and for the migration is about 10% in our example. Therefore.0059 592. the VSAM data handler module performs only a single read. but it retains the programs that are still using the COMMAREAs.0017 0.0008 0. The peak processor time is about 0.0004 0.0020 592.

This is when processor time drops below 0.7 03 6:4 75 :1 7.0020 0.9 03 6:3 64 :1 8. Sample application 185 .0010 0. User CPU Time Base Application 0. 03 6:4 983 :1 3.0000 User CPU Time Figure 5-23 Processor time base application 40 . See Figure 5-23. 03 6:4 78 :1 0.5 03 6:2 156 :1 3.The presentation logic DFH0XGUI sends only a map and issues an EXEC CICS RETURN TRANID command.0005 0. but the path is longer than the inquire single function.7 03 6:5 90 :1 9.5 03 6:3 172 :1 5. 03 6:3 68 :1 1. 03 6:5 94 :1 2. 03 6:5 019 :1 6.8 03 7:0 26 :1 1.0015 0.0005 seconds The place order function also has less file control requests than the inquire catalog function.5 03 6:4 186 :1 7.6 03 7:0 223 :1 9.7 03 6:2 60 :1 5.2 11 6 7: 3 :1 8.0 03 7:0 31 :1 4. 03 6:2 :1 03 Chapter 5.

9 12 13 03: :41.The chart in Figure 5-24 shows the processor consumption of the catalog manager application at the stage1 migration level. and the caller of the current program. 12 554 03: :51. 186 CICS Transaction Server V3 R1 Channels and Containers Revealed . 12 747 03: :46.0 000 1 . U C UT eS 1 ser P im tage U C UT e ser P im 0. 5 :12 75 03 :54. 6 1 82 03: :48. 9 12 35 03: :56. we wrote a user exit that gets control at the XEIIN and XEIOUT global user exit points. 12 536 03: :39. 1 1 12 03: :29.0 015 0. then the processor time was lower that 16 micro seconds. the current program. 1 1 56 03: :59. The peak processor time is at about 0. the eip function code. As mentioned previously. 0 1 73 03: :34. 3 12 34 03: :44. the overhead is most likely due to the additional logic in the data separation module. You can determine the processor consumption for a single CICS command. Figure 5-25 shows a fragment of the output available now.17 :09 13 771 03: 3:06.0 020 0. The processor time gets accumulated for each task number and the exit allows to determine the processor time for the sub routines.0017 seconds. 5 :12 31 03 2:24. 0 12 15 03: :49. 2 :13 16 03 3:01. the graphic shows 100 Transactions of the migrated catalog manager application. 8 12 71 03: :26.0 005 0. Within the exit record the user processor time. Similar to the previous run. If the processor time does not increase from one command to another. 5 1 36 03: :04.0 010 0. 09 03: Figure 5-24 Processor time at stage 1 level In order to determine the actual processor consumption of the data separation module. 4 12 33 03: 2:36. 12 527 03: 2:31.

000992 0.000352 0.000416 0. Then.000784 0.000656 0.000704 0.00032 0.00048 0.000656 0.000704 0.See Figure 5-25.00112 Exit XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT XEIIN XEIOUT Tx XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI XGUI Caller CICS CICS CICS CICS CICS CICS CICS CICS CICS CICS CICS CICS EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN Current EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XGUI EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XSEP EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN EFH2XCMN DFH0XVDS DFH0XVDS DFH0XVDS DFH0XVDS DFH0XVDS DFH0XVDS DFH0XVDS DFH0XVDS Figure 5-25 Fragment of the output You can start the transaction of the migrated application again and enable the user exits.000432 0.00032 0.000784 0.000656 0.000704 0.000784 0. place the same order again using the base application. Task 65931 65931 65931 65931 65931 65931 65931 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 65932 Command READ READ IGNORE CONDITION IGNORE CONDITION SEND MAP SEND MAP RETURN IGNORE CONDITION IGNORE CONDITION RECEIVE MAP RECEIVE MAP LINK PUT CONTAINER PUT CONTAINER PUT CONTAINER PUT CONTAINER PUT CONTAINER PUT CONTAINER LINK ASSIGN ASSIGN GET CONTAINER GET CONTAINER READ READ GET CONTAINER GET CONTAINER LINK READ READ STARTBR STARTBR READNEXT READNEXT READNEXT READNEXT UserCPUT 0.000416 0.000624 0.000784 0.000384 0.000944 0.000656 0.000656 0.000704 0. Sample application 187 .000704 0. Chapter 5.000992 0.001088 0.001104 0. Place an order and collect the data.00048 0.00112 0.000384 0.00112 0.000432 0.000352 0.000656 0.

For example. The catalog manager application starts five transactions to place the order.The following result is displayed. It used 0. a high level of tracing is active. 188 CICS Transaction Server V3 R1 Channels and Containers Revealed . this chapter uses the results of the catalog application performance behavior to demonstrate a comparison of the applications on our CICS system. Therefore.005504 seconds EGUI 0. 5. Table 5-1 shows the processor consumption of the entire application.4 Conclusion This chapter uses the migration scenario of the catalog manager application to demonstrate the use of best practices to exploit channel and containers.000576 processor seconds. Table 5-1 Processor consumption of entire application XGUI 0.004288 seconds The data separation module is called six times. The CICS regions that this chapter uses are not tuned to peak performance.

You can use this chapter to navigate through this channels and containers book and start your investigation regarding this topic. This chapter contains the following: Administration FAQs Application programming FAQs Performance FAQs Functions not yet supporting channels and containers Online information about channels and containers © Copyright IBM Corp. where you can access more detailed information. All rights reserved. 2006.6 Chapter 6. 189 . It provides a short answer for each one of these questions and a possible reference to certain chapters or sections inside this book. Frequently asked questions This chapter provides a list of the most frequently asked questions (FAQs).

“Introduction to channels and containers” on page 1. On the highest logical level return in the transaction flow (return to CICS).1 Administration questions Table 6-1 contains frequently asked questions dealing with the administration of channels and containers. See Chapter 3. CICS manages the container storage. See Chapter 1. be used in a pseudo-conversational mode? 3 4 Is it possible to inquire against containers in a channel? 5 Does the program free the storage areas that EXEC CICS GET CONTAINER acquires? 190 CICS Transaction Server V3 R1 Channels and Containers Revealed . Table 6-1 Administration FAQs No. and can be thought of as a parameter list. use the command format EXEC CICS RETURN TRANSID CHANNEL. “Application design and implementation” on page 23. A channel is a set of containers that you can pass to another program or transaction. EXEC CICS START. You can also think of it as a named COMMAREA.6. Channels and COMMAREA are mutually exclusive mechanisms for transferring data on EXEC CICS LINK. Otherwise. 2 Can a CICS program continue to use communication area (COMMAREA) to pass data while implementing the channel and container constructs into its design? Can a CICS transaction. This means that it is not possible to know the number of containers on a channel using EXEC CICS INQ CHANNEL(xxxxxxxx) CONTAINER COUNT. but not both at the same time.1. A container is a named block of data that you can transfer to another program or transaction. the program reclaims the container storage when you terminate the task. If necessary. Meaning. you may use one technique or the other during each operation. 1 Question How does Customer Information Control System (CICS) Transaction Server Version 3 resolve the restriction of a 32 KB? Answer CICS Transaction Server 3. No. See Chapter 2. you can use pseudo-conversational mode to preserve the container data between transactions. To retrieve data passed to your program. If you require to preserve some or all of the data. Yes. “Programming” on page 59. “EXEC CICS application programming interface” on page 60. It is not possible to inquire using SPI. you may copy it into your own application storage. you can use EXEC CICS DELETE CONTAINER to delete the container and free the storage. use the command format EXEC CICS GET CONTAINER CHANNEL. EXEC CICS XCTL. Do not issue a FREEMAIN against the storage area. and EXEC CICS RETURN commands. using channels to transfer data.1 introduces Enhanced Inter-program data Transfer using the new constructs of channels and containers. See 3.

1 to a CICS non-Transaction Server 3. “Best practices” on page 52. See 4. “Configuration” on page 93. Table 6-2 Application programming FAQs No. channels and containers are only supported at CICS Transaction Server 3. 7 Can you access channels and containers via task-related user exit (TRUE) or global user exit (GLUE)? Are channels and containers suitable for dynamic transaction routing in CICSPlex System Manager environment? Is it possible to pass a channel from a CICS Transaction Server 3. See 2. “STARTBROWSE application programming interface” on page 36. you have to use business transaction services (BTS). See 4.6. See Chapter 3.1 level? 8 Yes. If you require recoverability for the container’s content. “Migration planning” on page 102. 6 Question Are the containers recoverable? Answer No they are not.9. but you must use a special container if you require to access the data. No. but TRUE and GLUE can create their own channels. Frequently asked questions 191 . 2 Calling programs cannot pass channels and containers in the call.1. “Migration planning” on page 102.No.4. New abend codes have been introduced to manage such condition.2 Application programming questions Table 6-2 contains frequently asked questions regarding the application programming using channels and containers. if any. 9 No. See 2.6.1 level. 1 Question How can you know if a subroutine is invoked by programs using COMMAREA or channel if both the methods are in use? Can you use channels and containers in Common Business Oriented Language (COBOL) dynamic calls? While migrating existing COMMAREAs is it better to use channels with single or multiple containers? Answer The EXEC CICS ASSIGN CHANNEL is provided for this scope. See 4. Chapter 6. “Programming” on page 59. 3 It is suggested the usage of multiple containers.4. The called program can access the current channel. 6. An abnormal end occurs in both the sending and receiving region.

Use dedicated containers for error information. EXEC CICS START. “EXEC CICS application programming interface” on page 60. make it a separate container.1. See 2. Yes they are.1. The server program. and EXEC CICS RETURN are the commands that you can use to pass channels between programs. 4 Question How can a program know what are the containers associated to the current channel? Why you must use data conversion in channel API instead of the CICS provided one? What are the factors that you must consider when designing a channel? Answer Browse application programming interface (API) are provided for this scope. See 3. The data conversion model offered by channel API is simpler to manage compared to the CICS one. Consider the following factors while designing a channel: Use separate containers for input and output data. not the client.1. 5 6 7 Is it there any type of API used to create a channel? There is no explicit API to create a channel. See 3. “Passing a channel to another program or task” on page 62. For more considerations on the matter.6. More on this in 3. Use separate containers for read-only and read-write data. More on this in 2. but it is created when performing certain commands. “Data conversion with channels” on page 39.1. “Browsing the current channel” on page 66. 8 How can a program pass one channel to another one? 9 Are CICS Java classes provided to manage channels and containers? 192 CICS Transaction Server V3 R1 Channels and Containers Revealed .No. see 2.1.2. “CICS Java” on page 69. “Designing a channel” on page 52. EXEC CICS LINK.9. “STARTBROWSE application programming interface” on page 36 and 3. EXEC CICS XCTL. must create the output containers.4.3. If a structure is optional.6.

6.3 Performance questions
Table 6-3 contains frequently asked questions dealing with the performance of channels and containers.
Table 6-3 Performance FAQs No. 1 Question Does the terminal input/output area (TIOA) size interfere in any way with channels transmission over MRO session? Answer The terminal input/output area used to process messages over MRO links has a maximum length of 32767 bytes, as defined in the parameter IOAREALEN. In case of channels and containers usage, where data may be larger than 32 KB, CICS splits the data into more 32 KB TIOAs as required and sends them to the remote region. In the remote region, CICS reassembles the 32 KB chunks of TIOA and presents them to the application as a channel. Note that using intersystem communication (ISC) links between CICS to pass containers data can affect performances, depending on the amount of data passed. The larger the data, the more response time is affected by the process of sending them. See 4.7, “Problem determination” on page 105. You must be careful when you use channels and containers to define the amount of extended dynamic storage area size. Also, in this case, if large amounts of data are to be PUT in a container, it can affect the extended dynamic storage area allocation. The data area is getmained in EUDSA and associated to the task. When you issue the put container command, it is also allocated in ECDSA subpool PGCSCB4K so that it can pass to the next program. This can cause stress conditions if the EDSASIZE parameter in DFHSIT is not well defined to meet such storage requirement. See 4.7, “Problem determination” on page 105.

2

Any suggestion about containers and storage usage?

Chapter 6. Frequently asked questions

193

No. 3

Question Is there any limitation to the container size used for data transfer in CICS Transaction Server 3.1?

Answer CICS does not enforce a size limitation for the container structure used in Enhanced Inter-program Data Transfer. You are limited only by the available storage in the CICS address spaces, and by any architected structure limits in the application programming language. Container storage is acquired in the CICS address space above the 16 MB line, but below the 4 GB bar. Instead of using a single large container for transferring data between programs, effective programming practice suggests defining multiple containers within a channel, based on purpose such as input, output, data type, data size, and so on. SeeChapter 4, “Systems management and configuration” on page 89. For such kind of data the temporary storage solution degrades compared to the channels and containers solution. See 4.4, “Performance considerations” on page 93.

4

What is the difference in performance between channels and containers and temporary storage (TS) used to transfer data exceeding 32 KB?

6.4 Functions not supporting channels and containers
Table 6-4 shows the functions and languages that currently do not support the channels and containers API.
Table 6-4 Functions not supporting channels and containers No. 1 2 3 Function C++ WEB API SOAP feature Comment Channels and containers support for C or C++ foundation classes is not in place. Channels and containers support for EXEC CICS WEB and DOCUMENT API is not provided. The CICS Transaction Server 3.1 Web services support for SOAP is different than the SOAP for CICS feature of CICS Transaction Server 2.2. You can still use the SOAP for CICS feature on the CICS Transaction Server 3.1, but we recommend using CICS Web services. SOAP feature uses BTS containers, not channels and containers API. CICS Transaction Gateway using ECI is not yet able to use these new enhancements. We do not (yet) support passing channels via EXCI.

4 5

External call interface (ECI) External CICS interface (EXCI)

194

CICS Transaction Server V3 R1 Channels and Containers Revealed

6.5 Online information about channels and containers
These are Web sites containing interesting information about channels and containers: The following is the Web site address of the Information Center for CICS Transaction Server 3.1. After opening the Web site go to Learning paths → Introduction to channels and containers: http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp The CICS Transaction Server V3.1 product main page, a summary of the function and technical detail: http://www-306.ibm.com/software/htp/cics/tserver/v31/apptrans/ A white paper describing using channels and containers to enhance CICS interprogram data transfer found at the following ftp site: ftp://service.boulder.ibm.com/software/htp/cics/pdf/cics-g224753500. pdf A CICS Transaction Server product support page that you can use to search for channels and containers and obtain useful tips: http://www-306.ibm.com/software/htp/cics/tserver/support/ A channels and containers presentation that was presented in 2005 during the Transaction and Messaging Conference that was held in Orlando, Florida: http://wmq.boulder.ibm.com/training/techconf/2005mq/C65-abs.pdf

6.6 Hints and tips
The following is a list of some hints and tips: To determine if a container was put as a BIT or CHAR Perform a GET CONTAINER NODATA CCSID(00037) and check the resp code. If it comes back as RESP=X, RESP2=Y, then the container is of type BIT. To access the current channel in JCICS other than using Task.getCurrentChannel(); If the name of the current channel is "CURRCHAN" then the following JCICS call explicitly returns a reference to the current channel: Task.createChannel("CURRCHAN"); The point at which the container is actually created inside of CICS while using JCICS to create a container.

Chapter 6. Frequently asked questions

195

When the data is put into the container using JCICS, the container is created inside of CICS as the following code snippet shows: Channel myChannel = Task.createChannel(); Container myContainer = myChannel.createContainer(); myContainer.put("Hello"); // It is at this point that the container is created in CICS

196

CICS Transaction Server V3 R1 Channels and Containers Revealed

197 . to link to the existing channel-aware business logic. We have extended the EJB Hello World sample application to utilize the relevant JCICS classes. © Copyright IBM Corp. to the CICS back end application. CICS Java Enterprise JavaBeans example This appendix is a description of how to invoke an existing Customer Information Control System (CICS) assembler application from a session bean running in a CICS Transaction Server Version 3. This is achieved using Java classes. 2006. rather than a communication area (COMMAREA). The enterprise beans JCICS link request passes a channel.A Appendix A. All rights reserved. from the CICS Java (JCICS) class library.1 Enterprise JavaBeans™ (EJB™) server.

which starts the naming server.1 Figure A-1 Structure of the JCICS EJB sample 198 CICS Transaction Server V3 R1 Channels and Containers Revealed . Web application enterprise archive (EAR) file Export the CICSHelloWorld. “Additional material” on page 207. Class of service (COS) naming server We used the TNAMESERVE command on the Windows command prompt. The way to set one up is described in the CICS information center section Setting up an EJB server. http://localhost:9080/cicshello COS Naming service 9. The CICS back end program Create an assembler program LNKFRST1 that gets passed a channel from the EJB JCICS link request. Figure A-1 shows the structure of the JCICS EJB example application.jar file.155. By default it listens on port 900. “Additional material” on page 207. The EJB jar file Export the HelloWorldEJB.15. CICS EJB server The CICS region must be set up as an EJB server. which is available in Appendix B.EAR file.0 pa JC ss IC in Sg Li a Ch nk an ne l CICS TS 3. which is available in Appendix B.Channel and containers JCICS EJB example The following components are used and are prerequisite to run the application: IBM WebSphere Application Server Use a WebSphere Application Server V6 to deploy the Web application.141 Client Web Application JCICS-EJB CICS Programs WAS 6.

a program name. passing the input the parameters entered by the user 3. The back end appends a string in front of the phrase and returns to the Web application. The user starts the application from a Web browser. When the user clicks the Submit button. and a channel name. CICS Java Enterprise JavaBeans example 199 . which is passed to a channel-aware CICS back end program. Enterprise Edition (J2EE) Web application server An enterprise bean running on a CICS EJB server A back end assembler program The sample works according to the following steps: 1. The phrase is copied to a container. the servlet is invoked. 2. 5. The servlet performs the following functions: – Looks up a reference to the enterprise bean in the Java Naming and Directory Interface (JNDI) namespace – Creates a new remote instance of the enterprise bean in CICS – Invokes a method on the bean-instance. which is passed to an EJB. It copies the phrase into the container. Appendix A. 4. After that the enterprise bean issues a JCICS link to the CICS back end program passing the channel.What the JCICS EJB example does The extended EJB Hello World application requests an input phrase from an HTML form. The enterprise bean business method uses the relevant JCICS classes to create a channel and container. It appends the phrase to its program name and returns. The sample consists of: An HTML form A Java servlet. running in a compliant Java 2 Platform. The servlet uses a JavaServer page to display the result on the user's browser. On return the enterprise bean appends the returned phrase to the string You said and returns the result to the servlet. plus JavaServer™ Pages™ (JSPs). 6. The form asks the user to input a phrase. A form is displayed. The CICS back end program issues a get container command.

and a JNDI prefix. The program name and the channel name is entered. You have to provide the hello string.JavaServer pages The existing JavaServer pages from the original Hello World EJB sample application are used. Figure A-2 shows the JCICS EJB sample screen. Figure A-2 JCICS EJB sample screen 200 CICS Transaction Server V3 R1 Channels and Containers Revealed . a JNDI provider URL. Two additional parameters that are passed to the enterprise bean are added. The Submit button invokes the servlet. The other parameters are still the same as the original Hello World sample uses.

Figure A-3 shows the result display from the second JavaServer page. /** * HelloWorldBean.sample. the program name.java * * This class provides the Session Bean implementation for the CICS * EJB Hello World sample Appendix A. Figure A-3 JCICS EJB result screen JCICS business method Example A-1 shows how to change the business method of the Hello World sample application. Example: A-1 EJB business method package cics. The enterprise bean appended the phrase to You said. CICS Java Enterprise JavaBeans example 201 . and the string. The channel name. See the relevant comments in the code: Create the channel Create the container Put the data into the container Link to program passing the channel See Example A-1. The CICS back end program appended the phrase to LNKFRST1 RETURNED=. The hello method use to take one parameter. The code demonstrates how the JCICS classes was used to link to the CICS back end program passing a channel. which was the hello string. We extended the method to take three strings.

202 CICS Transaction Server V3 R1 Channels and Containers Revealed .String newHelloString.Properties.ibm. * @param newHelloString java. com. // create the channel Channel tstglues = t.util.String */ public String hello(java. javax.getTask().cics. try { Task t=Task. /** * ejbActivate method */ public void ejbActivate() {} /** * ejbCreate method */ public void ejbCreate() {} /** * ejbPassivate method */ public void ejbPassivate() {} /** * ejbRemove method */ public void ejbRemove() {} /** * The one and old 'business' method on the enterprise bean.String newchannelname) { String logMessage.*. java.*/ import import import import java.lang.createChannel(newchannelname).lang. java. public class HelloWorldBean implements SessionBean { private javax.lang.ejb.server.SessionContext mySessionCtx = null. java.rmi.RemoteException.lang.String newprogname.*.ejb.

} } Appendix A. // Link to the program passing the channel Program p = new Program().get().SessionContext ctx) { mySessionCtx = ctx. } /** * setSessionContext method * @param ctx javax.out. p.createContainer("MAINCNT1"). t.SessionContext */ public void setSessionContext(javax.// create the container Container maincnt1 = tstglues.println(">>>> back in the enterprise bean" + retd). } catch (Throwable th) { System.put(newHelloString). //String retd = new String( ReturnData ). String retd = new String( ReturnData ). newHelloString = new String( ReturnData ). // put the data into the container maincnt1.println("some sort of error occurred ").ejb. p.setName(newprogname). CICS Java Enterprise JavaBeans example 203 . } return "You said: " + newHelloString .link(tstglues).err. byte[] ReturnData = maincnt1.ejb.

Example: A-2 CICS back end program DFHEISTG DSECT RESP DS F RESP2 DS F CA1 DS 0CL50 PROGRAM DS CL8 RETMSG DS CL10 CA1STR DS CL30 MIGRCHN DS CL16 MIGRCNT DS CL16 *CA DSECT CASTRING DS CL30 LINKFRST CSECT BEGIN DS 0H * L 4. See Example A-2. Then issue a GET CONTAINER(CA1STR) command in order to append the string to the program name. We specified CA1 on the FROM option.=CL10' RETURNED=' EXEC CICS ASSIGN PROGRAM(PROGRAM) RESP(RESP) RESP2(RESP2) EXEC CICS GET CONTAINER(MIGRCNT) INTO(CA1STR) EXEC CICS PUT CONTAINER(MIGRCNT) FROM(CA1) RETURN DS 0H EXEC CICS RETURN END //LKED.DFHEICAP * USING CA.=CL16'MAINCNT1 ' MVC RETMSG. which copies the assembled string into the container.CICS back end program Example A-2 shows the assembler program that gets called by enterprise bean.4 MVC MIGRCNT. return to the caller which is the enterprise bean. After this issue a put container command. Issue an ASSIGN PROGRAM() command to get the program name to which you append the hello string. After this.AMODE(31) NAME LNKFRST1(R) /* // 204 CICS Transaction Server V3 R1 Channels and Containers Revealed .SYSIN DD * MODE RMODE(ANY).

ear files you must use the files that we provided in Appendix B.jar and CICSHelloWorld. Compile and link the CICS back end program LNKFRST1. “Additional material” on page 207.Installation In order to install the EJB JCICS example do the following: 1. Appendix A. Install the HelloWorldEJB. 2. You can use the CICS information center to get the installation description for the CICS Hello World sample application. Instead of using the CICS provided HelloWorldEJB.ear file. CICS Java Enterprise JavaBeans example 205 .jar file and CICSHelloWorld.

206 CICS Transaction Server V3 R1 Channels and Containers Revealed .

Additional material This chapter refers to the additional material that you can download from the Internet. © Copyright IBM Corp.com/redbooks Select the additional materials and open the directory that corresponds with the IBM Redbook form number. 207 . 2006. Locating the Web material The Web material associated with this book is available in soft copy on the Internet from the IBM Redbooks™ Web server. SG247227. you can go to the IBM Redbooks Web site at: ibm.ibm.B Appendix B. These additional materials provide you with further information about the various aspects involving Customer Information Control System (CICS) channels and containers and also communication areas (COMMAREAs). Point your Web browser to: ftp://www.redbooks. All rights reserved.com/redbooks/SG247227 Alternatively.

PHONETIC. This subroutine is provided in Example B-1.zip There are four zipped code samples.ear file and the HelloWorldEJB. PROGRAM-ID. “Application design and implementation” on page 23.jar are figures that show sample screens of CICS and JCICS EJB. Sample server program used in some examples In some examples in Chapter 2.COBOL3') APOST TRUNC(BIN) IDENTIFICATION DIVISION.xls file shows the fluctuations in user CPU time.xls file shows the outputs for XEIIN and XEIOUT global user exit points. System requirements for downloading the Web material The following system configuration is recommended: Hard disk space: Operating System: Processor: Memory: 1. The CICSHelloWorld. Example: B-1 Subroutine to return string PROCESS LIST CICS('SP. ***************************************************************** * CHANGE A NAME (40Bytes) to a phonetic name (40Bytes) * * COMMAREA AND CHANNEL INTERFACDE * ***************************************************************** 208 CICS Transaction Server V3 R1 Channels and Containers Revealed . This subroutine changes the name into a phonetic string and returns the string to the caller through the channel or the COMMAREA.2 MB minimum Windows 500 MHz or higher 256 MB preferably 512 MB How to use the Web material Create a subdirectory or folder on your workstation and unzip the contents of the Web material zip file into this folder.Using the Web material The additional Web material that accompanies this IBM Redbook includes the following files: File name Description SG24-7227Web_Content. we used a program which could receive a name in a channel or a COMMAREA. The cattrace. The catalog.

01 MYBROWSETOKEN PIC 9(8) BINARY. 03 PNAME PIC X(40). *------. 01 TAB1-1 REDEFINES TAB1-1X.counter --------* 01 I PIC 9(2). 01 01 01 01 TAB2-1X PIC X(15) VALUE "ZKGQ IJ FWPT$". 03 ZEICHEN PIC X OCCURS 15 TIMES. 01 RSN PIC 9(8) BINARY. TAB2-3 REDEFINES TAB2-3X. *------.flags ------------------* 01 SWITCH PIC X(2).RETURN AND REASON CODES -----------* 01 RC PIC 9(8) BINARY. 03 TAB2-1-FIELD PIC X OCCURS 15 TIMES. VALID-CHARACTERS-TAB REDEFINES VALID-CHARACTERS.CHANNEL STUFF ---------* 01 CURRENTCHANNELNAME PIC X(16). 03 TAB1-3-FIELD PIC X(2) OCCURS 18 TIMES. 01 TAB1-3 REDEFINES TAB1-3X. 01 OUTPUTCONTAINER PIC X(16) VALUE IS 'PHONETICNAMECONT'. *------. 01 DFHCOMMAREA. 03 LNAME PIC X(40). WORKING-STORAGE SECTION. 03 TAB1-1-FIELD PIC X(2) OCCURS 18 TIMES. *------.DATA DIVISION. TAB2-1 REDEFINES TAB2-1X. LINKAGE SECTION. 01 TAB1-3X PIC X(36) VALUE 'C C C C C C X KVV V Y E E AYAYOYA$$ '. Appendix B.TABLES ---------* 01 TAB1-1X PIC X(36) VALUE 'SCSZCZTZTSDSKSQUPFPHUEAEOEEIEYEUAUOU'. *------. Additional material 209 . 03 REDEFINES PNAME. TAB2-3X PIC X(15) VALUE 'CCCCEYEYYSVVBDU'. 01 01 01 P POINTER. 88 LETTER-OK VALUE IS 'OK'. 01 INPUTCONTAINER PIC X(16) VALUE IS 'NAMECONTAINER '. VALID-CHARACTERS PIC X(15) VALUE 'ABCDLMNORSUVSXY'. 03 TAB2-3-FIELD PIC X OCCURS 15 TIMES. 01 K PIC 9(2).

IF CURRENTCHANNELNAME IS EQUAL TO SPACES THEN CONTINUE * continue with commarea ELSE * try to find out the name of the input container EXEC CICS GETMAIN SET(P) FLENGTH(LENGTH OF DFHCOMMAREA) INITIMG(X'40') END-EXEC SET ADDRESS OF DFHCOMMAREA TO P EXEC CICS GET CONTAINER(INPUTCONTAINER) CHANNEL(CURRENTCHANNELNAME) INTO(LNAME) END-EXEC END-IF. * change single characters MOVE X'0A3A39' TO TAB2-1X(5:3) MOVE X'45' TO TAB2-1X(10:1) PERFORM WITH TEST BEFORE VARYING I FROM 1 BY 1 UNTIL I > LENGTH OF TAB2-1X INSPECT PNAME REPLACING ALL TAB2-1-FIELD (I) BY TAB2-3-FIELD (I) END-PERFORM. EXEC CICS ASSIGN CHANNEL(CURRENTCHANNELNAME) END-EXEC. * delete non valid characters PERFORM WITH TEST BEFORE VARYING I FROM 1 BY 1 UNTIL I > 40 MOVE SPACE TO SWITCH PERFORM WITH TEST BEFORE VARYING K FROM 1 BY 1 UNTIL K > LENGTH OF VALID-CHARACTERS-TAB IF LETTER (I) = ZEICHEN (K) THEN MOVE 'OK' TO SWITCH 210 CICS Transaction Server V3 R1 Channels and Containers Revealed . * uppercase the input string MOVE FUNCTION UPPER-CASE (LNAME) TO PNAME.05 / LETTER PIC X OCCURS 40 TIMES. PROCEDURE DIVISION USING DFHCOMMAREA. * establish addressibility. * change double characters PERFORM WITH TEST BEFORE VARYING I FROM 1 BY 1 UNTIL I > ( LENGTH OF TAB1-1X / 2 ) INSPECT PNAME REPLACING ALL TAB1-1-FIELD (I) BY TAB1-3-FIELD (I) END-PERFORM.

PERFORM COMPRESS-STRING. * delete double characters PERFORM COMPRESS-STRING. PERFORM WITH TEST BEFORE VARYING I FROM 1 BY 1 UNTIL I = 40 IF LETTER (I) = LETTER (I + 1) THEN MOVE SPACE TO LETTER (I) ELSE CONTINUE END-IF END-PERFORM. * if a channel is available. Additional material 211 . ***************************************************************** * subroutine * ***************************************************************** * delete all blanks COMPRESS-STRING. GOBACK. * return to caller EXEC CICS RETURN END-EXEC.ELSE CONTINUE END-IF END-PERFORM IF LETTER-OK THEN CONTINUE ELSE MOVE SPACE TO LETTER (I) END-IF END-PERFORM. then move output into container IF CURRENTCHANNELNAME IS EQUAL TO SPACES THEN CONTINUE * continue with return to cics ELSE EXEC CICS PUT CONTAINER(OUTPUTCONTAINER) FROM(PNAME) END-EXEC END-IF. PERFORM 40 TIMES PERFORM WITH TEST BEFORE VARYING I FROM 1 BY 1 UNTIL I = 40 IF LETTER (I) = ' ' THEN MOVE LETTER (I + 1) TO LETTER (I) Appendix B.

212 CICS Transaction Server V3 R1 Channels and Containers Revealed .MOVE ' ' TO LETTER (I + 1) ELSE CONTINUE END-IF END-PERFORM END-PERFORM. * END PROGRAM PHONETIC.

2006. Note that some of the documents referenced here may be available in soft copy only.ibm. Application Development for CICS Web Services. 213 .Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.boulder. pdf © Copyright IBM Corp. a summary of the function http://www-306. SG24-5275 Other publications These publications are also relevant as further information sources: CICS Transaction Server for z/OS V3. see “How to get IBM Redbooks” on page 214.com/software/htp/cics/tserver/v31/apptrans/ CICS Transaction Server product support page http://www-306.ibm.1 CICS Customization Guide.com/software/htp/cics/support/ CICS product main page.com/software/htp/cics/pdf/cics-g224753500. IBM Redbooks For information about ordering these publications. All rights reserved. SG24-7126 Java Application Development for CICS.ibm.ibm.com/software/htp/cics/tserver/support/ Description of channels and containers that can be downloaded from the following ftp site ftp://service. SC34-6429 Online resources These Web sites and URLs are also relevant as further information sources: CICS family product support page http://www-306.

Information center for CICS Transaction Server 3.ibm.boulder. Hints and Tips. or download IBM Redbooks.com/support IBM Global Services ibm.jsp The presentation about channels and containers done during the 2005 Transaction and Messaging Conference that was held in Orlando. as well as order hardcopy IBM Redbooks or CD-ROMs.1 containing the learning path to Introduction to Channels and Containers http://publib.FL http://wmq.com/services 214 CICS Transaction Server V3 R1 Channels and Containers Revealed . at this Web site: ibm. draft publications and Additional materials. Redpapers.boulder.pdf How to get IBM Redbooks You can search for.ibm.com/redbooks Help from IBM IBM Support and downloads ibm. view.com/training/techconf/2005mq/C65-abs.com/infocenter/cicsts/v3r1/index.

54. 184 stage2 139 example 136 application 135. 201 solution 32 CHANNEL CHN 115 channels and containers 1 benefits 19 concepts 8 programming 59 A abend code 103–105 ACPR parameter 106–107. 67. 182 migration 136. 23. 91. 61. 69 API (application programming interface) 18 application design 23 implementation 23 programmer 18. 153 CCSID 40. 147. 154 program 139. 72 BIT 60. 38–40. 187 function test 139 new structure 137 original ID 183 Web service support extension 134 BIGR transaction 129. 154 module 136–138. 139 program 136 return 138. 12. 143.Index Numerics 32KB buffer 123–124. 61. 215 . 92 particular conversion 92 value 61 CECI example 45 channel example 25 name 10. 138 module 136. 39. 143 inquire single function 168 issue 168 item image 171 migrated version 156. 85 program part 85 context 16. All rights reserved. 108–109 parameter list 107–108 API 27. 2006. 170. 70 BROWSETOKEN 66 BTS © Copyright IBM Corp. 84 BTS (business transaction services) 17 business transaction services (BTS) 17 C catalog item cost column 165 image 134 image support 169 catalog manager 136 application 139. 59. 43. 127. 76. 40. 131 binary data 19. 132 AOR (application-owning region) 127 APAR 103 APAR (authorized program analysis report) 59 APCR parameter 106. 182 business logic 136 program 137–138. 109 AOR 104. 54. 128 container area 128 32KB COMMAREA limit 8 restriction 5 size constraint 5 activity 10. 93 application programming interface (API) 18 application-owning region (AOR) 127 ASSIGN CHANNEL 63 authorized program analysis report (APAR) 59 B back level toleration 103 base application 137. 42. 122. 162. 182 containers interface 175 DFH0XCMN 138.

67 container channel 15. 198 system 19. 102–103. 133 catalog example 134 new programming approach 8.1 level 191 V3. 110. 109. 90–91 dfjcics.1 4–5. 36. 193. 91 COMMAREA 49. 49. 74 DELETE CONTAINER 65.storage 47 subroutines 38 tracing applications 110 CHAR 60. 91. 53.1 region 105 CICS (Customer Information Control System) 16 CICS Java (JCICS) 75 code page 19. 195.1 EJB server 197 V3. 39–40. 147 pool 116 usage 24 ContainerErrorException 69 containerIterator() 73 copybook 7 createChannel() 69 createContainer() 69 current channel 63.1 information center 60. 91. 210 DFHDYP 90 DFHDYPDS 90 DFHEISTG DSECT 81. 72. 73 Customer Information Control System (CICS) 16 D data conversion 18. 70 character data 18. 69 V3. 42. 190 name 15. 103. 197. 105. 42. 60. 192 separation 93 type varied mix 4 DATATYPE 43. 176. 46. 61 CICS application 16. 68 delete() 74 deleteContainer() 74 DFHCOMMAREA 29. 10. 153. 68. 72.jar 69 DISPLAY PNAME 25. 75. 43. 40. 204 DFHROUTE 90 container 51. 74. 85 DATATYPE(DFHVALUE(BIT)) 61 DATATYPE(DFHVALUE(CHAR)) 61 DBCS (double-byte character set) 40 debugging 110 default CCSID 40 code page 70. 188 Transaction Gateway 5 Transaction Server C-language program 39 COBOL program 39 file application 44 program 39. 52. 50. 208 alternate solutions 5 application 18 data conversion 18 characteristics 2 constraints 5 data passing 2 example 24 migration 20 overload 33 scenario 94. 90–91. 10. 190 command 14. 58. 93 216 CICS Transaction Server V3 R1 Channels and Containers Revealed . 67. 199 data 14. 41. 8. 103 region 41 SOAP application 42 V2. 128. 191 V3. 190 region 7. 92. 111. 16 request processing path 8 Java class 192 class library 197 environment JCICS class 17 program 7–8. 15. 105. 91 character data 19 conversion 39. 67. 30.2 194 V3. 62. 34 distributed program link (DPL) 2. 98 solution 31 structure 6. 140–141 COMMAREA (communication area) 16 COMMAREAs to channels migration 54 communication area (COMMAREA) 16 CONTAINER BROWSETOKEN 12.

77. 91 ECI (external call interface) 5 enterprise bean 17. 81. 204. 63. 52–53. 170 hierarchical file system (HFS) 139 Index 217 . 112. 153 LINK PROGRAM channel 14 MOVE CONTAINER channel 14–15 read 170 return 36. 67 INQ Channel 190 link 10. 15 CICS 6. 9.double-byte character set (DBCS) 40 DPL (distributed program link) 2 DPL call 52 dynamic routing 48 data content 104 environment 49 exit 49 program 57. 81. 90. 170. 140 single 95 EXCI (external CICS interface) 5 EXEC API support 17 verb 8. 157–158 link activity 80 link command 81. 37. 95. 204. 190 RETURN TRANSID COMMAREA 5 start 21. 200 new remote instance 199 error data 95 error information 7. 103 WRITEQ transient data queue 83 XCTL 10. 33. 138 link program 9. 14. 41. 170. 190 FROMCCSID 61 G GET CONTAINER 64 get() 72 getCurrentChannel() 72 GETNEXT CONTAINER call 67 call insert 67 global user exits (GLUEs) 104 H HFS (hierarchical file system) 139 HFS directory 174 catalog item image 170 image file 168. 121. 90 dynamically-routed application 57 E EBCDIC encoding 39. 56. 57. 140. 37. 65 flow intersystem communication 132 multiregion operation 122 FREEMAIN 66. 61. 111 EXEC CICS 24–25. 211 ABEND 142 ABEND ABCODE 156 API 60 CHECK activity 80 command 9 GETMAIN 210 GETNEXT Container 12. 33. 43–44. 211 RETURN ENDACTIVITY 78–79 RETURN TRANSID 29 RETURN TRANSID channel 14. 57. 55. 192 dedicated container 52. 91. 126. 14 XCTL program 62 CICS START TRANSID 5. 90 link 25 LINK PROGRAM channel 60 MOVE container 26 RETURN TRANSID 26 channel 60 WRITEQ transient data queue 45 XCTL program 56 XCTL PROGRAM channel 60 EXEC CICS START TRANSID 60 Extended Binary Coded Decimal Interchange Code (EBCDIC) 74 external call interface (ECI) 5 external CICS interface (EXCI) 5 F file control 183–184 file example 44 FLENGTH 60.

130–132 PG 1701 PGCH Exit 113–114. 66. 210 inquire catalog request 01INQC 157 parameter 158 single request 01INQS 157 ID 170 INTO 65 INTOCCSID 64 option 43. 209 place order request 01ORDR 157 type 159 PLACE-ORDER 157. 129. 50 Q QUANTITY-REQ 144. 65 INVREQ 63 response 61 issue() 71 O output container 32. 93. 116. 124–126. 197. 143. 201 program 73. 192 P performance 93 PG 1700 PGCH Entry 113–114. 33. 105. 148. 149. 83 218 CICS Transaction Server V3 R1 Channels and Containers Revealed . 126. 120–121. 33. 172 JCICS (CICS Java) 75 L LENGERR 65 link() 70 LOCALCCSID 61 LOCALCSSID 92 LU62 FMH5 124 M memory constraints 3 message queue 42 migration issues 102 MODE RMODE 78. 210 processor time 186 program BIGREM 112–113 source code 112 pseudo-conversation 62. 160 return code 124–125. 130 PG 1900 PGCR Entry 115–116. 127. 128 request 100 put() 70 J Java 69 JavaServer Page 199–200 JCICS API 69 class 17. 123. 68 MRO link 98. 152. 128. 204 monitoring 99 changes 99 MOVE CONTAINER 65. 126. 116. 148. 168–169. 104 PUT CONTAINER 60 command 27. 145 RC-MSG container 171 separate input container 143 N non-BTS client 76. 118–121. 172–173 cycle 128 data 100 process 114. 132 PIC 9 29. 193 32K data size 98 export_all function 123 MYCOMMAREA 34. 50. 145. 127. 129–130. 127. 128. 81. 185 PROCEDURE division 29. 170 response message 145. 118. 117–118. 160 presentation logic DFH0XGUI 137. 121. 160 R RC (return code) 31 Redbooks Web site 214 Contact us xii request ID 145. 132 PG 1901 PGCR Exit 115. 120–121. 116. 118–121. 199.I input container 50. 124–125. 118. 155. 130–132 PG 1800 PGCP Entry 114. 83–84.

145. 122. 56. 74 sub routine 186 processor time 186 Systems management and configuration 89 V Virtual Storage Access Method (VSAM) 155 VSAM data handler DFH0XVDS 155 module 155. 90. 170. 93. 151 single-byte character set 40 string 40 SOAP example 42 start transid 71 statistical changes 101 storage 90 String. 143. 118. Index 219 . 135 VSAM (Virtual Storage Access Method) 155 VSAM data handler module DFH0XVDS 155 W WORKING-STORAGE section 34. 184 module DFH0XVDS 155 return 160 stub DFH0XVDS 136 file 6. 113. 126. 139. 145. 192 CA-INQUIRE-REQUEST structure 145 server program 12. 192 issue 41 output containers 143 PAYR 82 servlet 199–200 SET 65 setNextChannel() 71 single container 22.structure items 143 return code (RC) 31 return transid 71 routing program 48. 81–83 TRUE (task related user exit) 104 113–116. 104 U Unicode 74 URM (user replaceable module) 104 user replaceable module (URM) 104 UTF-8 74 S sample application trace flow 111 separate container 15. 51. 36. 119–121 128–130 131–132 122. 209 X XCTL 62 command 2.getBytes() 70. 157. 57. 132 TOR (terminal-owning region) 49 trace entries 106 transaction BIGL 111. 78. 79. 120 TRN. 76. 94. 140. 54.SYSIN DD 77. 60 T task related user exit (TRUE) 104 TASK-00043 KE_NUM-00EA TCB-QR 118 TASK-00044 KE_NUM-00E9 TCB-QR TASK-00131 KE_NUM-00EB TCB-QR TASK-00132 KE_NUM-00EC TCB-QR TASK-00155 KE_NUM-00E8 TCB-QR 124–126 terminal-owning region (TOR) 49 TOR 104. 93. 52–53. 140.

220 CICS Transaction Server V3 R1 Channels and Containers Revealed .

CICS Transaction Server V3 R1 Channels and Containers Revealed (0.473” 90<->249 pages .2”spine) 0.17”<->0.

.

.

Some APARs are introduced. The BTS API is discussed as a similar yet recoverable alternative to channels and containers. It provides an overview about techniques used to pass data between applications running in CICS and their constraints. INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. It provides information. It shows how to migrate an existing CICS application to exploit channels and containers instead of using COMMAREAs.Back cover ® CICS Transaction Server V3R1 Channels and Containers Revealed Converting a COMMAREA based application to use channels and containers Configuring systems.1.com/redbooks SG24-7227-00 ISBN 0738495824 . discussing the systems management. Experts from IBM. For more information: ibm. It provides examples to show how to evolve channels and containers from COMMAREAs. This book presents information from a systems management point of view. including sample application Simplifying process for code page conversion This IBM Redbook discusses the new channels and containers support in CICS Transaction Server 3. which allows CICS to fully comply with emerging technology requirements in terms of sizing and flexibility. It explains the channels and containers API and its uses in a traditional CICS application and also a JCICS application. configuration tasks. which enable more flexible Web services features through the use of channels and containers. This book discusses about application design and implementing channels and containers from an application programmers point of view. Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment. and techniques that you must consider when implementing a channels and containers solution.

Sign up to vote on this title
UsefulNot useful