CICS FAQ

CICS for OS/2 - Frequently Asked Questions Version 1.1 Document: Issued: Revision Date: Previous Revision Date: Nextt Rev Nex Review iew::

CA38 21st March, 1996 15th December, 1998 21st March, 1996 None

Bill Matthews IBM Systems Support Center Roanoke Dallas TX, 76262

Revision Revision Date: Date: 15th Decem December, ber, 1998 1998 Document Id: CA38 Title: Title: CICS CICS for OS/2 OS/2 - FAQ FAQ

Page ii

Take Take Note Note!! Before using this User's Guide and the product it supports, be sure to read the general information under "Notices".

Second Edition, December 1998 This edition applies to Version 1.1 of CICS for OS/2 - Frequently Asked Questions and to all subsequent releases and modifications until otherwise indicated in new editions. A form for reader's reader's comments is provided provided at the back of this publication. publication. If the form has has been removed, address address your comments to: IBM United Kingdom Laboratories Transaction Systems Marketing Support (MP207) Hursley Park Hursley Hampshire, SO21 2JN, England When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate appropriate without incurring incurring any obligation obligation to you. You may continue to use the information information that you supply. Copyright International Business Machines Corporation 1998. All rights rights reserved. reserved. Note to U.S. Government Users - Documentation related to restricted right Use, duplication or disclosure is subject to restrictions set forth in GS Schedule Contract with IBM Corporation.

©


Page iii

Contents 1.0 1.0 Intr Introd oduc ucti tion on

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

2.0 An Histor Historica icall Perspec Perspectiv tivee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 2.1 Mile Milest ston ones es . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2 2

3.0 3.0 Appl Applic icat atio ion n Deve Develo lopm pmen entt . . . . . . . 3.1 Performan Performance ce of DTP applicatio applications ns . . . Application Design Discussion . . . . . Answer . . . . . . . . . . . . . . . . . . Additional Information About the Design Answer . . . . . . . . . . . . . . . . . .

4 4 4 4 5 6

. . . . . . . . . . 4.0 4.0 Btri Btriev evee 4.1 Maximu Maximum m Btrieve Btrieve files filesize ize.. Question . . . . . . . . . . Answer . . . . . . . . . . . 4.2 Use of of Btrie Btrieve ve 6.X 6.X in in batch batch Question . . . . . . . . . . Answer . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . 5.0 5.0 COMM COMMAR AREA EA and and ECI ECI 5.1 Allocating Allocating storage storage when when using using ECI . . . Question . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.0 6.0 Data Data Conv Conver ersi sion on . . . . . . . . . . . . . . . . . . . . 6.1 How is Data Conversio Conversion n handled handled?? . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . ASCII-EBCDIC conversion templates . . . . . . . . . 6.2 Data Convers Conversion ion on reques requests ts from from OS/2 to MVS/ESA MVS/ESA Question . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Sample Sample Data Data Conver Conversio sion n Table Table . . . . . . . . . . . . 6.4 Data Data conversi conversion/ on/bit bit swappi swapping ng . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5 Code Code Pages Pages & Data Data Conve Conversi rsion on . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . 7.0 7.0 Debu Debugg ggin ing g . . . . . . 7.1 What is an an Abend Abend AZI6 AZI6 Question . . . . . . . . Answer . . . . . . . . .

7 7 7 7 7 7 7 8 8 8 8

9 9 . . . . . . . . . . . . 9 . . . . . . . . . . . . 9 . . . . . . . . . . . . 9 . . . . . . . . . . . . . . . . . . . . . . . . 10 . . . . . . . . . . . . 10 . . . . . . . . . . . . 11 . . . . . . . . . . . . 11 . . . . . . . . . . . . 13 . . . . . . . . . . . . 13 . . . . . . . . . . . . 13 . . . . . . . . . . . . 13 . . . . . . . . . . . . 13 . . . . . . . . . . . . 14 . . . . . . . . . . . . 14 . . . . . . . . . . . . 15

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16 from from SRVTIME? SRVTIME???? ??? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8.0 8.0 Gat Gateway eway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1 8.1 CICS CICS OS/ OS/2 2 Gate Gatewa way y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18 18 18

Revision Date: 15th December, 1998 Document Id: CA38 Title: CICS for OS/2 - FAQ

Answer

Page iv

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . 9.0 General Questions about CICS for OS/2 9.1 Avoiding when trapping Question . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2 Maximum length of the COMMAREA . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3 Maximum number of tasks and minimum free tasks . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.4 How to Determine if a program(process) is running under Question . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.5 MAX tasks vs Minimum FREE tasks . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.6 CICS for OS/2 V2 Durability . . . . . . . . . . . . . . . A 1993 Durability Test . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CICS for OS/2

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . 10.0 Intersystem Communications 10.1 Private Mirror: What it is and how to use it . . . . . . . . . . . . . . Details on a Private Mirror . . . . . . . . . . . . . . . . . . . . . . . . . Example: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.2 Issuing SYNCPOINT in a DPL program . . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.3 Value of EIBTRMID . . . . . . . . . . . . . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.4 Memory Requirements for host CICS Sessions and Connection . . . Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parallel session devices: . . . . . . . . . . . . . . . . . . . . . . . . . . . LU 6.2 Session and memory consumption for Communications Manager/2 Send and Receive Buffers . . . . . . . . . . . . . . . . . . . . . . . . . .

11.0 Inter-System Communications . . . . . . . . . . . . . . . . 11.1 Is Two Phase Commit Supported? . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Connection Problems between CICS/ESA and CICS for OS/2 Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Solution Found . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Configuration Example for CICS for OS/2 to CICS/390 . . . Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VTAM Definitions . . . . . . . . . . . . . . . . . . . . . . . . . VTAM Definitions . . . . . . . . . . . . . . . . . . . . . . . . . CICS/390 Definitions . . . . . . . . . . . . . . . . . . . . . . . CICS for OS/2 Definitions . . . . . . . . . . . . . . . . . . . . Communication Manager/2 Definitions . . . . . . . . . . . . . . 11.4 Security From/To CICS OS/2 and CICS/ESA . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20 20 20 20 20 20 20 21 21 21 22 22 22 22 22 23 24 24 26 26 26 27 28 28 28 28 28 28 29 29 29 30 30

31 31 . . . . . . . . . . . . . 31 . . . . . . . . . . . . . 31 . . . . . . . . . . . . . 32 . . . . . . . . . . . . . 32 . . . . . . . . . . . . . 33 . . . . . . . . . . . . . 33 . . . . . . . . . . . . . 34 . . . . . . . . . . . . . 34 . . . . . . . . . . . . . 34 . . . . . . . . . . . . . 34 . . . . . . . . . . . . . 35 . . . . . . . . . . . . . 37 . . . . . . . . . . . . . 38 . . . . . . . . . . . . . 40 . . . . . . . . . . . . . 41

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18


Page v

Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.5 Security Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.6 Additional background on Security - recommended reading . . . . . . . . . . . . CICS OS/2 TERMINAL CONTROL TABLE (SYSTEM) . . . . . . . . . . . . . . NON-CICS OS/2 DEFINITIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . APPC REMOTELY ATTACHABLE TRANSACTION PROGRAM (TP) PROFILE HOST CICS DEFINITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

41 41 42 42 43 44 44

12.0 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.1 CICS OS/2 and C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

45 45 45

13.0 PEM . . . . . 13.1 PEM (Password Question . . . . Answer . . . . .

46 46 46 46

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Expiration Management) and CICS/OS2 V3.0

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14.0 3270 Support . 14.1 3270 Support . Question . . . . . Answer . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47 47 47 47


Page vi

Notices. The following paragraph does not apply in any country where such provisions are inconsistent with local law. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you. References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used. Any functionally equivalent program that does not infringe any of the intellectual property rights may be used instead of the IBM product. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594, USA. The information contained in this document has not be submitted to any formal IBM test and is distributed AS IS. The use of the information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item has been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: CICS OS/2 MVS CICS/ESA System 390 IBM


Summary of Changes Date

Changes

21st March 1996

Initial release as HTML files

16th December 1998

Updated and issue in Adobe Acrobat PDF format

Page vii


Page viii

Bibliography CICS Books (In English) 









CICS/ESA Version 3 Arcitecture and Problem Determination, Bob Archambeault and Mardie Gibbs, McGraw-Hill, J. Ranade IBM and DEC Series, 1994, ISBN: 0-07-002744-7 CICS Applications Design, Bob Crownhart, McGraw-Hill, 1994, ISBN: 0-07-014774-4, Misc: 217 pages The CICS Programmer's Guide to FEPI, Robert Harris, McGraw-Hill,1994, ISBN: 0-07-707793-8, Misc: available as SC33-1140 from IBM CICS - A Guide to Internal Structures, Eugene Hudders, The WileyQED IBM Mainframe Series, 1994, ISBN: 0-471-52172-8, Misc: 332 pages Distributed CICS: An In-Depth Assessment for Downsizing Applications, Richard Schreiber and William R Ogden, Wiley-QED, 1994, ISBN: 0-471-06055-0, Misc: 267 pages



CICS Catalog, The Standish Group, The Standish Group International, 1994



CICS Concepts and Uses - A Management Guide, Jim Geraghty, McGraw-Hill, 1993, ISBN: 0-07-707751-2































CICS Capacity Planning and Performance Management, Ted C. Keller, McGraw-Hill, 1993, ISBN: 0-07-033783-7, Misc: 407 pages Cooperative Processing Using CICS, Rob K. Lamb, McGraw-Hill, 1993, ISBN: 0-07-036111-8, Misc: 283 pages CICS Essentials (includes CICS/ESA 3.3) for Application Developers and Programmers, J Le Bert, McGraw-Hill, NY, 1993, ISBN: 0-07-035869-9, Misc: 440 pages CICS - A how-to for COBOL programmers, David Shelby Kirk, QED, 1993, ISBN: 0-89435-428-0, Misc: 371 pages CICS Performance Optimization, Xephon, Xephon, 1993 IBM's Workstation CICS, Bob Crownhart, McGraw-Hill, J. Ranade IBM Series, 1992, ISBN: 0-07-014770-1, Misc: 277 pages CICS - A Guide to Performance Tuning, Eugene S. Hudders, QED Publishing Group, 1992, ISBN: 0-89435-395-0, Misc: 214 pages CICS - A Guide to Application Debugging, Eugene S. Hudders, QED Publishing Group, 1992, ISBN: 0-89435-331-4, Misc: 403 pages Understanding CICS Internals, John Kneiling, Richard Lefkon, Pamela Somers, McGraw-Hill, 1992, ISBN: 0-07-037040-0, Misc: 290 pages CICS for the COBOL Programmer: Part 1: An Introductory Course (includes CICS/ESA 3.3), D. Lowe, Murach and Associates, 1984 (Later edition 1992), ISBN: 0-911625-15-1, Misc: 326 pages (1984), ISBN: 0-911625-60-7, Misc: 409 pages (1992) CICS for the COBOL Programmer: Part 2: An Advanced Course, D. Lowe, Murach and Associates, 1985 (Later edition 1992), ISBN: 0-911625-16-X, Misc: 322 pages (1985), ISBN: 0-911625-67-4, Misc: 475 pages (1992) The CICS Programmer's Desk Reference, D. Lowe, M. Murtach & Associates, 1987 (Later edition 1992), ISBN: 0-911625-43-7, Misc: 489 pages (1987), ISBN: 0-911625-68-2, Misc: 507 pages (1992) CICS Application and System Programming, Barry K. Nirmal, The QED IBM Mainframe series, 1992, ISBN: 0-89435-393-4, Misc: 543 pages CICS-Command Level Programming, Alex Varsegi, McGraw-Hill, 1992, ISBN: 0-8306-6705-9, Misc: 282 pages New Directions in CICS, Xephon, Xephon, 1992,
























Page ix

Computer Audit Guidance Notes IBM software: MVS, CICS and SMF, Chartered Inst. of Public Finance and Accountancy, 1991, ISBN: 0-85299-342-0 CICS A Programmers Reference, P. Donofrio, McGraw-Hill, J Ranade IBM Series, 1991, ISBN: 0-07-017607-8, Misc: 254 pages CICS Command Level Programming, A. Jatich, John Wiley and Sons, NY, ISBN: 0-471-52861-7, Misc: 2nd Ed, 1991, 602 pages, ISBN: 0-471-88533-9, Misc: 1st Ed, 1985, 360 pages DOS/VSE CICS Systems Programming, Gary A. Stotts, QED Information Sciences Inc, Wellesley, MA, 1991, ISBN: 0-89435-379-9, Misc: 315 pages CICS Using COBOL, A.M. Suhy, Wadsworth Inc, Belmont, CA, 1991, ISBN: 0-534-12618-9, Misc: 403 pages CICS Debugging, Dump Reading and Problem Determination, P. Donofrio, McGraw-Hill, J Ranade IBM Series, 1989, ISBN: 0-07-017606-X, Misc: 176 pages A CICS Handbook, Y. Kageyama, McGraw-Hill, NY, 1989, ISBN: 0-07-033637-7, Misc: 616 pages CICS for Microcomputers, J Le Bert, McGraw-Hill, NY, 1989, ISBN: 0-07-036968-2, Misc: 362 pages CICS/VS Command Level Programming Techniques, M.H. Merchant, Prentice Hall, Englewood Cliffs, NY, 1989, ISBN: 0-13-133869-2, Misc: 286 pages CICS - A Practical Guide to System Fine Tuning, S. Piggott, McGraw-Hill, J Ranade IBM Series, 1989, ISBN: 0-07-050054-1, Misc: 202 pages Distributed Processing in the CICS Environment: A Guide to MRO and ISC, A.J. Wipfler, McGraw-Hill, J Ranade IBM Series, 1989, ISBN: 0-07-071136-4, Misc: 466 pages



