CICS for OS/2 - Frequently Asked Questions

Version 1.1

Document: CA38
Issued: 21st March, 1996
Revision Date: 15th December, 1998
Previous Revision Date: 21st March, 1996
Next Review: None

Bill Matthews
IBM Systems Support Center
Roanoke
Dallas
TX, 76262
Revision Date: 15th December, 1998
Document Id: CA38 Page ii
Title: CICS for OS/2 - FAQ

Take 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 comments is provided at the back of this publication. If the form has been removed, 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 without incurring any obligation to you. You may continue to use the information that
you supply.

 Copyright International Business Machines Corporation 1998. All rights 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page iii
Title: CICS for OS/2 - FAQ

Contents
1.0 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2.0 An Historical Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.1 Milestones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3.0 Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.1 Performance of DTP applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Application Design Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Additional Information About the Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.0 Btrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1 Maximum Btrieve filesize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2 Use of Btrieve 6.X in batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.0 COMMAREA and ECI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.1 Allocating storage when using ECI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

6.0 Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

6.1 How is Data Conversion handled? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
ASCII-EBCDIC conversion templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.2 Data Conversion on requests from OS/2 to MVS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.3 Sample Data Conversion Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.4 Data conversion/bit swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.5 Code Pages & Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7.0 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1 What is an Abend AZI6 from SRVTIME???? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

8.0 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
8.1 CICS OS/2 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Revision Date: 15th December, 1998
Document Id: CA38 Page iv
Title: CICS for OS/2 - FAQ

Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

9.0 General Questions about CICS for OS/2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

9.1 Avoiding <SHUTDOWN><CONTINUE> when trapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.2 Maximum length of the COMMAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.3 Maximum number of tasks and minimum free tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
9.4 How to Determine if a program(process) is running under CICS for OS/2 . . . . . . . . . . . . . . . . . . 22
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
9.5 MAX tasks vs Minimum FREE tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
9.6 CICS for OS/2 V2 Durability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
A 1993 Durability Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

10.0 Intersystem Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

11.0 Inter-System Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

11.1 Is Two Phase Commit Supported? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
11.2 Connection Problems between CICS/ESA and CICS for OS/2 . . . . . . . . . . . . . . . . . . . . . . . . 32
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Solution Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
11.3 Configuration Example for CICS for OS/2 to CICS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
VTAM Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
VTAM Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
CICS/390 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
CICS for OS/2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Communication Manager/2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
11.4 Security From/To CICS OS/2 and CICS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Revision Date: 15th December, 1998
Document Id: CA38 Page v
Title: CICS for OS/2 - FAQ

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

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

13.0 PEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
13.1 PEM (Password Expiration Management) and CICS/OS2 V3.0 . . . . . . . . . . . . . . . . . . . . . . . . 46
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

14.0 3270 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

14.1 3270 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Revision Date: 15th December, 1998
Document Id: CA38 Page vi
Title: CICS for OS/2 - FAQ

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 responsi-
bility.

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 environ-
ments 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
Revision Date: 15th December, 1998
Document Id: CA38 Page vii
Title: CICS for OS/2 - FAQ

Summary of Changes
Date Changes
21st March 1996 Initial release as HTML files
16th December 1998 Updated and issue in Adobe Acrobat PDF format
Revision Date: 15th December, 1998
Document Id: CA38 Page viii
Title: CICS for OS/2 - FAQ

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: avail-
able 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,
Revision Date: 15th December, 1998
Document Id: CA38 Page ix
Title: CICS for OS/2 - FAQ

¹ 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
Revision Date: 15th December, 1998
Document Id: CA38 Page x
Title: CICS for OS/2 - FAQ

¹ 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
Revision Date: 15th December, 1998
Document Id: CA38 Page xi
Title: CICS for OS/2 - FAQ

¹ 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 Pub-
lishing, 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
Revision Date: 15th December, 1998
Document Id: CA38 Page 1 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 2 of 47
Title: CICS for OS/2 - FAQ

2.0 An Historical Perspective

