webMethods EntireX EntireX z/OS CICS® RPC Server Version 9.5 SP1 November 2013 This document applies to webMethods EntireX Version 9.5 SP1. Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions. Copyright © 1997-2013 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.. The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or Software AG USA, Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned herein may be trademarks of their respective owners. Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at http://documentation.softwareag.com/legal/. Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product doc- umentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s). This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License Texts, Copyright Notices and Disclaimers of Third-Party Products". This document is part of the product documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s). Document ID: EXX-CICSRPC-95SP1-20140628 Table of Contents EntireX z/OS CICS® RPC Server ....................................................................................... v 1 Introduction to CICS RPC Server .................................................................................... 1 Inside the RPC Server ................................................................................................ 2 Impersonation ............................................................................................................ 9 Usage of SVM Files .................................................................................................. 10 Interface Types Supported by the RPC Server ......................................................... 11 Automatic Syncpoint Handling ............................................................................... 11 Scenario I: Calling an Existing COBOL Server ........................................................ 11 Scenario II: Writing a New COBOL Server .............................................................. 12 Scenario III: Calling an Existing PL/I Server ............................................................ 12 Scenario IV: Writing a New PL/I Server ................................................................... 13 Returning Application Error Codes from a Server to a Client ................................ 13 2 Administering the CICS RPC Server ............................................................................. 15 Customizing the RPC Server .................................................................................... 16 Configuring the RPC Server ..................................................................................... 18 Locating and Calling the Target Server .................................................................... 26 Using SSL or TLS with the RPC Server .................................................................... 28 RPC User Exits ......................................................................................................... 28 Autostart/Stop during CICS Start/Shutdown .......................................................... 33 Multiple RPC Servers in the same CICS .................................................................. 34 3 RPC Online Maintenance Facility ................................................................................. 35 Monitoring the RPC Server ...................................................................................... 36 Starting the RPC Server ............................................................................................ 38 Pinging the RPC Server ............................................................................................ 39 Stopping the RPC Server .......................................................................................... 39 Modifying Parameters of the RPC Server ................................................................ 39 Activating Tracing for the RPC Server ..................................................................... 40 Console Commands for the RPC Server .................................................................. 40 4 Deployment Service ...................................................................................................... 43 Introduction .............................................................................................................. 44 Scope ........................................................................................................................ 45 Enabling the Deployment Service ............................................................................ 45 Disabling the Deployment Service ........................................................................... 46 5 Handling SVM Files ...................................................................................................... 47 SVM Files in the EntireX Workbench ....................................................................... 48 SVM Files in the RPC Server .................................................................................... 48 Source Control of SVM Files .................................................................................... 49 Change Management of SVM Files .......................................................................... 49 Compare SVM Files .................................................................................................. 49 List Deployed SVM Files .......................................................................................... 49 Check if an SVM File Revision has been Deployed ................................................. 50 Access Control: Secure SVM File Deployment ........................................................ 50 Ensure that Deployed SVM Files are not Overwritten ............................................ 50 iii EntireX z/OS CICS® RPC Server When is an SVM File Required? ............................................................................... 51 Is There a Way to Smoothly Introduce SVM Files? .................................................. 53 iv EntireX z/OS CICS® RPC Server EntireX z/OS CICS® RPC Server The EntireX z/OS CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS under CICS. It supports the programming languages COBOL and PL/I. ■ For COBOL, it works together with the COBOL Wrapper and IDL Extractor for COBOL. ■ For PL/I, it works together with the PL/I Wrapper and IDL Extractor for PL/I. Supported compilers are listed under z/OS Prerequisites in the EntireX Release Notes in the EntireX Release Notes. v vi 1 Introduction to CICS RPC Server ■ Inside the RPC Server ....................................................................................................................... 2 ■ Impersonation .................................................................................................................................. 9 ■ Usage of SVM Files ......................................................................................................................... 10 ■ Interface Types Supported by the RPC Server ...................................................................................... 11 ■ Automatic Syncpoint Handling ........................................................................................................... 11 ■ Scenario I: Calling an Existing COBOL Server ....................................................................................... 11 ■ Scenario II: Writing a New COBOL Server ............................................................................................ 12 ■ Scenario III: Calling an Existing PL/I Server .......................................................................................... 12 ■ Scenario IV: Writing a New PL/I Server ................................................................................................ 13 ■ Returning Application Error Codes from a Server to a Client ..................................................................... 13 1 Introduction to CICS RPC Server The EntireX z/OS CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS under CICS. It supports the programming languages COBOL and PL/I. Inside the RPC Server ■ Worker Models ■ Inbuilt Services 2 EntireX z/OS CICS® RPC Server Introduction to CICS RPC Server ■ User Exits Worker Models RPC requests are worked off inside the RPC server in worker tasks, which are controlled by a main task. Every RPC request occupies during its processing a worker task. If you are using RPC conversations, each RPC conversation requires its own task during the lifetime of the conversation. The CICS RPC Server provides two worker models: ■ FIXED The fixed model creates a fixed number of worker tasks. The number of worker tasks (defined with ERXMAIN macro parameter MINW) does not increase