CICS Performance Monitors: Xephon User Survey, Xephon, Xephon, 1989, Misc: 117 pages



CICS Performance Management, E. Emanuel, MacMillan, NY, 1988, ISBN: 0-02-949221-1, Misc: 352 pages



CICS/VS Command Level Handbook, A. Kaufman, Wiley, NY, 1988, ISBN: 0-0471-81207-2























CICS Programmers Guide, K. Kostohyrz, Weber Systems Inc, Chesterland, OH, 1988, ISBN: 0-938862-88-X, Misc: 286 pages CICS, S. Piggott, MacMillan, NY, 1988, ISBN: 0-02-947901-0, Misc: 352 pages CICS: Application development and programming, A. J. Wipfler, McGraw-Hill, 1988, ISBN: 0-07-071139-9, Misc: 414 pages CICS Performance, Xephon Consultancy Report, Xephon, 1988, Misc: 175 pages The CICS Companion: A reference guide to COBOL command level programming, T. Gildersleeve, Prentice Hall Inc, Englewood Cliffs, NJ, 1987, ISBN: 0-13-134461-7 Misc: 238 pages How to use CICS to create on-line Applications, Methods and Solutions, B. Musteata, QED Info sciences US, 1987, ISBN: 0-89435-182-6, Misc: 525 pages Advanced CICS Design Techniques, Concepts and Guidelines, J.E. Summerville, Van Nostrand Reinhold, 1987, ISBN: 0-442-28213-3, Misc: 259 pages Systems Design under CICS Command and VSAM, A. Varsegi, TAB Books, Blue Ridge Summit, PA, 1987, ISBN: 0-8306-2843-6, Misc: 272 pages CICS virtual storage: Online system design and implementation techniques, David Lee, Prentice Hall, ISBN: 0-13-133935-4, Misc: 397 pages, available in Italian, (CDD On-line Systems INC 1986, 0-9611810-7-9) CICS Command Level with ANS COBOL Examples, P. Lim, Van Nostrand Reinhold Co, NY, 1986 (2nd ed), ISBN: 0-442-25814-3, Misc: 582 pages, ISBN: 0-442-25845-3 (paperback) Misc: 582 pages CICS Primer, L. Ryan, Science Research Associates Inc (SRA), 1986, ISBN: 0-574-21940-? Misc: 326 pages, MacMillan Publishing Co, 1986, ISBN: 0-02-404941-7 Misc: 326 pages
















Page x

Customer Information Control System (CICS) Made Easy, J.J. Le Bert, McGraw-Hill, 1986, ISBN: 0-07-036972-0, Misc: 278 pages Specifying the CICS Applications Programmers Interface, I. Hayes, Oxford Computing Lab, 1985, ISBN: 0-902928-28-7, Misc: 82 pages On-Line Systems Design and Implementation Using COBOL and Command Level CICS, C. J. Kacmar, Reston Publishing Co, 1984, ISBN: 0-8359-5231-2 Misc: 404 pages CICS Mastering Command Level Coding Using COBOL, W. Bruno and L. Bosland, Prentice Hall Inc. 1984 (re-issued in 1988?), ISBN: 0-131-34073-5, Misc: 1986 200 pages, 0-13-134040-9 1984 edition CICS in Practice, Xephon, Xephon, 1984 CICS/VS Command Level Programming with COBOL Examples, D. Lee, CCD Online Systems Inc, 1983, ISBN: 0-9611810-1-X CICS/VS Command Level Reference Guide for COBOL Programmers, L. Viands, QED Information Sciences Inc, 1983, ISBN: 089435-101-X , Misc: 100 pages



CICS: Designing for Performance, E. Emanuel, McGraw-Hill, ISBN: 0-07-019420-3



Understanding CICS Internals, R. Lefkon, McGraw-Hill, ISBN: 0-07037040-0



CICS Virtual Storage Command Level Cobol, P.A. Lim, Reinhold, ISBN: 0-442-25845-3

CICS Books (In German) 



CICS leicht und schnell gelernt, Thomas Kregeloh / Stefan Schoenleber, Verlagsgesellschaft Rudolf Mueller Gmbh, Koeln 1991, ISBN: 3-481-00218-1, Misc: 362 pages CICS-Eine praxisorientierte Einfuhrung, Thomas Kregeloh / Stefan Schoenleber, Vieweg 1992, ISBN: 3-528-05272-4, Misc: 324 pages

CICS Books (In Italian - translation) 



CICS/VS - Tecniche di programmazione ed implementazione dei systemi on-line, David Lee, Gruppo Editoriale Jackson, ISBN: 88-256-0248-0 CICS, William G Bruno and Lois Bosland, Tecniche Nuovo 1990, ISBN: 88-7081-580-3

Related Books (OLTP etc) 











Messging and Queuing using the MQI, Burnie Blakeley, Harry Harris, Rhys Lewis, Jay Ranade Series, McGraw Hill, ISBN: 0-07-005730-3, Misc: 469 pages OLTP - On Line Transaction Processing Systems, Bill Claybrook, John Wiley, 1992, ISBN: 0-471-55668-8, Misc: 358 pages Open Enterprise Transaction Processing: Integrating the Tuxedo System with Mainframe CICS, Data Logic, Unix International, 1992, Misc: 172 pages IMS for the COBOL programmer Part 1 - DL/I database processing, Steve Echols, ISBN: 0-911625-29-1, Misc: 333 pages IMS for the COBOL programmer Part 2 - Communications Data and Message Format Services, Steve Echols, ISBN: 0-911625-30-5, Misc: 395 pages Database Transaction Models for Advanced Applications, A.K. Elmagarmid (editor), Morgan Kaufmann, 1992, ISBN: 1-55860-214-3, Misc: 611 pages




























Page xi

Camelot and Avalon: A Distributed Transaction Facility, Jeff Eppinger, Lily Mummert, Alfred Spector (editors), Morgan Kaufmann, 1991, ISBN: 1-55860-185-6, Misc: 505 pages The Benchmark Handbook for Database and Transaction Processing Systems, Jim Gray (editor), Morgan Kaufmann, 1991 (Later edition 1993), ISBN: 1-55860-159-7, Misc: 334 pages (1991), ISBN: 1-55860-292-5, Misc: 392 pages (1993) Transaction Processing - Concepts and Techniques, Jim Gray and Andreas Reuter, Morgan Kaufmann, 1993, ISBN: 1-55860-190-2, Misc: 1070 pages Performance Analysis of Transaction Processing Systems, Wilbur Highleyman, Prentice Hall, 1989, ISBN: 0-13-657008-9, Misc: 424 pages Micro Focus Workbench - Developing Mainframe COBOL Applications on the PC, Alida Jatich and Phil Nowak, John Wiley and Sons, Inc, Misc: 423 pages IMS programming techniques, Dan Kapp and Joe Leben, Van Nostrand Rheinhold, 2nd edition, ISBN: 0-442-24655-1, Misc: 338 pages IMS/VS DB/DC online programming using MFS and DL/I, David Lee, CDD Online Systems Data Processing Series, Misc: 300 pages IMS/VS DL/I programming with COBOL examples, David Lee, CDD Online Systems Data Processing Series, ISBN: 0-7611810-4-4 Atomic Transactions, Nancy Lynch, Michael Merritt, William Weihl, Alan Fekete, Morgan Kaufmann, 1994, ISBN: 1-55860-104-X, Misc: 500 pages IMS/VS Expert's Guide, Lockwood Lyon, Van Nostrand Reinhold, 1990, ISBN: 0-442-23977-7, Misc: 254 pages Z Guide for Beginners, Mike McMorran and Steve Powell, Blackwell Scientific Publications, 1993, ISBN: 0-632-03117-4, Misc: 247 pages Micro Focus CICS option, Developing CICS applications on the PC, Clayton L. McNally Junior, QED Publishing, 1993, ISBN: 0-89435-460-4, Misc: 292 pages Nested Transactions: An Approach to Reliable Distributed Computing, J. Eliot B. Moss, The MIT Press, 1985, ISBN: 0-262-13200-1, Misc: 160 pages



Object Transaction Specification, OMG Document TC-94-8-4, 1994



Software Development with Z, J.B. Wordsworth, Addison-Wesley, 1992, ISBN: 0-201-62757-4, Misc: 334 pages





Distributed Transaction Processing Reference Model, X/Open Guide, X/Open, 1991, ISBN: 1-872630-16-2, Misc: 30 pages Distributed Transaction Processing: The XA Specification, X/Open Guide, X/Open, 1991, ISBN: 1-872630-24-3, Misc: 80 pages


Page 1 of 47

1.0 Introduction The supplied document provides details extracted from various FAQ (Frequently Asked Questions) databases that exist within the CICS for OS/2 technical support community.


Page 2 of 47

2.0 An Historical Perspective 2.1 Milestones PUCICS Announced CICS (OS) Program Product Available CICS/DOS (Entry & Standard) Announce Virtual Storage for S/370 Announce CICS/VS (DOS/VS and OS/VS) Announce DFH = Destined for Hursley CICS/DOS/VS & CICS/OS/VS V1.1.1 Ships CICS/DOS/VS 1.2 Announce & Ship CICS/OS/VS 1.2 Announce & Ship (VS1) CICS/OS/VS 1.2 Announce & Ship (VS2) CICS/VS 1.4 Announce CICS/VS 1.5 Announce CICS/OS/VS 1.5 Ships CICS/OS/VS 1.6 Announce CICS/DOS/VS 1.6 Announc CICS/OS/VS 1.6.1 Announce CICS/OS/VS 1.7 Announce CICS/CMS Announce CICS/DOS/VS 1.7 Announc CICS/MVS V2.1 Announce CICS/VM V1 & V2 Announce CICS OS/2 V1 Announce CICS/MVS V2.1.1 Announce & Ship (28th) CICS/ESA V3.1 Announce CICS OS/2 V1.1 CICS OS/2 V1.2 Announce CICS OS/2 V1.2 Available CICS/ESA V3.2 Announce CICS/VSE V2.1 Announce CICS/MVS V2.1.2 Announce CICS/ESA V3.2.1 CICS/400 Announce CICS/ESA V3.3 Announce CICS/ESA V3.3 Available (Provided Bi-directional DPL support) CICS/VSE V2.2 Announce CICS OS/2 V2 Statement of Direction CICS/6000 Announce CICS for OS/2 V2 Beta start CICS/VSE V2.2 Ship CICS for OS/2 V2 Announce IBM MQSeries Announcements CICS on Windows VT V2 Announce CICS for OS/2 V2 Available CICS/ESA V4.1 Announce CICS Clients Announcements CICS/6000 V1R2 CICS for OS/2 V2.1 Transaction Server for OS/2 Warp V4.0

April 28, 1968 June 30, 1969 June 1970 August 1972 February 1973 August 1974 May 1975 February 1976 May 1976 August 1976 March 31, 1978 October 2, 1979 November 1980 July 1982 December 1982 March 1983 July 1985 October 1985 October 1986 February 17, 1987 October 20 1987 October 25, 1988 June 20, 1989 June 20, 1989 August 15, 1989 November 14, 1989 March 3, 1990 September 4, 1990 September 4, 1990 February 1991 March 22, 1991 February 18, 1992 March 3, 1992 March 27, 1992 June 23, 1992 September 15, 1992 September 22, 1992 February 5, 1993 March 12, 1992 March 30, 1993 March 30, 1993 June 8, 1993 October 8, 1993 February 1, 1994 January 26, 1995 January 26, 1995 January 26, 1995 March 12, 1996


Transaction Server for NT V4 Transaction Server for OS/2 Warp V4.1 VisualAge CICS for Windows NT V3 (Ships with VisualAge Cobol and PL/I V2.2) CICS Transaction Server for OS/390 V1.1 CICS Transaction Server for OS/390 V1.3 .

Page 3 of 47