2.1 Milestones
PUCICS Announced April 28, 1968
CICS (OS) Program Product Available June 30, 1969
CICS/DOS (Entry & Standard) Announce June 1970
Virtual Storage for S/370 Announce August 1972
CICS/VS (DOS/VS and OS/VS) Announce February 1973
DFH = Destined for Hursley August 1974
CICS/DOS/VS & CICS/OS/VS V1.1.1 Ships May 1975
CICS/DOS/VS 1.2 Announce & Ship February 1976
CICS/OS/VS 1.2 Announce & Ship (VS1) May 1976
CICS/OS/VS 1.2 Announce & Ship (VS2) August 1976
CICS/VS 1.4 Announce March 31, 1978
CICS/VS 1.5 Announce October 2, 1979
CICS/OS/VS 1.5 Ships November 1980
CICS/OS/VS 1.6 Announce July 1982
CICS/DOS/VS 1.6 Announc December 1982
CICS/OS/VS 1.6.1 Announce March 1983
CICS/OS/VS 1.7 Announce July 1985
CICS/CMS Announce October 1985
CICS/DOS/VS 1.7 Announc October 1986
CICS/MVS V2.1 Announce February 17, 1987
CICS/VM V1 & V2 Announce October 20 1987
CICS OS/2 V1 Announce October 25, 1988
CICS/MVS V2.1.1 Announce & Ship (28th) June 20, 1989
CICS/ESA V3.1 Announce June 20, 1989
CICS OS/2 V1.1 August 15, 1989
CICS OS/2 V1.2 Announce November 14, 1989
CICS OS/2 V1.2 Available March 3, 1990
CICS/ESA V3.2 Announce September 4, 1990
CICS/VSE V2.1 Announce September 4, 1990
CICS/MVS V2.1.2 Announce February 1991
CICS/ESA V3.2.1 March 22, 1991
CICS/400 Announce February 18, 1992
CICS/ESA V3.3 Announce March 3, 1992
CICS/ESA V3.3 Available (Provided Bi-directional DPL support) March 27, 1992
CICS/VSE V2.2 Announce June 23, 1992
CICS OS/2 V2 Statement of Direction September 15, 1992
CICS/6000 Announce September 22, 1992
CICS for OS/2 V2 Beta start February 5, 1993
CICS/VSE V2.2 Ship March 12, 1992
CICS for OS/2 V2 Announce March 30, 1993
IBM MQSeries Announcements March 30, 1993
CICS on Windows VT V2 Announce June 8, 1993
CICS for OS/2 V2 Available October 8, 1993
CICS/ESA V4.1 Announce February 1, 1994
CICS Clients Announcements January 26, 1995
CICS/6000 V1R2 January 26, 1995
CICS for OS/2 V2.1 January 26, 1995
Transaction Server for OS/2 Warp V4.0 March 12, 1996
Revision Date: 15th December, 1998
Document Id: CA38 Page 3 of 47
Title: CICS for OS/2 - FAQ

Transaction Server for NT V4 November 11, 1996

Transaction Server for OS/2 Warp V4.1 March 24, 1998
VisualAge CICS for Windows NT V3 (Ships with VisualAge April 17, 1998
Cobol and PL/I V2.2)
CICS Transaction Server for OS/390 V1.1 September 10, 1996
CICS Transaction Server for OS/390 V1.3 September 9, 1998

.
Revision Date: 15th December, 1998
Document Id: CA38 Page 4 of 47
Title: CICS for OS/2 - FAQ

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 applica-
tion 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 5 of 47
Title: CICS for OS/2 - FAQ

loop
: retrieve record from DL/I
(1) : send record to CICS for OS/2
(2) : write record to TS
(3) : 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?
Revision Date: 15th December, 1998
Document Id: CA38 Page 6 of 47
Title: CICS for OS/2 - FAQ

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 interme-
diate 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 Commu-
nications 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 interme-
diate 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 7 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 8 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 9 of 47
Title: CICS for OS/2 - FAQ

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) pro-
vided 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 -
Revision Date: 15th December, 1998
Document Id: CA38 Page 10 of 47
Title: CICS for OS/2 - FAQ

(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 consider-
ations:
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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 11 of 47
Title: CICS for OS/2 - FAQ

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 speci-
fying 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 12 of 47
Title: CICS for OS/2 - FAQ

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 X
DATALEN=32500,LAST=YES

* * 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, X
DATALEN=2
DFHCNV TYPE=FIELD,OFFSET=0002,DATATYP=BINARY, X
DATALEN=2
DFHCNV TYPE=FIELD,OFFSET=0004,DATATYP=CHARACTER, X
DATALEN=75
DFHCNV TYPE=FIELD,OFFSET=0079,DATATYP=BINARY, X
DATALEN=2
DFHCNV TYPE=FIELD,OFFSET=0081,DATATYP=CHARACTER, X
DATALEN=50,LAST=YES
* * 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
Revision Date: 15th December, 1998
Document Id: CA38 Page 13 of 47
Title: CICS for OS/2 - FAQ

* * 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 ?)
Revision Date: 15th December, 1998
Document Id: CA38 Page 14 of 47
Title: CICS for OS/2 - FAQ

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 cur-
rency!).

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 15 of 47
Title: CICS for OS/2 - FAQ

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. CLINTCP=437, SRVERCP=037
b. CLINTCP=437, SRVERCP=285
c. CLINTCP=850, SRVERCP=037
d. CLINTCP=850, SRVERCP=285
2. You will need one or more intermediate servers connected to each host server. Each intermediate server "sup-
ports" a particular ASCII/EBCDIC combination, e.g. 850/285
3. You will need to connect each client to the appropriate intermediate server.
Revision Date: 15th December, 1998
Document Id: CA38 Page 16 of 47
Title: CICS for OS/2 - FAQ

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 ... File Control
IC ... Interval Control
TD ... Transient Data
TS ... Temporary Storage
PC ... 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
Revision Date: 15th December, 1998
Document Id: CA38 Page 17 of 47
Title: CICS for OS/2 - FAQ

