CICS Transaction Server for z/OS

CICS Application Programming GuideVersion 3 Release 1

SC34-6433-06

CICS Transaction Server for z/OS

CICS Application Programming GuideVersion 3 Release 1

SC34-6433-06

Note!Before using this information and the product it supports, be sure to read the general information under Notices on page701.

This edition applies to Version 3 Release 1 of CICS Transaction Server for z/OS, program number 5655-M15, andto all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you areusing the correct edition for the level of the product.

Copyright IBM Corporation 1989, 2010.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xixWhat this book is about . . . . . . . . . . . . . . . . . . . . . xix

Who should read this book . . . . . . . . . . . . . . . . . . . xix

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 3 Release 1 . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 2 Release 3 . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 2 Release 2 . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 2 Release 1 . . . . . xxiChanges for CICS Transaction Server for OS/390, Version 1 Release 3 . . . xxii

Part 1. Writing CICS Applications . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. What is a CICS application? . . . . . . . . . . . . . . . 3CICS programs, transactions and tasks . . . . . . . . . . . . . . . . 3

Chapter 2. CICS programming . . . . . . . . . . . . . . . . . . . 5CICS programming commands . . . . . . . . . . . . . . . . . . . 5

System programming commands. . . . . . . . . . . . . . . . . . 6EXEC interface block (EIB) . . . . . . . . . . . . . . . . . . . . 6

Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Translator Options . . . . . . . . . . . . . . . . . . . . . . . 6

Testing for CICS . . . . . . . . . . . . . . . . . . . . . . . . . 7CICS programming roadmap . . . . . . . . . . . . . . . . . . . . 7

Chapter 3. Language Environment . . . . . . . . . . . . . . . . . 9Language Environment services . . . . . . . . . . . . . . . . . . 10Using Language Environment Abend-handling . . . . . . . . . . . . . 12

User-written Language Environment condition handlers . . . . . . . . . 12Managing Language Environment storage . . . . . . . . . . . . . . . 13Mixing languages in Language Environment . . . . . . . . . . . . . . 13Using Dynamic Link Libraries and Language Environment . . . . . . . . . 15Defining runtime options for Language Environment . . . . . . . . . . . 16

Runtime options in child enclaves . . . . . . . . . . . . . . . . . 18CEEBXITA coding . . . . . . . . . . . . . . . . . . . . . . . 18Determining which options were used . . . . . . . . . . . . . . . 19

Writing a CEEBINT initialization exit for Language Environment . . . . . . . 19

Chapter 4. Programming in COBOL . . . . . . . . . . . . . . . . 21COBOL programming considerations . . . . . . . . . . . . . . . . . 22

COBOL programming restrictions . . . . . . . . . . . . . . . . . 23Language Environment CBLPSHPOP option . . . . . . . . . . . . . 25Using the DL/I CALL interface . . . . . . . . . . . . . . . . . . 25

Considerations for VS COBOL II programs . . . . . . . . . . . . . . 26Using based addressing with COBOL . . . . . . . . . . . . . . . . 27

Using WITH DEBUGGING MODE . . . . . . . . . . . . . . . . . 28Calling subprograms from COBOL. . . . . . . . . . . . . . . . . . 28

Rules for calling subprograms . . . . . . . . . . . . . . . . . . 30Flow of control between programs and subprograms . . . . . . . . . . 32

Using the COBOL2 and COBOL3 translator options . . . . . . . . . . . 34Literals intervening in blank lines . . . . . . . . . . . . . . . . . 35Lower case characters . . . . . . . . . . . . . . . . . . . . . 35Sequence numbers containing any character . . . . . . . . . . . . . 35

Copyright IBM Corp. 1989, 2010 iii

REPLACE statement. . . . . . . . . . . . . . . . . . . . . . 35Batch compilation . . . . . . . . . . . . . . . . . . . . . . . 36Nested programs . . . . . . . . . . . . . . . . . . . . . . . 38Reference modification . . . . . . . . . . . . . . . . . . . . . 41Global variables . . . . . . . . . . . . . . . . . . . . . . . 42Comma and semicolon as delimiters . . . . . . . . . . . . . . . . 42Symbolic character definition . . . . . . . . . . . . . . . . . . . 42

Chapter 5. Programming in C and C++ . . . . . . . . . . . . . . . 43C and C++ programming considerations . . . . . . . . . . . . . . . 43

XPLink considerations for C and C++ programming . . . . . . . . . . 46Passing arguments in C or C++. . . . . . . . . . . . . . . . . . . 49Accessing the EIB. . . . . . . . . . . . . . . . . . . . . . . . 50