November 11, 1996 March 24, 1998 April 17, 1998 September 10, 1996 September 9, 1998


Page 4 of 47

3.0 Application Development

3.1 Performance of DTP applications Application Design Discussion I have developed a DTP application between CICS for MVS/ESA and CICS for OS/2 which does the following:

CICS for MVS/ESA Transaction Reads a data record out of a DL/I Database and sends it to CICS for OS/2. This is repeated for each available data record in the DL/I database. The data records themselves are of varying length (between 50 and 200 bytes) and the number of data records to be sent is also variable.

CICS for OS/2 Transaction Receives a data record from CICS for MVS/ESA, converts the data from EBCDIC to ASCII and writes the data to TS Queues. This is repeated for each data record sent from the host transaction. Once all of the data has been received from the host CICS, it is read from the TS Queues and written to an ASCII file. The intermediate step involving the TS Queues is only done for data recovery/syncpointing purposes... The application logic works fine, but it runs rather slowly, and I want to improve the performance. From some tests I have done, I find that the data transfer rate works out to approximately 750 bytes/sec. Since some of the data to be transferred has a volume of approximately 30 MB, at the current rate, this transaction would be running for about 12 hours. Just for comparison, a normal 3270 file transfer for that quantity of data takes approximately half an hour! I am not sure why the performance is so poor...whether it is due mainly to the DL/I, the many SEND and RECEIVE operations (1 per data record, and where the larger transfers can have up to approximately 250,000 records), or the large number of WRITEQ TS (again, 1 per data record sent). My CICS for OS/2 TCS definition includes: Session Buffer Size = 32767 For the LU 6.2 session's mode definition I am currently using a Max RU Size = 256. Would it help significantly to increase this value? What value could be recommended? Or would it help significantly if I changed the application logic to send a larger number of data records at time instead of sending each one individually, thereby reducing the number of SEND and RECEIVE commands to be carried out?

Answer It looks as though delays can occur in several areas.


(1) (2) (3)

Page 5 of 47

loop : retrieve record from DL/I : send record to CICS for OS/2 : write record to TS : receive reply from CICS for OS/2 loop

1. represents the time taken to send the request through the network. Only one RU should be required given record lengths of 50 to 200 bytes 2. represents the time to write the record to auxiliary TS; the time depends on the recoverability of the queue; the time also depends on whether or not CICS for OS/2 forces each write. 3. represents the time taken to send the reply through the network. Why do you need to receive one reply from CICS for OS/2 for each record that is sent? If you eliminate the requirement then you have

loop : retrieve record from DL/I : send record to CICS for OS/2 loop CICS for MVS/ESA may defer passing the record (plus LLID prefix) to VTAM; data is held in an intermediate buffer and is sent either when the buffer is full or when the WAIT option is specified on the SEND command. The size of the buffer depends on RU size and is a minimum of 8K (from CICS for MVS/ESA 3.2.1 onwards). Increasing RU size from 256 bytes to 2048 bytes will reduce the number of RUs flowing through the network as well as reducing the number of RUs that have to be received by Communications Manager/2 on behalf of CICS for OS/2; however you must remember that a larger RU size may affect the overall network traffic.

Additional Information About the Design The sending application (CICS for MVS/ESA) does not get a reply back from the receiving application (CICS for OS/2) for each data record sent. Data is sent continuously until a syncpoint is to be taken (this is currently done after sending every 5000 records), at which time a SEND with the INVITE and WAIT options is made. The CICS for OS/2 application receives the 5000 records and then does a syncpoint. After the syncpoint, CICS for OS/2 sends a 1 character flag to CICS for MVS/ESA indicating that the syncpoint was made, at which time CICS for MVS/ESA also does a syncpoint. Then CICS for MVS/ESA starts to send data records continuously again. The TS Queues are defined as recoverable (for syncpointing purposes). Each data record is written to TS as it is received by CICS for OS/2. What do you mean by the statement "CICS for OS/2 forces each write"? Could the speed of writing the records physically to disk be the bottleneck? Can recoverable TS queues be defined to another medium that is faster than disk? If I leave my program logic unchanged (send each data record individually) increasing the RU size won't buy me much since the records are so small that they will fit into a single RU, but if I change the program logic around to send a larger number of data records at a time, then increasing the RU size to 2048 bytes would be recommended....correct? What is generally better...a lot of little RU's, or a smaller number of bigger RU's? You mentioned that larger RU sizes negatively affect the overall network traffic...in which way?


Page 6 of 47

Answer From a CICS for MVS/ESA point of view you should increase the RU size from 256 bytes to, for example, 4096 bytes. 1. If you specify the WAIT option on every SEND command then the maximum RU size is irrelevant as each RU passing through the network will carry one and only one record. 2. If you do not specify the WAIT option the CICS for MVS/ESA may choose to hold the records in an intermediate buffer; the contents of the buffer are passed to VTAM when the buffer is full or when the WAIT option is specified on a SEND command. Assume that the length of the intermediate buffer is 8192 bytes. If the maximum RU size is 256 then 32 RUs will be sent whereas if the maximum RU size is 4096 then 2 RUs will be sent. Each RU has to be received by Communications Manager/2. It is clear that the the overhead attributable to Communications Manager/2 processing will be reduced as the the number of RUs is reduced. I believe that data sent from CICS for MVS/ESA to CICS for OS/2 has to pass through at least one network controller. If the controller has to manage RUs of different maximum size then network delays may occur if it is operating near capacity; it's all a question of how the controller managers its internal buffers. Returning to your application ... Consider the case where CICS for MVS/ESA is holding 32 records in the intermediate buffer when the "syncpoint" call is issued. These records have to be sent to CICS for OS/2 and received by CICS for OS/2 and written to TS before all 5000 writes can be committed. This suggests that you might want to specify WAIT on every nth SEND command where n might be 5 or 10.


Page 7 of 47

4.0 Btrieve 4.1 Maximum Btrieve filesize. Question Is there a limit on the maximum size (in bytes) of a Btrieve file?

Answer The version of Btrieve shipped with CICS for OS/2 supports a maximum file size of approximately 4 GB.

4.2 Use of Btrieve 6.X in batch Question Can Btrieve V6 be used by batch applications written for V5.10?

Answer Applications previously written for Btrieve 5.10 may use the 6.X engine because the 16-bit API set remains intact and is upward compatible in this new version, with two following provisos: 



The call interface to Btrieve 6.15 requires more stack space than Btrieve 5.10, which may cause the application to trap. Relinking with a larger stack resolves the problem. If Btrieve is not active when the API is called, an environment variable (BTRINTF) must be set to indicate the location of Btrieve.EXE. Command file CICSENV.CMD will do this or it may be done explicitly as in the following example:

SET BTRINTF=/H:D:\CICS310\RUNTIME If consecutive batch programs are to be run, it is recommended that Btrieve be started explicitly, as the repeated starting and stopping of the Btrieve engine will affect performance. If a developer wishes to use the native Btrieve API they will need a copy of the 5.10 Btrieve SDK including the Programmer's Manual, and should be familiar with programming using the Btrieve API set. In Btrieve 6.X, the 16-bit APIs have been complemented with a 32-bit equivalent. The 32-bit API names are specified by adding "32" to the end of the 16-bit API name. Parameters for the 32-bit functions naturally accept 32-bit pointers and integers.


Page 8 of 47

5.0 COMMAREA and ECI 5.1 Allocating storage when using ECI Question I am using ECI to call a CICS program on MVS and am not sure how it all works under the covers. Let's say that my MVS program has a commarea that is 4000 bytes long. Do I need to do a malloc() on the PC for 4000 bytes and pass the pointer to my ECI_PARMS structure or is the space allocated for me and I receive a pointer to it? Also, when I call the remote program, I pass up about 20 bytes as an input to the host program. Do I need to have 4000 bytes allocated, or just the buffer for the 20 bytes?

Answer If your server program expects a commarea of length 4000 bytes, then your client program must provide a commarea of length 4000 bytes. Suppose you had set eci_commarea_length to 20. The CICS client would assume that the commarea was of length 20 and would send upto 20 bytes of commarea data; upto because trailing nulls (i.e. X'00') may be removed. The CICS server would allocate a 20 byte buffer, receive the commarea data, restore trailing nulls if these had been removed, and (EXEC CICS) LINK to your server program. EIBCALEN will be set to 20 on entry to your program. Summary:       

Pick maximum of how much you want to send or receive(must be less than 325000). Get space for it if you haven't got it Set pointer to it in ECI block Set length in ECI block Clear it to X'00's Place your data in it Call eci

Notes: 1. If you do not pad with nulls, then the entire commarea is transmitted - unnecessarily. You affect to overall response time of the transaction and potentially the entire network, when enough requests are flowing. If you do pad with nulls, then only the necessary information is sent, potentially something smaller than the complete commarea. 2. 32500 is the largest. In addition to your data, there is some overhead (called FMHs or Function Management Headers) that must also be sent so that CICS and the mirror can know what you want them to do.


Page 9 of 47

6.0 Data Conversion

6.1 How is Data Conversion handled? Question Can you provide some additional guidance concerning data conversion and code page support?

Answer The DPL architecture assumes that data conversion will be performed in the server (in your case CICS/ESA) provided a trigger has been received from the client (or distributed CICS). Commareas are converted provided either a conversion template has been defined or the user replaceable conversion module has been modified. Transactions and tasks are important, The DPL architecture requires a mirror task to be attached before the program can be invoked. Further more transid CPMI is used as the default trigger for data conversion. Starting with apar PN58392 on CICS/ESA 3.3, improvements to the range of data conversions supported by the host have been available. For Latin-1, conversions are supported between three ASCII code pages (437, ISO 8859-1 (IBM 819), 850) and ten EBCDIC code pages (037, 273, 277, 278, 280, 284, 285, 297, 500, 871). The apar also provides conversions for Arabic, Cyrillic, Greek, Hebrew, Latin-2, Latin-5, additional Japanese, Korean, Simplified Chinese, and Traditional Chinese. The apar added the CLINTCP and SRVERCP options on the DFHCNV macro; the CDEPAGE option is retained for compatibility. The CICS client determines the code page using platform specific functions.

ASCII-EBCDIC conversion templates Lets explore the ASCII/EBCDIC/ASCII question a moment - in the specific case for Distributed Program Link. There are four basic approaches: 1. Define the COMMAREA in the DFHCVT and let it be converted by the mirror. 2. Have the CICS OS/2 application handle all conversions. 3. Have the host CICS application handle all conversions. 4. A combo of 2 & 3 where each side converts what it is sending. Pros and cons (to mention just a few) 1. (pro) I don't need to write any conversion code -


Page 10 of 47

(con) but defining every commarea can be complex and all definitions have to go into the same table 2. (pro) Conversion is under control of the application programmer (con) Someone has to understand how to do conversions under OS/2. Don't forget to handle code pages. 3. (pro) same as #2 - plus, on a 370, translate routines can be fairly easily written in assembler. (con) I still have to be aware of code pages. Is the host program used for host activities? Also, I have to understand what can and cannot be translated. 4. basically the same as above. I can see an additional advantage for doing it within the application - even if I have to have a duplicate program for responding to host requests and OS/2 requests - in that change can be easier to manage, ie I could install new application code without having to redo the DFHCVT. But, I must also always remember that there are two sides that are dependent upon the layout of the commarea. I guess I am as much concerned with application management as anything else. And some additional considerations: 1. Translation on the workstation is fairly straightforward in that you have the WinCPTranslateString function and code page conversion tables are already defined. 2. On the host there is very little code page support and you have to write your own translation tables. The CVT macros have their own. 3. If you wish to test your programs on the workstation first, ie. use a local link rather than DPL, you will have to disable any conversion code. If you use templates then no code needs to be disabled. 4. Templates can be a problem in that the commareas have to be in a fixed format if the full power of the templates are used. Note this includes conversion of binary fields where necessary. You can use the User Exit routine on the templates for generalized variable format conversion.

6.2 Data Conversion on requests from OS/2 to MVS/ESA Question I understand that the following statements are the the "minimal set" of conversion statements required on a MVS server.

DFHCNV TYPE=INITIAL DFHCNV TYPE=FINAL END Does the use of these statements instruct the MVS system to perform ASCII to EBCIDIC conversion on all data (commarea, function shipped, etc.) received from an OS/2 system? If this is not the case; is there a way to perform this conversion on all requests from all OS/2 systems connected to the MVS server.


Page 11 of 47

