Mainframe Migration and Upgrade Guide Version 6.0, November 2003 IONA, IONA Technologies, the IONA logo, Orbix, Orbix/E, Orbacus, Artix, Orchestrator, Mobile Orchestrator, Enterprise Integrator, Adaptive Runtime Technology, Transparent Enterprise Deployment, and Total Business Integration are trademarks or registered trademarks of IONA Technologies PLC and/or its subsidiaries. Java and J2EE are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. CORBA is a trademark or registered trademark of the Object Management Group, Inc. in the United States and other countries. All other trademarks that appear herein are the property of their respective owners. While the information in this publication is believed to be accurate, IONA Technologies PLC makes no warranty of any kind to this material including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. IONA Technologies PLC shall not be liable for errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance or use of this material. COPYRIGHT NOTICE No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means, photocopying, recording or otherwise, without prior written consent of IONA Technologies PLC. No third party intellectual property right liability is assumed with respect to the use of the information contained herein. IONA Technologies PLC assumes no responsibility for errors or omissions contained in this book. This publication and features described herein are subject to change without notice. Copyright © 2001, 2003 IONA Technologies PLC. All rights reserved. All products or services mentioned in this manual are covered by the trademarks, service marks, or product names as designated by the companies who market those products. Updated: 27-May-2004 M3169 Contents List of Tables vii Preface ix Part 1 Migrating from 2.3.x Chapter 1 Introduction 3 Overview 4 C++ Applications 5 COBOL and PL/I Applications 6 Chapter 2 Upgrading from an Orbix 2.3.x-Based Solution 9 Chapter 3 C++ Migration Issues 13 C++ Client Migration 14 CORBA Object Location and Binding 15 Naming Service 16 Object-String Conversion 18 resolve_initial_references() 19 Client-Side CORBA Compliancy 20 Callback Objects 22 Orbix-Specific APIs 23 CORBA::Environment Parameter 24 Dynamic Invocation Interface (DII) 25 C++ Server Migration 26 BOA to POA Migration 27 Activation Modes 29 Object/Servant Lifecycles 30 Creating Object References Without Servants 32 Orbix Filters and CORBA 2.3 Alternatives 33 Connection Management 36 iii CONTENTS Exception-Safe Servant Implementations 38 Opaques 39 Orbix 6.x IDL Compiler Output 40 Chapter 4 COBOL Migration Issues 41 Name Mapping Issues 43 Fully Qualified Level 01 Data Names 44 Operation and Level 88 Data Names 48 IDL Constant Definitions Mapped to Fully Qualified Names 52 Derived Interface Names and Fully Qualified Names 57 Numeric Suffixes for Data Names 60 160-Character Limit for String Literals 61 Maximum Length of COBOL Data Names 66 Copybook Names Based on IDL Member Name 69 Introduction to IDL Member Name Migration Issues 70 IDL Member Name Different from its Interface Names 72 More than One Interface in an IDL Member 74 Length of IDL Member Names 76 Name Scoping and the COBOL Compilers 77 Same Container Name Used More than Once 78 Same Fieldname Used More than Once 85 Typecode Name and Length Identifiers 87 Comparing Compiler Output 88 IDL Member Name Different from its Interface Name 89 More than One Interface in an IDL Member 92 Reserved COBOL and OMG Keywords 96 Reserved COBOL Keywords for Module or Interface Names 97 Use of Result as an Argument Name in IDL 98 OMG Mapping Standard for Unions and Exceptions 100 Error Checking and Exceptions 102 COBOL-Specific Issue Relating to Error Checking 103 Error Checking Generation at Runtime for Batch Servers 105 Nested Unions in IDL 106 Mapping for Arrays 111 Working Storage data Items and Group Moves 113 Mapping for IDL type Any 115 CORBA Copybook Additions 117 Parameter Passing of Object References in IDL Operations 118 iv CONTENTS CORBA Object Location and Binding 119 Migration Overview and Example 120 The Naming Service 122 Object-String Conversion 124 API Migration Issues 125 Deprecated APIs 126 ORBEXEC and USER Exception parameters 127 ORBSTAT 128 ORBALLOC 129 COBOL IMS Server Migration Issues 131 Server Mainline Program Requirement for IMS Servers 132 The Linkage Section for IMS Servers 136 Access to the Program Communication Block for IMS Servers 142 Error Checking Generation at Runtime for IMS Servers 145 COBOL IMS Client Migration Issues 146 The Linkage Section for IMS Clients 147 Error Checking Generation at Runtime for IMS Clients 149 Extra Copybooks in Orbix 6.x for IMS Clients 150 COBOL CICS Server Migration Issues 152 Server Mainline Program Requirement for CICS Servers 153 Access to the EXEC Interface Block Data Structure 158 Error Checking Generation at Runtime for CICS Servers 159 COBOL CICS Client Migration Issues 160 Error Checking Generation at Runtime for CICS Clients 161 Extra Copybooks in Orbix Mainframe 6.x 162 Miscellaneous 163 Chapter 5 PL/I Migration Issues 165 Fully Qualified Level 1 Data Names 167 Maximum Length of PL/I Data Names 170 IDL Constant Definitions Mapped to Fully Qualified Names 174 Typecode Name and Length Identifiers 177 Include Member names Based on the IDL Member name 178 IDL Member names Different from Interface Names 181 More than One Interface in an IDL Member 183 Reserved PL/I Keywords for Module or Interface Names 185 Orbix PL/I Error Checking 186 v CONTENTS CORBA Object Location and Binding 187 Migration Overview and Example 188 Naming Service 190 Object-String Conversion 192 CORBA Include Member Additions 193 API Migration Issues 194 Deprecated APIs 195 PODSTAT in Orbix 6.x 196 PODEXEC and User Exception parameters 197 Server Accessor (Z Member) 198 PL/I IMS Server Migration Issues 204 Server Mainline Module 205 Access to the Program Communication Block 210 PL/I IMS Client Migration issues 212 Program Communication Block Definitions Modifications 213 DLIDATA Include Member Modifications 216 Error Checking Generation at Runtime for IMS Clients 217 PL/I CICS Server Migration Issues 218 Server Mainline Program Requirements for CICS Servers 219 Access to the EXEC Interface Block Data Structure 224 PL/I CICS Client Migration Issues 225 Miscellaneous 226 Chapter 6 Common Migration Issues 227 IDL Fixed Type Definitions 228 IDL Defined in Fixed Block Data Sets 229 Administrative Tools 230 Diagnostic Output 232 Use of the Orbix Protocol 234 imsraw and cicsraw IDL changes 235 vi CONTENTS Part 2 Migrating from 5.x Chapter 7 Upgrading from Mainframe Edition 5.x 239 Chapter 8 Orbix Mainframe Configuration 243 Index 249 vii CONTENTS viii List of Tables Table 1: Migration Possibilities for OS/390 4 Table 2: POA Policy Types and Their Values for Callback Objects 22 Table 3: C++ Compiler Output Comparison for OS/390 USS 40 Table 4: COBOL Compiler Output for IDL Constant Definitions 52 Table 5: COBOL Compiler Output for GRID IDL Member 75 Table 6: COBOL Mapping Changes for IDL Data Types 113 Table 7: Deprecated COBOL APIs and Their Replacements 126 Table 8: ORBALLOC and Mapping Changes for IDL Data Types 129 Table 9: Extra Copybooks that ship with Orbix 6.x 150 Table 10: Extra Copybooks that ship with Orbix 6.x 162 Table 11: PL/I Compiler Output for IDL Constant Definitions 174 Table 12: PL/I Compiler Output Comparison GRID Include Member Names 181 Table 13: PL/I Compiler Deprecated IDL Generated Members and Their Replacements 184 Table 14: Deprecated PL/I APIs and Their Replacements 195 vii LIST OF TABLES viii Preface Overview This guide describes the issues that surround the migration of Orbix for OS/390 applications from earlier IONA mainframe solutions to an Orbix Mainframe 6.x solution. The bulk of this guide (Part 1) focuses on migrating from Orbix 2.3.x-based solutions, because much fewer changes are required to migrate from Orbix E2A Mainframe Edition 5.x. Part 2 describes Orbix E2A Mainframe Edition 5.x migration issues. This guide describes migration issues relating specifically to COBOL and PL/I applications in a native OS/390 environment, and to C++ applications in both a native OS/390 and UNIX System Services environment. Support If you need help with this or any other IONA products, contact IONA at [email protected]. Comments on IONA documentation can be sent to [email protected]. Audience This guide is intended for application programmers who want to migrate their Orbix for OS/390 applications from earlier IONA mainframe solutions to an Orbix Mainframe 6.x solution. It is assumed that the reader is familiar with the basic concepts of CORBA 2.3. Related Documentation Orbix Mainframe 6.0 documentation includes the following related guides: • CORBA Programmer’s Guide, C++ • CORBA Programmer’s Reference, C++ • COBOL Programmer’s Guide and Reference • PL/I Programmer’s Guide and Reference ix PREFACE • CORBA Administrator’s Guide • IMS Adapters Administrator’s Guide • CICS Adapters Administrator’s Guide • Mainframe CORBA Concepts Guide • Mainframe Security Guide • Mainframe Management Guide For the latest version of all IONA product documentation, see the IONA web site at: http://www.iona.com/support/docs Organization of this Guide This guide is divided into two main parts as follows: Part 1, “Migrating from 2.3.x” Chapter 1, “Introduction” This chapter introduces the main differences between the Orbix 2.3.x-based IONA mainframe solutions and Orbix Mainframe 6.x. It also summarizes the main migration impact involved. Chapter 2, “Upgrading from an Orbix 2.3.x-Based Solution” This chapter outlines the requirements for upgrading from an Orbix 2.3.x-based IONA mainframe solution to Orbix Mainframe 6.x.