Naming EIB fields . . . . . . . . . . . . . . . . . . . . . . . 50Locale support for C and C++ . . . . . . . . . . . . . . . . . . . 51Programming in C++. . . . . . . . . . . . . . . . . . . . . . . 51

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 6. Programming in PL/I . . . . . . . . . . . . . . . . . . 53PL/I programming restrictions . . . . . . . . . . . . . . . . . . . 53Language Environment considerations for PL/I applications . . . . . . . . 54

Chapter 7. Programming in Assembler . . . . . . . . . . . . . . . 57Language Environment considerations for Assembler applications . . . . . . 58Calling Assembler programs . . . . . . . . . . . . . . . . . . . . 60

Part 2. Preparing applications to run . . . . . . . . . . . . . . . . . . . . . 63

Chapter 8. Translation and compilation . . . . . . . . . . . . . . . 67The integrated CICS translator . . . . . . . . . . . . . . . . . . . 67

Using the integrated CICS translator . . . . . . . . . . . . . . . . 68Specifying CICS translator options. . . . . . . . . . . . . . . . . 68

The translation process . . . . . . . . . . . . . . . . . . . . . . 69The CICS-supplied translators . . . . . . . . . . . . . . . . . . . 72

Dynamic invocation of the separate translator . . . . . . . . . . . . 72Using a CICS translator . . . . . . . . . . . . . . . . . . . . . 73Defining translator options . . . . . . . . . . . . . . . . . . . . . 74

Translator options . . . . . . . . . . . . . . . . . . . . . . . 75Translator options table . . . . . . . . . . . . . . . . . . . . . 85

Using COPY statements . . . . . . . . . . . . . . . . . . . . . 86The CICS-supplied interface modules . . . . . . . . . . . . . . . . 86

The EXEC interface modules. . . . . . . . . . . . . . . . . . . 86The CPI Communications interface module . . . . . . . . . . . . . 86The SAA Resource Recovery interface module . . . . . . . . . . . . 86

Using the EXEC interface modules . . . . . . . . . . . . . . . . . 87COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 88PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88C and C++ . . . . . . . . . . . . . . . . . . . . . . . . . 89Assembler language . . . . . . . . . . . . . . . . . . . . . . 89EXAMPLE Assembler language PROGRAM using LEASM . . . . . . . . 89

Chapter 9. Installing application programs . . . . . . . . . . . . . . 99Program installation roadmap . . . . . . . . . . . . . . . . . . . 99

Preparing for program installation . . . . . . . . . . . . . . . . 100Defining MVS residence and addressing modes . . . . . . . . . . . . 100

Establishing a programs addressing mode . . . . . . . . . . . . . 101

iv CICS TS for z/OS: CICS Application Programming Guide

||

||

CICS address space considerations. . . . . . . . . . . . . . . . 101Making programs permanently resident . . . . . . . . . . . . . . 102

Running applications in the link pack area . . . . . . . . . . . . . . 102Running application programs in the RDSAs . . . . . . . . . . . . . 103

Assembler . . . . . . . . . . . . . . . . . . . . . . . . . 103C and C/++. . . . . . . . . . . . . . . . . . . . . . . . . 104COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 104PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Using BMS map sets in application programs . . . . . . . . . . . . . 105Using the CICS-supplied procedures to install application programs . . . . . 106

Installing programs in load library secondary extents . . . . . . . . . 108Including the CICS-supplied interface modules . . . . . . . . . . . . . 108Installing assembler language application programs . . . . . . . . . . . 109Installing COBOL application programs . . . . . . . . . . . . . . . 110

Sample JCL to install COBOL application programs . . . . . . . . . . 111Installing PL/I application programs . . . . . . . . . . . . . . . . . 114

Sample JCL to install PL/I application programs . . . . . . . . . . . 114PL/I procedure with an integrated translator . . . . . . . . . . . . . 115

Installing C application programs . . . . . . . . . . . . . . . . . . 117Sample JCL to install C application programs . . . . . . . . . . . . 118

Using your own job streams . . . . . . . . . . . . . . . . . . . 120Translator requirements . . . . . . . . . . . . . . . . . . . . 120Online programs that use EXEC CICS or EXEC DLI commands . . . . . 120Online programs that use the CALL DLI interface . . . . . . . . . . . 122Batch or BMP programs that use EXEC DLI commands . . . . . . . . 123Batch or BMP programs that use DL/I CALL commands . . . . . . . . 123

Chapter 10. Installing map sets and partition sets . . . . . . . . . . 125Installing map sets . . . . . . .