Answer With The "minimum" conversion table (as you correctly described) the assertion is that there are no resources for which the systems programmer wishes to define a template. When CICS for MVS/ESA processes a request for which data conversion is required, e.g. Inbound WRITEQ TD or outbound READQTD request, then the user replaceable program DFHUCNV is invoked unless a template specifying USREXIT=NO had been defined for the resource named in the request. CICS for MVS/ESA ships a sample DFHUCNV which only processes TS requests for which templates specifying USREXIT=YES have been defined. Since DFHUCNV is user replaceable, it is possible to imagine another version of DFHUCNV that "knows" that all records in TS queues whose names begin with xxxx have the same format. (It beats having to define a template for every such queue.) The net is that, given the "minimum" conversion table and DFHUCNV as shipped, CICS for MVS/ESA will not convert any data. You can override the default action by replacing DFHUCNV. Note that if you choose so to do then you are assuming that: 1. all workstations connected to a given CICS for MVS/ESA server share a common encoding, e.g. ASCII 437, for character data and a common format, e.g. Intel, for binary data 2. DFHUCNV as replaced knows the ASCII encoding and binary format and knows the corresponding EBCDIC encoding 3. DFHUCNV has the appropriate ASCII/EBCDIC translation tables

6.3 Sample Data Conversion Table The following is a sample conversion table that describes two programs and two files, one which has an alternate index. The ECHO program handles a variable length COMMAREA that is all character. Thus a max size is specified. However, the VSAMSERV program has a very specific layout and thus shows the use of both character as well as binary fields.


Page 12 of 47

PRINT GEN TITLE 'DFHCNV - CONVERSION FOR CICS OS/2' DFHCNV TYPE=INITIAL,CDEPAGE=437 * * * Definitions for the ECHO program * * DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=ECHO,USREXIT=NO DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0000,DATATYP=CHARACTER DATALEN=32500,LAST=YES

X

* * Definition for VSAMSERV when placed on CICS/ESA * DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=VSAMSERV,USREXIT=NO DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0000,DATATYP=CHARACTER, DATALEN=2 DFHCNV TYPE=FIELD,OFFSET=0002,DATATYP=BINARY, DATALEN=2 DFHCNV TYPE=FIELD,OFFSET=0004,DATATYP=CHARACTER, DATALEN=75 DFHCNV TYPE=FIELD,OFFSET=0079,DATATYP=BINARY, DATALEN=2 DFHCNV TYPE=FIELD,OFFSET=0081,DATATYP=CHARACTER, DATALEN=50,LAST=YES

X X X X X

* * This is FILEA from the IVP * DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=FILEA,USREXIT=NO DFHCNV TYPE=KEY DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=6, X LAST=YES DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER, X DATALEN=80,LAST=YES * * Definition for TECHBASE when placed on CICS/ESA * DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=TECHBASE,USREXIT=NO DFHCNV TYPE=KEY DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=5, X LAST=YES DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER, X DATALEN=75 DFHCNV TYPE=FIELD,OFFSET=75,DATATYP=BINARY, X DATALEN=2,LAST=YES


Page 13 of 47

* * Definition for TECHALT when placed on CICS/ESA * DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=TECHALT,USREXIT=NO DFHCNV TYPE=KEY DFHCNV TYPE=FIELD,OFFSET=5,DATATYP=CHARACTER,DATALEN=15,X LAST=YES DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER, X DATALEN=75 DFHCNV TYPE=FIELD,OFFSET=75,DATATYP=BINARY, X DATALEN=2,LAST=YES * DFHCNV TYPE=FINAL END DFHCNVBA

6.4 Data conversion/bit swapping Question If I develop an application on a PC using OS/2, C-SET2 and CICS for OS/2, what kinds of data conversion/bit swapping do I have to worry about when I ship data to the host (MVS/ESA, CICS 3.3, C/370)?

Answer First of all, read the chapter on data conversion in the CICS documentation. Also, remember that you are using C (rather than COBOL), all numeric values (in addition to character values) will also have to be converted since C will expect numeric data to be in INTEL format (rather than the S370 format supported with COBOL).

6.5 Code Pages & Data Conversion Question I'm trying to understand how the code page and data conversion works between CICS. For example, If I'm using the Common client to make an ECI call into a CICS for OS/2 server, and the CICS for OS/2 program is defined as remote, so we end up doing a DPL request to a host CICS, where will automatic data conversion take place and where will I need to do DFHCNV macro etc. The client system will have it's own codepages set in config.sys and they may well be different to the codepages set in the config.sys for the CICS for OS/2 server. Now I know that it's only the servers who do conversion, so my guess is that between the common client and the CICS for OS/2 server some sort of automatic data conversion will take place. Which code pages are used ? For example, does the client send it's codepage? Does the client's codepage come from the 'model' terminal used on the terminal definition (even though the ECI request is non-terminal ?)


Page 14 of 47

So I've now assumed that the info is now in the CICS for OS/2's codepage (although I'm not sure where it's come from). Now the request is DPL'd to the host. I figure we've now got to convert the data into EBCDIC so I need to do a DFHCNV macro on CICS/ESA ... In here I set what I think the CICS for OS/2 code page is and what the CICS/ESA code page is. What is the CICS/ESA code page? There are no SIT settings for the hosts code page? So do I just decide for myself ? I'm not doing any transaction routing here, so I figure that the Partner Code Page in my TCS is not important. Also because I'm sending UK pound signs in the commarea I guess I'll need to set up a user conversion table in my host DFHCNV....

Answer 1. Unless you want life to be very complicated, don't mix codepages on the PC systems. 2. When the ECI is sent to the host, there and only there will conversion take place based on the DFHCVT and only when the CVMI mirror is used. No conversion will take place on the CICS for OS/2 gateway. 3. The current DFHCVT assumes 037 for the host code page and 437 for the PC. At some point in the future, there will be the ability to have multiple and different code pages for CICS for OS/2 much the same as is current for CICS for AIX. APAR PN58392 on CICS/ESA 3.3 has made some improvements to the range of data conversions supported by the host. For Latin-1, conversions are supported between three ASCII code pages (437, ISO 8859-1 (IBM 819), 850) and ten EBCDIC code pages (037, 273, 277, 278, 280, 284, 285, 297, 500, 871). The APAR also provides conversions for Arabic, Cyrillic, Greek, Hebrew, Latin-2, Latin-5, additional Japanese, Korean, Simplified Chinese, and Traditional Chinese. You'll have to use the CLINTCP and SRVERCP options on the DFHCNV macro; the CDEPAGE option is retained for compatibility. In the above case, the user should change the DFHCNV macros to specify CLINTCP=437:850, SRVERCP=285; that way he should be able to preserve the pound signs (despite the EC talk of a common currency!).

Question It would be nice not to have different codepages on the CICS Client machines, but the CICS for OS/2 server is part of a service bureau and all of the clients are via dial-ups in many different companies, so it's quite tricky to say you must use this codepage when you install OS/2. Perhaps the thing I am missing is where the codepages come from. Does the client use the codepage of the OS/2 system, or is it something the application decides ? If we take my previous example, because the ECI call is being sent directly to the host via DPL, the 'client' code page (to the host) is that of the Common Clients machine and not that of the CICS for OS/2 server.


Page 15 of 47

Answer The CICS client determines the code page using platform specific functions. As the CICS OS/2 intermediate server does not propagate the code page from the client to the host server you will need to indulge in some crafty configuration. Consider a set of clients (either ASCII 437 or ASCII 850) invoking programs on a set of hosts (either EBCDIC 037 or EBCDIC 285) :1. You will need 4 host servers each having a different combination of CLINTCP and SRVERCP parameters on the DFHCNV macro/table a. b. c. d.

CLINTCP=437, CLINTCP=437, CLINTCP=850, CLINTCP=850,

SRVERCP=037 SRVERCP=285 SRVERCP=037 SRVERCP=285

2. You will need one or more intermediate servers connected to each host server. Each intermediate server "supports" a particular ASCII/EBCDIC combination, e.g. 850/285 3. You will need to connect each client to the appropriate intermediate server.


Page 16 of 47

7.0 Debugging 7.1 What is an Abend AZI6 from SRVTIME???? Question We have installed the various components of the Java gateway and are testing. In running the supplied applets, we have seen RC=-6 on our logs. In the traces, we see an abend with an RC=AZI6. Can someone give us some clues here on how to address this? In SRVTIME, we commented out the commands in the send-msg section. Could the exit cause the exec cics return to not be executed? The trace also indicates a CommArea of 1 byte returned when we sent up 16 x'2D' as required.

Answer Looking at the cobol version of SRVTIME, it is checking for a commarea that is at least 18 bytes long. My suggestion would be to send a commarea slightly longer and put a character (or several) starting a position 19. You should then see these go up and come back. The AZI6 says that the application on the other side (ie SRVTIME) has abended. Check for the abend code in the host region - when you get the AZI6. Also, make sure that the DFHCNV has been defined on the host CICS, even if you do not plan on using it. The following types of CICS resources can be identified in the conversion table:

FC IC TD TS PC

... ... ... ... ...

File Control Interval Control Transient Data Temporary Storage Program Control - ie the COMMAREA for Distributed Program Link requests

Some simple guidelines for COMMAREAs can make life a bit easier: 1. Always initialize the COMMAREA to LOW-VALUES (Binary Zeros) since binary data will be compressed, starting at the end before transmission. 2. Always use a data structure definition to move information into the COMMAREA, especially when using COBOL 3. Never place addresses into the COMMAREA. The other side does not have the ability to branch to code in your system. 4. Define the area such that the most used information appears early in the structure. 5. Do your best to have the data stored in character format, then the conversion table is very simple. Here's my version of the conversion template for program SRVTIME


Page 17 of 47

* * THIS IS FOR CICS CLIENT PGM SRVTIME * DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=SRVTIME,USREXIT=NO DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=CHARACTER,DATALEN=1 DFHCNV TYPE=FIELD,OFFSET=9,DATATYP=CHARACTER,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=17,DATATYP=CHARACTER,DATALEN=1 DFHCNV TYPE=FIELD,OFFSET=19,DATATYP=CHARACTER,DATALEN=32749 DFHCNV TYPE=FINAL END DFHCNVBA Notes: 1. I'm assuming that rest-commarea contains character data that requires conversion. I'm also assuming SBCS encodings. 2. If lowval really does contain X'00' then you could omit the field definition. If not then DATAYP=CHARACTER provides a more accurate representation of the COBOL definition. 3. CICS treats DATALEN=32749 as specifying the maximum length of the data to be converted. If the length of the commarea was 22 then CICS would convert 6 bytes of character data 4. You have a problem with the commarea as defined in the linkage section. The length of rest-commarea can not exceed 32751 given API limits and should not exceed 32484 given recommendations for commareas passed via DPL. The DFHCNV macros are described in

CICS Family: Communicating from CICS on System/390 Document Number SC33-1697-01 Assembly of the DFHCNV table is identical to that for other macro defined resource macros; refer to

CICS for MVS/ESA System Definition Guide Version 4 Release 1 Document Number SC33-1164-01 ... or equivalent ...


Page 18 of 47

8.0 Gateway 8.1 CICS OS/2 Gateway Question What hardware is required to run 1500 clients through a single gateway. I'd prefer a pentium with 4 MPU adapters. Would this require multiple processors as well.