*
* 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 ...
Revision Date: 15th December, 1998
Document Id: CA38 Page 18 of 47
Title: CICS for OS/2 - FAQ

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 avail-
ability.

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 19 of 47
Title: CICS for OS/2 - FAQ

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....
Revision Date: 15th December, 1998
Document Id: CA38 Page 20 of 47
Title: CICS for OS/2 - FAQ

9.0 General Questions about CICS for OS/2

9.1 Avoiding <SHUTDOWN><CONTINUE> when trapping

Question
Does anybody know a way to prevent CICS OS/2 from putting out these two buttons with
<SHUTDOWN><CONTINUE> when a transaction is trapping.

When you run a CICS OS/2 remotely and have a couple of hundred kilometers between yourself and the push-
button, 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 21 of 47
Title: CICS for OS/2 - FAQ

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 pre-
determined 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 require-
ments 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 trans-
actions. 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 22 of 47
Title: CICS for OS/2 - FAQ

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
Revision Date: 15th December, 1998
Document Id: CA38 Page 23 of 47
Title: CICS for OS/2 - FAQ

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 ses-
sions, 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 24 of 47
Title: CICS for OS/2 - FAQ

¹ 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 non-
facility 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).
Revision Date: 15th December, 1998
Document Id: CA38 Page 25 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 26 of 47
Title: CICS for OS/2 - FAQ

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 user-
transaction. 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 (docu-
mented 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 proto-
cols. 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 27 of 47
Title: CICS for OS/2 - FAQ

This named TRANSID must be defined in the DPL server region with the same characteristics as the mirror trans-
action 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) PROFILE(DFHCICSA)
PARTITIONSET() STATUS(ENABLED) 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, PRI-
ORITY, TCLASS, etc. to give the applications and systems programmers more control over the application environ-
ment.
Revision Date: 15th December, 1998
Document Id: CA38 Page 28 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 29 of 47
Title: CICS for OS/2 - FAQ

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 con-
nections.

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 terminal entry for the " " " 448

ZCTCNIBD NIB descriptor " " " " " 96
ZCBMSEXT BMS extension " " " " " 48
ZCLUCEXT LU62 extension " " " " " 144

ZCTCTME mode entry for user application sessions 128

ZCTCTTEL terminal entry for user " " 448

ZCTCNIBD NIB descriptor " " " " 96
ZCBMSEXT BMS extension " " " " 48
ZCLUCEXT LU62 extension " " " " 144

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 192

ZCTCTME mode entry for user application session 128
ZCTCTTEL terminal entry for user " " 448
ZCTCNIBD NIB descriptor " " " " 96
ZCBMSEXT BMS extension " " " " 48
ZCLUCEXT LU62 extension " " " " 144

For a total of 1056 per connection/session

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

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 defi-
nition 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 dura-
tion 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 31 of 47
Title: CICS for OS/2 - FAQ

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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 32 of 47
Title: CICS for OS/2 - FAQ

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
Revision Date: 15th December, 1998
Document Id: CA38 Page 33 of 47
Title: CICS for OS/2 - FAQ

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!
Revision Date: 15th December, 1998
Document Id: CA38 Page 34 of 47
Title: CICS for OS/2 - FAQ

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, X
IDBLK=05D, X
IDNUM=45509, X
MAXDATA=1033, X
MAXOUT=7,SSCPFM=USSSCS, X
PACING=0,VPACING=2, X
PUTYPE=2,ISTATUS=ACTIVE

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
Revision Date: 15th December, 1998
Document Id: CA38 Page 35 of 47
Title: CICS for OS/2 - FAQ

=======================================================================
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
Revision Date: 15th December, 1998
Document Id: CA38 Page 36 of 47
Title: CICS for OS/2 - FAQ

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