Answer With CICS for OS/2, there is a limit of 254 clients per NetBIOS adapter and a limit of 999 TCP/IP connected clients (or servers). The upstream links are another question. A client can have multiple units of work multiplexed over one connection - e.g. Multiple 3270 type terminals in OS/2 or Windows, or multiple async ECI calls, or multithreaded synchronous ECI calls. Each active unit of work uses one local task on the CICS for OS/2 machine for the duration of that work. (Which is why pseudo-conversation programming is important. There is no point in having more sessions over a connection than there are local tasks, because normally there is only one session per active transaction to any remote system. (DTP is the possible exception). The number of local tasks is limited to 99, though system memory and CPU limits this to 20-40 practically. The advantage of a CICS for OS/2 gateway is that it multiplexes all the client connections over one connection to the mainframe with a lower number of sessions. If more clients want to do something simulatenously than there are tasks or sessions, then the clients will block. Normally a terminal transaction is only active for a very short time however - the think time waiting for a terminal input does not use a task or session if the transaction is pseudoconversational. While there are other pluses using a CICS OS/2 gateway, the main one is LU reduction in the network since the clients come up to the mainframe over parallel sessions rather than multiple single LU sessions. This is a positive benefit for NCP, VTAM and host CICS. Also will allow you to re-route requests to other address spaces with a trivial bit of code, thus increasing availability. There are some simple tuning factors in CICS for OS/2: 1. FAAMIR.DLL marked as resident in PPT 2. CPMI priority upped in PCT entry 3. Up the default system priority in the SIT 4. Clear the commarea to nulls before filling, both on the originating client and on the RETURN from CICS mainframe.


Page 19 of 47

5. Watch for paging? if so get some memory...anyway if using FAT pre-allocate the swap file (3rd parameter in CONFIS.SYS) 6. What is priority of CPMI on mainframe, if if isnt greater than other transactions in the CICS system, it should be....


Page 20 of 47

9.0 General Questions about CICS for OS/2 9.1 Avoiding when trapping Question Does anybody know a way to prevent CICS OS/2 from putting out these two buttons with when a transaction is trapping. When you run a CICS OS/2 remotely and have a couple of hundred kilometers between yourself and the pushbutton, you lose some of the advantages of remote operations, which is such an advantage with CICS OS/2.

Answer Start CICS with the /Q option for unattended operation. E.g.

CICSRUN /Q /Q (note the two /Q as Rexx steals the first one)

9.2 Maximum length of the COMMAREA Question Could someone tell me the maximum COMMAREA size in CICS OS/2?

Answer 1. The absolute limit is 32k - the commarea length is held in a half word binary field. 2. When using COMMAREA with Distributed Program Link from CICS for OS/2, you must not go above 32,500 since: a. VTAM also has a 32k limit on a physical buffer size b. along with the commarea, we must ship an FMH5 and FMH43 3. CICS/ESA's documentation recommends 24k as a good general value, but that is not the maximum. Personally, I normally suggest a self-imposed max of 30k, but I also question the design of commareas that large. What concerns me is that the customer have an understanding of the effect on the network (line traffic/utilization, NCP buffers and control blocks, VTAM buffer pools, and so on) of suddenly adding a significant number of very large data buffers, especially when a 3270 network typically only uses 2 to 3k buffers (and those are large for 3270 datastreams). As a final comment, CICS for OS/2 and the IBM CICS Clients will remove trailing nulls from the commarea before sending to help the situation.


Page 21 of 47

9.3 Maximum number of tasks and minimum free tasks Question The CICS for OS/2 Version 3.0 Performance manual, section "2.4 Major CICS for OS/2 parameters" states the following: "Note that the number of non-facility processes (named @02@ and @03@) matches the value specified in Minimum free tasks. If more requests for transaction initiations enter the system than can be handled by these two processes, CICS for OS/2 can start up to three more processes, giving a maximum of six (the value specified in Maximum number of tasks). Currently, the stimuli which will activate this are: ... " The stimuli do not include ECI requests. Is this a documentation omission or do I need to have "Minimum free tasks" set such that I will always have a CICS OS/2 process available to satisfy my ECI requests, upto a predetermined maximum? If this is so, what is the OS/2 overhead of having a large number of non-facility processes?

Answer First, it is correct, ECI requests will not cause additional back-ground tasks to be initiated. Hence you need to set the Minimum number of Free Tasks to the enable the total number of concurrent requests you wish to handle. Now comes the fun. How high to set the number? For this you need to consider resource usage for CICS, OS/2 and your transactions. A back-ground task which is idle has a very small footprint, as most of its memory requirements are swapped out. Also, an idle task will not consume any processor resource. So the first consideration is how much memory is there on the system, and how much swapping might you cause OS/2 to perform. Some swapping is OK, but large amounts are not productive. Next consideration is the transaction resources. If the transactions compete against each other, for data resources, memory or processor usage, then it may be better to let CICS queue the requests rather then schedule many requests concurrently, and have them spend all their time competing for resource. While I have known users to have up to forty back-ground tasks, these have generally been on systems which are not memory constrained and the transaction requirements have been modest. Unfortunately, there is no magic number. If you are running the system with a number of client attached systems, remember that extended ECI conversations keep the back-ground task for the duration of the transaction. They are the equivalent of conversational transactions. But, if they include user 'Think time' then swapping out the waiting task may be a good option. Another consideration is to disable the desk-top terminal emulators. Each terminal requires a dedicated task, and will consume small amounts of processor time. Start the system with the /N option, and use the 'Start Terminal' icon to start a terminal if you require one on the desk top. This will start a new back-ground task! Therefore ensure the 'Maximum number of tasks' is greater than the number specified for 'Minimum free tasks'. Finally, the PA2 set of transactions is invaluable for monitoring the usage of system resources. Start the system with the /P-PA option. Capturing the output and analyzing it will give you a very good guide as to where to set the numbers and what the effect is on the system.


Page 22 of 47

9.4 How to Determine if a program(process) is running under CICS for OS/2 Question First, is there a method for a CICS transaction to determine which CICS it is running under? Second, is there a way to find out from within a BATCH program whether that program is executing under the CICS for OS/2 environment? On MVS, we have an assembler routine which checks to see if the executing program is 'DFHSIP'(?) to see if it is running under CICS/MVS. How could this be done for OS/2 and CICS for OS/2?

Answer For the first question: Just look at the OPSYS value returned from the EXEC CICS INQUIRE SYSTEM. For example, OPSYS returns 'P' for CICS for OS/2, '4' for CICS for OS/400, and 'X' for CICS for MVS/ESA. RELEASE will also tell you the CICS release level. For the second question: I expect that you have a program which has no CICS commands, is not put through the translator, but can be called as a subroutine by batch and CICS programs. If so, a suggestion: DosGetInfoSeg: one of things this returns is a module handle. DosGetModName: using the above module handle, will return the address of a buffer containing the fully qualified drive, path, filename, and extension of the module at the top, which is FAAOTPTK.EXE or DLL. Note that use of techniques such as this will make the program operating system dependent, but in this case what is needed is an equivalent technique under OS/2 for something which already works under MVS or VSE, presumably.

9.5 MAX tasks vs Minimum FREE tasks Question We have some questions concerning the MAX tasks and FREE tasks specifications in the SIT: It appears that an External Transaction Initiation (ETI) request with USAGE=3270 and TERMID=DFLT requires one FREE task and occupies the task until CICS for OS/2 returns to the ETI program. The task is occupied across transactions. For example, with MAX=3 FREE=1, we can run one such ETI program at a time. Starting a TR emulator session also requires one FREE task, but if one is available, then apparently the task is not tied up across transactions. Any number of TR emulators can be run against the server. The client's 3270 sessions appear to be 'sharing' a FREE task. For example, we can run 4 client terminal sessions when MAX=3 FREE=1 is


Page 23 of 47

specified. Such a FREE task can also be 'shared' across clients, e.g. We have serviced one emulator session on client 1 and another emulator session on client 2, with just one FREE task in the SIT. We are trying to find recommendations as to how many tasks to specify for how many clients, TR emulator sessions, native 3270 emulator sessions (ETI/non-facility or facility), and ECI programs. Are our observations correct?

Answer Let me try and clarify the usage of Maximum and Free task. Maximum tasks is, as its name suggests, the maximum number of task available to CICS for OS/2. Minimum free tasks is the number of non-facility tasks which CICS will attempt to maintain within the limits of maximum tasks. A pre-defined terminal, such as a PM, fullscreen or 3151 communications port will require the dedicated use of a task. An ETI request directed to a terminal (Usage=3270) will require a dedicated task for the duration of the ETI session. The session is terminated by the EXIT transaction. All other types of transactions will require a task for the duration of a transaction. This will include transactions initiated from PNA or Client attached terminals, inbound communication requests, ECI and simple non-facility type transactions. Now an example: 

Define maximum tasks as 6.



Define minimum free tasks as 2.



Define two PM terminals - V123 and V124.

When CICS for OS/2 is started it will install two tasks which will be used exclusively by V123 and V124. In addition, it will start two tasks which are available as non-facility tasks and candidates to be taken for any other transaction. CICS will have the capability to install another two tasks (6 (The maximum) - 2 terminals - 2 (free tasks)). If you now request an ETI transaction with usage=NONF the transaction will run on one of the non-facility tasks. If, however, you specify usage=3270 the system will install a terminal and convert one of the non-facility tasks into a dedicated facility task. As there will be only one free task, and we have two tasks not initiated, CICS will start another non-facility task to maintain the minimum of two That broadly is how the tasks are used. Some points to consider: 



You may never have more tasks than the defined maximum. Tasks may be released when the number of free tasks exceeds the minimum.



PNA attached terminals may cause tasks to be initiated.



Client attached terminals do not cause tasks to be initiated.



Surrogate terminals do not cause tasks to be initiated.



The number of concurrent transactions is limited by the number of tasks active.



Pre-defined terminals are installed before non-facility tasks and if the Maximum tasks is too small, the number specified for minimum free tasks will not be installed. Initialization will warn of this condition.




Page 24 of 47

Pre-defined terminals may be released and the task will than revert to being a non-facility and may hence be acquired to be another terminal.

Client emulators will attach to a server task on initiation (in order to install a terminal definition) and when a transaction is running on that emulator. At all other times (when not in transaction) the emulator will not use a server task. To determine how many non-facility tasks are required on the server you need to calculate the following: 









The rate/frequency of emulator installations. If 10 client emulators are initiated on the LAN at the same time and there are only 2 non-facilities running, then the last 8 emulators will wait on XSYSTEM until a nonfacility is free. The rate/frequency of emulator transactions. If you apply the same scenario as above, the result would be the same. The type of transaction being run. Conversational transactions are NOT to be recommended! For obvious reasons these would tie up a non- facility to an emulator. Be trendy and go for pseudo-conversational. Client ECI facility usage. Take into consideration the server task requirements, such as local terminals, ETI 3270 usage and local server application usage.

In order to calculate the number of running non-facilities required just for client emulators I personally would estimate the average server transaction rate/second (for just the client emulators) and set the number to this plus 1 for growth.

9.6 CICS for OS/2 V2 Durability A 1993 Durability Test Over the past 8 days (less two hours) I've been running a "durability" test. I'm not sure now if I was testing CICS for OS/2 V2 - or my building. But, within the last 30 minutes, my server passed 10 million transactions. This is a PS/2 M95 - 50mz - 40meg - on a lab LAN, bridged to the rest of the LAN, running 16mb in the lab and 4bm on the other side of the bridge. I've got five PS/2s, two Model 90s, a Model 95, and two Model 80s in the lab as well as another Model 95 on the other side of the bridge running the client code (yes, I know that's an overkill, but somebody has to have fun, so might as well be me). Each of the clients is running eight copies of the same client application, so I have a total of 48 clients. Also running on the server, is SPM/2 (and TCP/IP - but thats another application). Each requestor is running the same application which sends a 50 byte commarea in and gets a 50 byte back. It captures and reports the time to do this as well as displays the commarea received, waits for two seconds and does it again. At the server, there is an echo program that places the task counter in the commarea and returns. As part of the monitoring process, I have a spy program that opens a file, records information, and closes it every few seconds. At the server, I'm running 12 non-facility tasks and V123. The backend ECHO program is resident. OS/2 is NOT memory constrained, ie there is no paging activity. The machine has been running at a very steady state for the entire test. During the first several days the avg response time at a client was 1.33 seconds. Due to my playing around on the server (looking at memory, etc) over time the response time has changed to 1.57 (for the last 3 days at least).


Page 25 of 47

Now, what does this tell us? Well, for one thing that once you reach 10m trans, the transaction counter rolls and keeps on going. On a more serious note, it does show some minimum levels for client to server interactions.


Page 26 of 47

10.0 Intersystem Communications 10.1 Private Mirror: What it is and how to use it First of all, it is important to remember that the ECI is a request to execute a user-program and not a usertransaction. After reaching the CICS system, it becomes a LINK to the invoked program with the data being passed in a COMMAREA. There is no terminal associated with the task, therefore a program is not allowed to issue any terminal-oriented commands (such as SEND). If an ECI request comes into CICS for OS/2 and specifies a PROGRAM (not a transaction ID) which has been defined as remote, CICS for OS/2 will function ship the LINK (also known as DPL) to the target CICS system. The rules of DPL state that a DPL server program cannot issue any terminal-oriented commands. An option in the ECI call parameter list is a transaction ID. Prior to CSD1 for the CICS Clients, this transaction ID is used as the TRANID of the mirror as well as being in the EIB. One of the optional changes in CSD1 (documented in the readme) is the ability to use the normal mirror name but still have the specified transaction ID appear in the EIB. (Starting with CICS for OS/2 V2, such a transaction ID also has to be defined in the PCT pointing to the mirror.) As such, it is used in security checking and may be passed to a connected CICS system if a DPL request is sent. The transaction code is not used to invoke the background transaction in the same way that a transaction code entered by a terminal user or one specified in a START command would be used. It is possible to issue an ECI call to CICS for OS/2 specifying a transaction code and a program - where the program being invoked is not the initial program specified in the PCT entry for the named transaction. If the ECI request is transformed into a DPL request, the server CICS system will attach a mirror transaction (CPMI), but place the specified transaction code in the EIB. This way, any calls to DB2 will use the plan associated with the designated transaction call. In CICS for OS/2, the PPT includes TRANSID as well as SYSID. When a program is defined as remote, if a TRANSID is specified in the local PPT, that transid will be used instead of the CICS-supplied mirror transaction within the DPL server region. This transaction code must be defined within the DPL server region with the same parameters as those on the CICS-supplied mirror transaction (CPMI). When using such a private mirror, the transid in the client PPT system will be used both for transaction attach and the EIB. Again, remember that the host CICS program is being invoked due to DPL which uses the function-shipping protocols. Transaction routing is not involved in any way.

Details on a Private Mirror When DPL was added to host CICS in CICS/ESA V3.3, the function was enhanced over that initially provided in CICS for OS/2. One of the enhancements was to allow the programmer to specify TRANSID as one of the options on the LINK command - or to allow TRANSID to be specified as one of the remote operands on a PROGRAM definition in RDO. If a LINK command is issued for a remote program and TRANSID is not specified in either the LINK command or the RDO definition of the program, then the DPL server region will attach the default mirror transaction (CPMI, CSMI, etc.). If TRANSID is specified either on the LINK command or in the RDO definition of the program, then the DPL server region will attach the named TRANSID.


Page 27 of 47

This named TRANSID must be defined in the DPL server region with the same characteristics as the mirror transaction for which it is substituting. I have termed this TRANSID which is named on the LINK command as the "private" mirror.

Example: DPL client is CICS for OS/2; DPL server is CICS for MVS; default mirror is CPMI; private mirror transaction code is to be MYRR. To define a private mirror transaction code in CICS for MVS, copy the definition of CPMI, giving it a transaction code of MYRR. Note: The PROGRAM name for the ASCII mirror is different in later host CICS versions.

TRANSACTION(MYRR) GROUP(LYCCOSV) PROGRAM(DFHMIRVM) TWASIZE(0) PARTITIONSET() STATUS(ENABLED)

PROFILE(DFHCICSA) PRIMEDSIZE(0)

REMOTE -ATTRIBUTES REMOTESYSTEM() REMOTENAME() TRPROF() LOCALQ() SCHEDULING PRIORITY(1) TCLASS(NO) ALIASES TASKREQ() XTRANID() RECOVERY DTIMOUT(NO) INDOUBT(BACKOUT) RESTART(NO) SPURGE(NO) TPURGE(YES) DUMP(YES) TRACE(YES) SECURITY EXTSEC(NO) TRANSEC(1) RSL(0) RSLC(NO) The two most important things to get right in this definition are PROGRAM(DFHMIRVM) and PROFILE(DFHCICSA). To use the private mirror transaction, the CICS for OS/2 program would issue a LINK command such as:

EXEC CICS LINK PROGRAM(LINKEDTO) TRANSID(MYRR) COMMAREA(PLACE-I-PUT-THE-DATA) LENGTH(65) END-EXEC. Now, why would someone want to use a private mirror? Some customers want to collect statistics or monitoring data (for accounting or performance analysis) about the use of DPL. If the default mirror transaction code is being used, DPL usage will be lumped together with all the function-shipping requests in the transaction statistics. After implementing one or more private mirror transaction codes, the statistics and monitoring records can be more useful. Some customers are using private mirror transaction codes to allow them to continue to use the transaction level security which is in place for local transactions - and not have to implement resource level checking just to restrict the program links. Other transaction definition parameters may be altered on the private mirror transaction code - TWASIZE, PRIORITY, TCLASS, etc. to give the applications and systems programmers more control over the application environment.


Page 28 of 47

10.2 Issuing SYNCPOINT in a DPL program Question Can a CICS/ESA 3.3 application, invoked via a DPL request, use the EXEC CICS SYNCPOINT? Before moving to CICS/ESA 3.3, these programs worked. He is receiving an error message: CICS for OS/2 cannot issue SYNCPOINT in a DPL program.

Answer This has happened because CICS for MVS/ESA 3.3 does not allow certain commands to be used. In prior versions, it was not recommended, but also not checked. One of the banned commands is SYNCPOINT, unless the LINK command has the SYNCONRETURN option specified. If the SYNCONRETURN option is specified then the linked-to program can take as many syncpoints as it wants; that CICS will also take one for good measure. The synclevel of the conversation is always 1. In this case, the unit-of-work is divided between the front-end application and the back-end and are totally separate. If the SYNCONRETURN option is omitted then the linked-to program must not take any syncpoint. Consider the implications for DPL ... the mirror would become the syncpoint coordinator and you would observe some very interesting phenomena especially if the synclevel of the conversation were to be changed from 1 to 2. CICS has added code to police a restriction that has been documented since DPL was first implemented. Refer to SC33-0736-0, Communicating with CICS OS/2; page 5 describes the restrictions on programs linked by DPL, in particular the 6th "commandment". The policing code was added to CICS for MVS/ESA 3.3 and to CICS for VSE 2.2.

10.3 Value of EIBTRMID Question I have a CICS client talking to a CICS for OS/2 server via an ECI call which invokes a local server program. To what value is EIBTRMID set when the server program is in control? Is the value of EIBTRMID based on the value generated by autoinstall?

Answer The EIBTRMID for a DPL server program (which is what also happens with an ECI call) is the name of the principal facility for the task, i.e. the name of the session. Session names are allocated dynamically as client systems are autoinstalled.


Page 29 of 47

10.4 Memory Requirements for host CICS Sessions and Connection Information The question concerning memory requirements for LU6.2 definitions comes up on a fairly regular basis. Depending upon the level of your host CICS, the memory for these definitions may be allocated below the 16meg line (ie prior to CICS/ESA 3.3) or above (for 3.3 and above). Therefore, depending upon your host CICS, as well the ability of the paging subsystems, and so on, you may want to approach the "unbridled" use of LU6.2 sessions and connections. You may also find that the concept of an SOR (system owning region) to be attractive for these LU6.2 connections. Judicial use of CICS for OS/2 systems running as small TOS (Terminal Owning Systems) can also be a help to keeping this to a manageable level. NOTE: The following values may not be exact on your host CICS. However, they can be used for estimates.

Parallel session devices: ZCTCTSE system entry for the connection

192

ZCTCTME mode entry for the session services manager 128 ZCTCTTEL ZCTCNIBD ZCBMSEXT ZCLUCEXT

terminal entry NIB descriptor BMS extension LU62 extension

for " " "

the " " "

" " " "

" " " "

" " " "

448 96 48 144

ZCTCTME mode entry for user application sessions

128

ZCTCTTEL ZCTCNIBD ZCBMSEXT ZCLUCEXT

448 96 48 144

terminal entry NIB descriptor BMS extension LU62 extension

for " " "

user " " "

" " " "

" " " "

The net result for parallel sessions is: - 1792 bytes for the system entry, mode entry and 2 sessions for the session services manager. - 128 bytes for each mode entry - 736 for each defined session Single session definition: ZCTCTSE system entry for the connection ZCTCTME mode entry for user application session ZCTCTTEL terminal entry for user " " ZCTCNIBD NIB descriptor " " " " ZCBMSEXT BMS extension " " " " ZCLUCEXT LU62 extension " " " " For a total of 1056 per connection/session

192 128 448 96 48 144


Page 30 of 47

While a transaction is active, send and receive buffers are needed. The send buffer is as many send RUs (defined by SENDSIZE) that will fit in 4060 bytes plus 36. Figure on 4096. The receive buffer is 2 times the RECEIVESIZE. To get this data I used AUX trace and printed it using DFHTUP, with the following parameters:

FULL,TYPETR=SM0301 This will give the domain getmains. The subpool is in the optional data 2 field which is translated on the right side of the output. This summary identified the component storage areas required for the "local" definition of LU6.2 devices within CICS. We are still working on a determination of the subset of this storage that is required for a surrogate definition for a remote LU6.2 device.

LU 6.2 Session and memory consumption for Communications Manager/2 Network Node Memory Guidelines (ES) APPC/APPN Overhead = 1.8 MB Session Overhead = .007 MB / Session End Node Support Overhead = .03 MB / End Node Example: 32 ENs with 2 sessions each 1.8 MB + 32 * (.03 + 2 *(.007)) MB = 3.2MB End Node Memory Guidelines (ES) APPC/APPN Overhead = 1.8 MB Session Overhead = .007 MB / Session Example: EN with 4 sessions 1.8 MB + (4 * .007) MB = 1.83 MB About 7K/Active Session; Each NN uses about 30K/EN supported. The session information is average; it really depends on the RU size, and the pacing window size.

Send and Receive Buffers Here's some more information concerning the send and receive buffers that are allocated by CICS/390 for the duration of a conversation. For CICS/MVS the send buffer and the receive buffer are mapped onto the same block of storage which is typically 4096 bytes long. Note that the storage allocated must be capable of holding at least one send RU or two receive RUs. The storage is allocated below the 16M line. For CICS/ESA 3.2 and later releases the block of storage is typically 8192 bytes long and is logically divided into two parts. The receive buffer is mapped onto both parts whilst the send buffer is mapped onto the latter part; the length of the first part is that of a receive RU. The storage is allocated above the 16M line.


Page 31 of 47

11.0 Inter-System Communications

11.1 Is Two Phase Commit Supported? Question Does CICS for OS/2 Support a 2-phase commit process? For example, let's take a CICS for OS/2 program which issues a syncpoint request. Prior to the syncpoint, the program has 1. Issued a DPL request to CICSESA1 (NOSYNCONRETURN) 2. Issued a function ship write request to CICSESA2 3. Updated a local DB2/2 table Now the CICS for OS/2 system will be the 'initiator' here. CICS for OS/2 will then in turn send a 'COMMIT' flow to CICSESA1. If CICSESA2 replies 'COMMITTED' then CICS for OS/2 will send a 'COMMIT' to CICSESA2. If CICSESA2 replies 'ROLLEDBACK' then CICS for OS/2 will send a 'ROLLBACK' to DB2/2. The CICS for OS/2 CG says that an 'inconsistency message is logged'. What response is returned from the EXEC CICS SYNCPOINT command in this situation? (Or is the transaction abended?)

Answer Since "2 Phase Commit" is defined (among other things) as the ability to both receive and send a Prepare to Commit, then the answer for CICS for OS/2 must be No. Note that the base Communications Manager support was made available for the first time on 12 March 1996 with the announcement of IBM Communications Server for OS/2 Warp, Version 4. Versions of Communications Manager prior to this did not support two phase commit. Keep in mind that 2 phase commit does require additional data flows at syncpoint time, which can add to the life of a transaction. In the example that you cited, when the second system says that the commit has failed then the CICS for OS/2 transaction will be abended. The synclevel for DPL and function shipping is determined as follows: 1. If DPL when SYNCONRETURN specified ... use SL(1) 2. If DPL when SYNCONRETURN omitted or FS ... use SL(2) provided that both partners support SL(2) and provided the connection between partners is a parallel session. Case (1) does not require syncpoint coordination.


Page 32 of 47

In case (2) 1. If SL(2) is used then standard APPC architected syncpoint flows are used 2. If SL(1) is used then CICS architected flows are used. Basically the DPL/FS initiator sends "COMMIT" and expects to receive either "COMMITTED" or ROLLEDBACK"; note that the initiator may receive other responses, for example, if a session outage were to occur. CICS/390 commits "SL(2)" any local resources before attempting to commit "SL(1)" resources; strictly CICS/390 propogates the result of the commit. CICS for OS/2 selects one of the "SL(1)" resources and commits that. The outcome (i.e. committed or rolledback) is applied to the other "SL(1)" and to local resources ... and ... should be fed back as the response to the SYNCPOINT command.

11.2 Connection Problems between CICS/ESA and CICS for OS/2 Question We have a problem starting sessions from CICS/ESA to CICS for OS/2. We can start with CICS for OS/2 to CICS/ESA without any problem and the sessions starts when needed. From CICS/ESA no sessions can be started. I get a CICS message for all sessions that are Ins Rel Cre saying:

DFHZC4931 E 11/12/93 10:16:31 DSSZCIC2 -995 CSNE VTAM detected bad logmode name. VTAM RETURN CODE 144B ((1) Module name: DFHZLEX) DFHZC3437 I 11/12/93 10:16:31 DSSZCIC2 -995 CSNE Node FS1SCBL0 action taken: NOCREATE CLSDST ABTASK ABSEND ABRECV ((1) Module name: DFHZNAC) DFHZC3462 I 11/12/93 10:16:31 DSSZCIC2 -995 CSNE Node FS1SCBL0 session terminated. ((2) Module name: DFHZCLS) The logmode mentioned in Communications Manager/2 is the same as in SESSION-definition. The session I started from CICS for OS/2 is used from CICS/ESA when freed (I did hold it with a conversational transaction). All sessions that tried to be started from CICS/ESA was set Out Rel


Page 33 of 47

Answer It certainly appears that there is something wrong with your definitions. We can keep guessing or you can take some time and do the following: 1. Gather up the following definitions for review: 

The CICS/ESA Sessions/Connection Definition for this LU6.2 link



The VTAM definitions - including PU and LU definitions as well as the MODEENT



The Communications Manager/2 NDF file



The CICS for OS/2 TCS definitions