========================================================================

Connection : WS02
Group : LYCCOSV
DEscription :

CONNECTION IDENTIFIERS

Netname : CIC40LU0
INDsys :

REMOTE ATTRIBUTES

REMOTESystem :
REMOTEName :

CONNECTION PROPERTIES

ACcessmethod : Vtam
Protocol : Appc
SInglesess : No
DAtastream : User
RECordformat : U

OPERATIONAL PROPERTIES

AUtoconnect : Yes
INService : Yes

SECURITY

SEcurityname :
ATtachsec : Local

BINDPassword :
BINDSecurity : No
Revision Date: 15th December, 1998
Document Id: CA38 Page 37 of 47
Title: CICS for OS/2 - FAQ

========================================================================

Sessions : COS2LYC
Group : LYCCOSV
DEscription :

SESSION IDENTIFIERS

Connection : WS02
SESSName :
NETnameq :
MOdename : LU62APPC

SESSION PROPERTIES

Protocol : Appc
MAximum : 004 , 001
RECEIVEPfx :
RECEIVECount :
SENDPfx :
SENDCount :
SENDSize : 04096
RECEIVESize : 04096
SESSPriority : 000
Transaction :
OPERATOR DEFAULTS
OPERId :
OPERPriority : 000
OPERRsl : 0
OPERSecurity : 1
PRESET SECURITY
USERId :

OPERATIONAL PROPERTIES

Autoconnect : All
INservice :
Buildchain : Yes
USERArealen : 000
IOarealen : 00000 , 00000
RELreq : No
DIscreq : Yes
NEPclass : 000

RECOVERY

RECOVOption : Sysdefault

RECOVNotify : None

CICS for OS/2 Definitions

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

========================================================================
CICS OS/2 Definitions WS02 (CICS gateway)

========================================================================
(The TCS entries only show significant details) TCS
========================================================================

System id. . . . . . . . . . : CIU7

Group . . . . . . . . . . . : LYCCOSV
Connection type. . . . . . . : APPC
Connection Priority. . . : 86
Description. . . . . . . . . : TO HOST REGION CICSU7

Session count. . . . . . : 04
Session Buffer Size. . . : 04096
APPC Details
Mode name. . . . . . . . : LU62APPC
LU alias Name . . . . . : CIC40LU0
Partner LU alias . . . . : CICSU7
Attach security. . . . . : L
Partner Code Page. . . . : 00037

Communication Manager/2 Definitions

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

========================================================================
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_ALIAS(CICPU40 )
NAU_ADDRESS(INDEPENDENT_LU)
NODE_TYPE(EN)
NODE_ID(X'45509')
HOST_FP_SUPPORT(YES);

DEFINE_LOGICAL_LINK LINK_NAME(LINK001)
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_LOCAL_LU LU_NAME(CIC40LU0)
DESCRIPTION(Logical unit to CICS/ESA)
NAU_ADDRESS(INDEPENDENT_LU);

DEFINE_PARTNER_LU FQ_PARTNER_LU_NAME(USIBMSL.CICSU7 )
PARTNER_LU_ALIAS(CICSU7)
PARTNER_LU_UNINTERPRETED_NAME(CICSU7 )
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);
Revision Date: 15th December, 1998
Document Id: CA38 Page 40 of 47
Title: CICS for OS/2 - FAQ

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

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

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 Communi-
cations 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 secu-
rity 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 42 of 47
Title: CICS for OS/2 - FAQ

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:

+-------------------+--------+-+ To use a bit of set theory, we
| AAAA | USR2 | | have four domains defined,
| +------------+-----+ | | AAAA is all of the secured
| | LINK | | | | transactions and resources
| | +-------+-----+-+| | in our system.
| | | USR1 | | || | 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 43 of 47
Title: CICS for OS/2 - FAQ

V 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 Pass-
word 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 func-
tions. 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 pass- word. 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 44 of 47
Title: CICS for OS/2 - FAQ

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 Communi-
cations 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.
Revision Date: 15th December, 1998
Document Id: CA38 Page 45 of 47
Title: CICS for OS/2 - FAQ

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 Presen-
tation Interface (EPI), for communication between the front-end application on the client and the CICS application
on the server.
Revision Date: 15th December, 1998
Document Id: CA38 Page 46 of 47
Title: CICS for OS/2 - FAQ

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...
Revision Date: 15th December, 1998
Document Id: CA38 Page 47 of 47
Title: CICS for OS/2 - FAQ

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 Communi-
cation 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, organiza-
tion, 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 for OS/2 - FAQ
CA38
ÉÂÔ