2. Try to isolate on which side of the link the problem occurs. Run a Communication Manager/2 trace on the PC and then perform your tests. Check the trace to see if anything is flowing from the host to the PC. 3. Where to look for possible errors Check: a. The spelling in all names b. For messages in the CICS/ESA log c. On Communications Manager/2, from Subsystem Management, check that the LINK is active. d. Use the CICS/ESA manual "Communicating with CICS OS/2" to check the connection/session etc. are correct. e. From Communications Manager/2 trace, locate the flow of the communication. Select APPC and IBMTRNET. f. Check that the LU6.2 logmode definition, CICS APPLID for APPC definitions etc. are correct. Don't take this for granted. g. Check that things like CPMI, CVMI, etc on CICS for OS/2 are defined. Check that the corresponding definitions on CICS/ESA are installed and active. h. Use CEMT (on the host) to acquire the connection manually. Look for error messages. There usually turns out to be a mismatch in names, a name omitted, or the same name not used every place.

Solution Found The problem is solved. The following question provided the solution. "Did you ensure that the LOGMODE defined in SESSION and Communications Manager/2 is also defined in both the CICS/ESA APPLID and the Workstation LU? I had a similar problem the other way round, and solved it by adding the Logmode to the MODETAB for CICS/ESA." What I found out was that the logmode specified for my PWS independent LU had an other name, so the message I got was correct. When I specified that logmode-name in my CICS for OS/2-session-definition in CICS/ESA (I didn't touch the rest where logmode-name was specified) I could contact CICS for OS/2 but suddenly I couldn't connect the other way. It could be a matter of number of session and winners I don't know. Now I have the same logmode-name in TCS for CICS/ESA, Communications Manger/2, VTAM-PWS, VTAM-CICS/ESA and RDO-def of CICS for OS/2 session. And it works!


Page 34 of 47

11.3 Configuration Example for CICS for OS/2 to CICS/390 Information The following is a sample of the host and workstation definitions for a CICS/ESA and CICS for OS/2 network. The configuration consists of two OS/2 workstations on a token ring network, 3745 with TIC, ACF/VTAM, and CICS/ESA.

-------------------------: ---------: : : CICSU7 : : ------------------: :--------: : : : : : : : CICSU8 : : : CICS :--------: CICS :---------: :--------: : : OS/2 : NETB : OS/2 : LU6.2 : : CICSU9 : : : WS01 : : WS02 : : ---------: ------------------: : : MVS/ESA : --------------------------

VTAM Definitions ======================================================================== VTAM definitions SYS1.VTAMLST(CICSSW1) ======================================================================== * THIS IS THE SWNET FOR THE 3745 TOKEN RING CICS SUPPORT FOR COMPTON * CICSSW1 VBUILD TYPE=SWNET CICPU40 PU ADDR=04,SPAN=(SPAN7), X MODETAB=DSVMODE, IDBLK=05D, IDNUM=45509, MAXDATA=1033, MAXOUT=7,SSCPFM=USSSCS, PACING=0,VPACING=2, PUTYPE=2,ISTATUS=ACTIVE

X X X X X X

CIC40LU2 LU LOCADDR=2,SPAN=(SPAN7),DLOGMOD=T32XX3,LOGAPPL=SLSAMON CIC40LU3 LU LOCADDR=3,SPAN=(SPAN7),DLOGMOD=T32XX3,LOGAPPL=SLSAMON CIC40LU4 LU LOCADDR=4,SPAN=(SPAN7),DLOGMOD=T32XX3,LOGAPPL=SLSAMON CIC40LU5 LU LOCADDR=5,SPAN=(SPAN7),DLOGMOD=M6APPC CIC40LU6 LU LOCADDR=6,SPAN=(SPAN7),DLOGMOD=M6APPC CIC40LU0 LU LOCADDR=0,SPAN=(SPAN7),DLOGMOD=LU62APPC,RESSCB=10

VTAM Definitions


Page 35 of 47

======================================================================= SYS1.VTAMLST(ATCSTR00) ======================================================================= HOSTSA=1,SSCPID=01,MAXSUBA=63,CONFIG=00, X SSCPNAME=CDRM01,NETID=USIBMSL, X NOPROMPT,DLRTCB=32,SUPP=NOSUP,PPOLOG=YES, X LPBUF=(120,,0,,60,60), LARGE GENERAL PURPOSE - PAGEABLE X LFBUF=(96,,0,,24,10), LARGE GENERAL PURPOSE FIXED X WPBUF=(150,,0,,25,10), DEVICE CONTROL - PAGEABLE X SFBUF=(128,,0,,32,10), SMALL GENERAL PURPOSE - FIXED X CRPLBUF=(160,,13,,80,80), RPL-COPY - PAGEABLE X IOBUF=(2000,240,12,,32,32) I/O BUFFERS - FIXED (NP & PP BUF ======================================================================= excerpt from LOGMODE table ======================================================================= * Logmode for independent LU6.2 sessions LU62APPC MODEENT LOGMODE=LU62APPC,FMPROF=X'13',TSPROF=X'07', * PRIPROT=X'B0',SECPROT=X'B0',COMPROT=X'50B1', TYPE=X'00',PSNDPAC=X'00',SRCVPAC=X'00',SSNDPAC=X'00', RUSIZES=X'8989',PSERVIC=X'060200000000000000002F00'

* *

* Logmode for SNA Services Manager, used with Parallel Sessions SNASVCMG MODEENT LOGMODE=SNASVCMG

CICS/390 Definitions


======================================================================== Host CICS definitions (all host systems are the same) ======================================================================== Connection Group DEscription

: WS02 : LYCCOSV :

CONNECTION IDENTIFIERS Netname INDsys

: CIC40LU0 :

REMOTE ATTRIBUTES REMOTESystem REMOTEName

: :

CONNECTION PROPERTIES ACcessmethod Protocol SInglesess DAtastream RECordformat

: : : : :

Vtam Appc No User U

OPERATIONAL PROPERTIES AUtoconnect INService

: Yes : Yes

SECURITY SEcurityname ATtachsec

: : Local

BINDPassword BINDSecurity

: : No

Page 36 of 47


======================================================================== Sessions Group DEscription

: COS2LYC : LYCCOSV :

SESSION IDENTIFIERS Connection SESSName NETnameq MOdename

: WS02 : : : LU62APPC

SESSION PROPERTIES Protocol : Appc MAximum : 004 , 001 RECEIVEPfx : RECEIVECount : SENDPfx : SENDCount : SENDSize : 04096 RECEIVESize : 0 40 9 6 SESSPriority : 000 Transaction : OPERATOR DEFAULTS OPERId : OPERPriority : 000 OPERRsl : 0 OPERSecurity : 1 PRESET SECURITY USERId : OPERATIONAL PROPERTIES Autoconnect INservice Buildchain USERArealen IOarealen RELreq DIscreq NEPclass

: : : : : : : :

A ll Yes 0 00 00000 , 00000 No Y es 000

RECOVERY RECOVOption

: Sy Sysdefault

RECOVNotify

: N on e

CICS for OS/2 Definitions

Page 37 of 47


Page 38 of 47

======================================================================== CICS OS/2 Definitions WS02 (CICS gateway) ======================================================================== (The TCS entries only show significant details) TCS ======================================================================== System id. . . . . . . . Grou Groupp . . . . . . . . . Connection type. . . . . Connection Priority. Description. . . . . . .

. . . . .

Session count. . . . Session Buffer Size. APPC Details Mode name. . . . . . LU ali alias as Nam Namee . . . Partner LU alias . . Attach security. . . Partner Code Page. .

. . : 04 . . : 04096 . . . . .

. . . . .

. . . . .

: : : : :

: : : : :

CIU7 LYCC LYCCOS OSVV APPC 86 TO HOST REGION CICSU7

LU62APPC CIC4 CIC40L 0LU0 U0 CICSU7 L 00037

Communication Manager/2 Definitions


======================================================================== OS/2 CM definitions from WS02 NEWCICS.NDF ======================================================================== DEFINE_LOCAL_CP FQ_CP_NAME(USIBMSL.CICPU40 ) DESCRIPTION(Created on 08-27-92 at 09:12a) CP_ALI CP_ ALIAS( AS(CIC CICPU4 PU400 ) NAU_ADDRESS(INDEPENDENT_LU) NODE_TYPE(EN) NODE_ID(X'45509') HOST_FP_SUPPORT(YES); DEFINE_LOG DEFINE_LOGICAL_ ICAL_LINK LINK LINK_NAME( LINK_NAME(LINK0 LINK001) 01) DESCRIPTION(Connection to MVS/ESA VTAM) FQ_ADJACENT_CP_NAME(USIBMSL.CDRM01) ADJACENT_NODE_TYPE(LEN) DLC_NAME(IBMTRNET) ADAPTER_NUMBER(0) DESTINATION_ADDRESS(X'400001551043') CP_CP_SESSION_SUPPORT(NO) ACTIVATE_AT_STARTUP(NO) SOLICIT_SSCP_SESSION(NO); DEFINE_LOC DEFINE_LOCAL_LU AL_LU LU_NAME(CIC4 LU_NAME(CIC40LU0) 0LU0) DESCRIPTION(Logical unit to CICS/ESA) NAU_ADDRESS(INDEPENDENT_LU); DEFINE_PAR DEFINE_PARTNER_ TNER_LU LU FQ_PARTNER FQ_PARTNER_LU_NA _LU_NAME(USI ME(USIBMSL.C BMSL.CICSU7 ICSU7 ) PARTNER_LU_ALIAS(CICSU7) PARTNE PAR TNER_L R_LU_U U_UNIN NINTER TERPRE PRETED TED_NA _NAME( ME(CIC CICSU7 SU7 ) MAX_MC_LL_SEND_SIZE(4096) CONV_SECURITY_VERIFICATION(NO) PARALLEL_SESSION_SUPPORT(YES); DEFINE_PARTNER_LU_LOCATION FQ_PARTNER_LU_NAME(USIBMSL.CICSU7) WILDCARD_ENTRY(NO) FQ_OWNING_CP_NAME(USIBMSL.CDRM01) LOCAL_NODE_NN_SERVER(NO);

Page 39 of 47


DEFINE_MODE MODE_NAME(LU62APPC) DESCRIPTION(Created on 08-27-92 at 09:12a) COS_NAME(#CONNECT) DEFAULT_RU_SIZE(NO) MAX_RU_SIZE_UPPER_BOUND(4096) RECEIVE_PACING_WINDOW(4) MAX_NEGOTIABLE_SESSION_LIMIT(10) PLU_MODE_SESSION_LIMIT(4) MIN_CONWINNERS_SOURCE(0); DEFINE_DEFAULTS IMPLICIT_INBOUND_PLU_SUPPORT(NO) DESCRIPTION(Created on 08-27-92 at 09:12a) DEFAULT_MODE_NAME(BLANK) MAX_MC_LL_SEND_SIZE(4096) DIRECTORY_FOR_INBOUND_ATTACHES(*) DEFAULT_TP_OPERATION(NONQUEUED_AM_STARTED) DEFAULT_TP_PROGRAM_TYPE(BACKGROUND) DEFAULT_TP_CONV_SECURITY_RQD(NO) MAX_HELD_ALERTS(10); DEFINE_TP TP_NAME(CPMI) FILESPEC(D:\CICS300\RUNTIME\FAACLPIN.EXE) PARM_STRING(CPMI) CONVERSATION_TYPE(EITHER) CONV_SECURITY_RQD(NO) SYNC_LEVEL(EITHER) TP_OPERATION(NONQUEUED_AM_STARTED) PROGRAM_TYPE(BACKGROUND) RECEIVE_ALLOCATE_TIMEOUT(INFINITE); DEFINE_TP TP_NAME(CRSR) FILESPEC(D:\CICS300\RUNTIME\FAACLPIN.EXE) PARM_STRING(CRSR) CONVERSATION_TYPE(EITHER) CONV_SECURITY_RQD(NO) SYNC_LEVEL(EITHER) TP_OPERATION(NONQUEUED_AM_STARTED) PROGRAM_TYPE(BACKGROUND) RECEIVE_ALLOCATE_TIMEOUT(INFINITE); START_ATTACH_MANAGER; CNOS

LOCAL_LU_ALIAS(CIC40LU0) FQ_PARTNER_LU_NAME(USIBMSL.CICSU7) MODE_NAME(LU62APPC) SET_NEGOTIABLE(YES) PLU_MODE_SESSION_LIMIT(4) MIN_CONWINNERS_SOURCE(0) MIN_CONWINNERS_TARGET(0) AUTO_ACTIVATE(4);

11.4 Security From/To CICS OS/2 and CICS/ESA

Page 40 of 47


Page 41 of 47

Question How do I get CICS for OS/2 and CICS/MVS to pass/accept security credentials from each other? I am currently forced to explicitly sign-on to the target CICS region in order to issue transactions, following a CRTE, for all transactions when going from OS/2 to MVS and for CEDA and other secured transactions when going from MVS to OS/2. I receive a SECG when I try to function ship a WRITEQ TS from OS/2 to MVS. I found in the manuals where it states that if attachsec = verify and Partner LU Conv Sec = Yes, then CICS will ship USERID and PASSWORD with every ISC request (DPL, DPT, Function Ship, Transaction Route). Is this true? What will tell the target region to use the supplied credentials? In all cases we CICS sign-on the source (local) region as administrator (as defined in the SNT) before attempting any ISC trans. There is an SNT entry in both target and source regions for the ID that we are using. The customer uses ACF/2 on the host as the security manager and I see no entries in the ACF/2 logs for our rejected request.

Answer 1. To have CICS OS/2 send userid and password then the TCS entry must specify V (for verify) - and - the connection/sessions definition at the host must also specify Verify. The security definitions for inbound APPC don't really matter since host CICS will always send the already verified flag along with userid and Communications Manager/2 does not do additional verification when that flag is on. 2. CRTE is a special case since it's purpose in life is to make things look like you were connected to the other system - therefore, you must signon at the other system before access is allowed to secured transactions/functions. CRTE between host systems works the same way. Note: The Redbook "APPC Security: MVS/ESA, CICS/ESA, and OS/2" (GG24-3960) gives a very good description of how security works in this environment.

11.5 Security Discussion Lets look at the host side first. Reference: CICS/ESA CICS-RACF Security Guide - SC33-0749-00 Chapter 3.1 Security in the intercommunication environment. page 116 ff The first level of security that can be imployed is the BINDPASSWORD. This is basically a "startup" time security and does not play in any further activity - once we've established out link. We now come to the "run time" security. Here is where we can limit the ability of the partner system to use our resources (programs, transactions, files, and so on). First we have LINK Security. We can establish a security profile (ie what is authorized) for the partner system as a whole. This is defined by either the SECURITYNAME option on the CONNECTION definition or the USERID field of the SESSIONS definitions. Once I have defined the LINK security then I have set the outer bounds for what resources can be used... to use a loose reference to set theory.


Page 42 of 47

Next - and WITHIN the bounds of the LINK Security - we may also restrict the remote user's access by requiring security on incoming ALLOCATEs (ie FMH5). We do this via the ATTACHSEC parms. In effect, this is USER security. I've got some more to say later on the ATTACHSEC options. When using security over an LU6.2 connection, there is a "base" level of security access needed. This base level defines what facilities that any request coming over the link can access. Lets try a small picture:

+-------------------+--------+-+ | AAAA | USR2 | | | +------------+-----+ | | | | LINK | | | | | | +-------+-----+-+| | | | | USR1 | | || | | | | | | || | | | | | | || | | | | | | || | | +----+-------+-----+ || | | | | || | | +-------+-------++ | +------------------------------+

To use a bit of set theory, we have four domains defined, AAAA is all of the secured transactions and resources in our system. LINK is only those resources that anyone connected over the LU 6.2 link can access USR1 those resources that can be accessed by the user USR2 and yet another user.

When a request is checked for authorization, then the intersection of the LINK and USRx domains defines what is and what is not authorized. What you need to do is to determine what all resources belong to the LINK domain (in your case) and define those for the "LINK" userid. The connection between host CICS and CICS OS/2 is treated (for security purposes) just like a connection between two hosts - except that both sides know that Verify can be used.

11.6 Additional background on Security - recommended reading The host CICS Intercommunications Guide has a chapter titled "Security in the intercommunication environment" that should also be read when planning for CICS OS/2 to host CICS security. Pay close attention to the sections that deal with LU6.2. Sections on LU6.1 or IRC do not pertain to CICS OS/2 connections. Also, note the section about dealing with remote users, for example CICS OS/2, which explains what userid is sent with attach requests.

CICS OS/2 TERMINAL CONTROL TABLE (SYSTEM) ATTACH SECURITY The security required during communications with the remote system. There are two levels of security available: L

Use this value to indicate local security, i.e. no userid and password are passed to the host, and the remote system will assume the user already has all authority needed. This is equivalent to the APPC Allocate Security option of NONE.


V

Page 43 of 47

Use this value to indicate verify level security, i.e. both userid and password are passed to the host, and the remote system should sign the user on to verify his/her security. CICS OS/2 will use the Userid and Password from the CICS OS/2 Sign On Table for this function. This is equivalent to the APPC Allocate Security option of PGM (program).

NON-CICS OS/2 DEFINITIONS APPC PARTNER LOGICAL UNIT PROFILE The security defined in this profile describes if the "partner logical unit" is trusted. Typically, a "trusted" partner is a system that provides both authority and authorization checking. In other words, by passing a Userid and Password verification, you provide proof of who you are when you sign-on to the system. In addition, by passing additional checking when requesting specific functions (i.e. Transactions), you have the right to use such functions. Thus, you can be considered as a trusted partner. This also implies, to some extent that the communications connection to the other system is also trusted.

LU-LU SESSION SECURITY Determines whether security will be checked whenever a session is started, i.e. the two logical units are connected. This is equivalent to the host CICS concept of bind time security. Specify YES if bind time security is required and provide a password when prompted, ensuring that it matches that given to the partner system. This will be either in this same field when defining the PARTNER LU ALIAS by which the partner knows this system or, in the case of host CICS, the BINDPASSWORD field in the CONNECTION or LU6.2 Single Session Terminal definition of this LU.

CONVERSATION SECURITY Determines security level on every INCOMING ALLOCATE from the remote system defined by this profile. Specify YES if a check of userid and password is required for every attempt to establish a conversation from a TP on the remote system defined by this profile. An APPC conversation security profile will be required for each valid userid/password combination both here and in the remote system, for example another OS/2 system. If the remote system is host CICS, then do not specify YES here, as host CICS NEVER sends passwords and thus all attempts at communication would be rejected - UNLESS "Conversation Security Verified" is also specified. As noted in the initial reference, host CICS always sends a Userid, but never sends a password. This is equivalent to the APPC ALLOCATE Security option SAME. The SAME option includes the Userid and the Already Verified Flag in the FMH5 (Attach Header).

CONVERSATION SECURITY VERIFIED This option indicates that OS/2 Communi- cations Manager is allowed to accept an incoming FMH5 containing a Userid and the Already Verified Flag as being a secured request. NOTE: Conversation-level security verification is always performed on those requests that include security information.


Page 44 of 47

APPC REMOTELY ATTACHABLE TRANSACTION PROGRAM (TP) PROFILE The security definitions in this profile deal with specific applications (called TP programs). When an Attach request arrives for a specific "TP Program", if security is specified in the RATP defining that program, then the associated security information must be present in the FMH5 or the request will be rejected by OS/2 Communications Manager, regardless of the security level defined for the partner LU making the request.

CONVERSATION SECURITY The security to apply to conversations involving this TP (program). If the TCS entry that defines this system to the CICS OS/2 that was the originator of this attach request specifies an ATTACH SECURITY level of Verify then the userid and password of the user on the originating system will be flowed and selecting YES for this field or the Conversation Security fields of the relevant PARTNER LU PROFILES will enable security checking. An APPC conversation security profile will be required in this system for each valid userid/password combination. For host CICS (since a password is never sent), the YES option will also allow attach requests containing a Userid and the Already Verified flag.

HOST CICS DEFINITION RDO CONNECTION DEFINITION BINDPASSWORD The password to be used for bind time security The password to be used (if any) for LU-LU session security.

ATTACHSEC The level of attach-time user security required for the connection Specify Local for no security or Verify if CM has been configured to send USERID and PASSWORD. Also note that while CICS OS/2 will send userid and password, when the TCS entry specifies security, the host CICS Attachsec option of Identify can also be used. However, the userid and password sent by CICS OS/2 will still be validated. The advantage is that host CICS will check to see if that userid has already been validated, and if so, will not revalidate the request. Please see the host CICS Inter-communications Guide described above.


Page 45 of 47

12.0 Languages 12.1 CICS OS/2 and C++ Question CICS for OS/2 supports the C++ language for CICS application development using Object Oriented methods. These methods - using class libraries to encapsulate function - allow greater re-use of code, which leads to increased programmer productivity, program quality and maintainability. CICS transactions can be written in the C++ language. This means that Object Oriented programs can now access the CICS API. This enhancement brings Customers the increased performance and flexibility of 32 bit CICS applications, plus the benefits of Object Oriented development methods. In addition to C++ support there is also a user exit (exit 27) available which enables multi-session debugging. This facility allows a programmer to review and debug more than one programme concurrently. This is particularly helpful for debugging client/server applications which use the External Call Interface (ECI), or EPI External Presentation Interface (EPI), for communication between the front-end application on the client and the CICS application on the server.


Page 46 of 47

13.0 PEM 13.1 PEM (Password Expiration Management) and CICS/OS2 V3.0 Question I am excited about this new way to interface with PEM at CICS ESA 3.3 without the need to code an APPC unmapped interface. Since our customers are becoming more Client/Server oriented, the need to make this function available without requiring a 3270 interface is important. However, when I read the documentation for the new product (V 3.0), it appears that the new program FAASCPEM was only designed to run at Exit 07 time. Is that true, or can I call this new interface from a regular CICS OS/2 application program running on the OS/2 server? This would give the needed flexibility to inspect information from RACF and determine if the user (a Windows Client) needs to be notified and prompted for a new password. Doing this from Exit 07 limits what can be done with the information returned. I realize that this PEM Verify or Change Password request needs to go via an APPC link with Local Security.

Answer The intent was to make the function callable from anywhere within CICS for OS/2. Look at line 157 of the FAAEXP07.c sample.( Lots of useful bits on setting up the Pem control block in here)

CICSCallPEM(peib,&Pem); So within a CICS application, you have the address of the EIB from EXEC CICS ADDRESS EIB(peib) and you have the layout of Pem in faascpem.h...


Page 47 of 47

14.0 3270 Support 14.1 3270 Support Question Can CICS OS/2 support Structured Field sends to "Set the Reply mode"? I'd like to be able to set the mode to obtain the extended color information when doing a read buffer command.

Answer The CICS OS/2 terminal emulators do not support structured fields. This means that you can not use structured fields to set the reply mode. The CICS OS/2 API also does not support the STRFIELD option on EXEC CICS SEND or EXEC CICS CONVERSE, which the only way structured fields could be sent to the terminal emulators. The highlight option does not affect the colour of the attribute position. It does affect both the foreground and background colour of the text part of the field. CICS OS/2 allows the terminal emulators to define a foreground and background colour for each logical 3270 foreground attribute colour. The background colour *does* affect the attribute position. This is a deliberate slight deviation from the 3270 specification. This is done so that by defining a common background colour for all the 3270 foreground attribute colours, then the background colour of the entire screen can be changed, without leaving ugly black squares for each attribute position. We have customers who require non-black background screen colours. I believe Communication Manager terminals have the same characteristic. Dark fields are the same colour as if the characters in the field were spaces. This allows some tricks such as using Set attribute to paint a hidden field with character attribute highlighting. If this was a password field, then when the user typed a password the character attributes which make the character position coloured are overwritten, and that character position reverts to the colour given by the field attributes. The user can then easily see how many characters have been typed. There has been some discussion as to whether dark fields should be the same colour as the attribute byte (to make them truly hidden). This would prohibit the password field technique. A black colour for a dark field would not be desirable for the same reasons as for background colour above. The best references for native 3270 datastream operation is "3270 Data Stream Programmers Reference", GA23-0059, and CICS OS/2 Application Programming, 65G1540 in the External Presentation Interface (EPI) section. CICS OS/2 is using an ASCII version of the 3270 datastream. I would recommend using DFHBMSCA values of constants, rather than hex representations, to make your CICS programs more portable.

Sending your comments to IBM CICS for OS/2 - Frequently Asked Questions Version 1.1 CA38 If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information in this book and the way in which the information is presented. To request additional publications, or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or to your IBM authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate, without incurring any obligation to you. You can send your comments to IBM in any of the following ways: 

By mail, use the Readers’ Comment Form.



By fax: – From outside the U.K., after your international access code use 44 1962 841409 – From within the U.K., use 01962 841409



Electronically, use the appropriate network ID: – IBMLink: IBMGB(TSCC) – Internet: [email protected]

Whichever you use, ensure that you include:   

The publication number and title The page number or topic to which your comment applies Your name and address/telephone number/fax number/network ID.

Readers’ Comments CICS for OS/2 - Frequently Asked Questions Version 1.1 CA38 Use this form to tell us what you think about this manual. If you have found errors in it, or if you want to express your opinion about it (such as organization, subject matter, appearance) or make suggestions for improvement, this is the form to use. To request additional publications, or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or to your IBM authorized remarketer. This form is provided for comments about the information in this manual and the way it is presented. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. Be sure to print your name and address below if you would like a reply.

Name

Address

Company or Organization Telephone

Email

CICS FAQ

Recommend Documents